Anatomy of a Target Back End#

A back end for a target architecture in GCC has the following parts:

  • A directory machine under gcc/config, containing a machine description machine.md file (see Machine Descriptions), header files machine.h and machine-protos.h and a source file machine.c (see Target Description Macros and Functions), possibly a target Makefile fragment t-machine (see Target Makefile Fragments), and maybe some other files. The names of these files may be changed from the defaults given by explicit specifications in config.gcc.

  • If necessary, a file machine-modes.def in the machine directory, containing additional machine modes to represent condition codes. See Condition Code Status, for further details.

  • An optional machine.opt file in the machine directory, containing a list of target-specific options. You can also add other option files using the extra_options variable in config.gcc. See Option specification files.

  • Entries in config.gcc (see The config.build; config.host; and config.gcc Files) for the systems with this target architecture.

  • Documentation in gcc/doc/invoke.texi for any command-line options supported by this target (see Run-time Target Specification). This means both entries in the summary table of options and details of the individual options.

  • Documentation in gcc/doc/extend.texi for any target-specific attributes supported (see Defining target-specific uses of __attribute__), including where the same attribute is already supported on some targets, which are enumerated in the manual.

  • Documentation in gcc/doc/extend.texi for any target-specific pragmas supported.

  • Documentation in gcc/doc/extend.texi of any target-specific built-in functions supported.

  • Documentation in gcc/doc/extend.texi of any target-specific format checking styles supported.

  • Documentation in gcc/doc/md.texi of any target-specific constraint letters (see Constraints for Particular Machines).

  • A note in gcc/doc/contrib.texi under the person or people who contributed the target support.

  • Entries in gcc/doc/install.texi for all target triplets supported with this target architecture, giving details of any special notes about installation for this target, or saying that there are no special notes if there are none.

  • Possibly other support outside the gcc directory for runtime libraries. The libstdc++ porting manual needs to be installed as info for this to work, or to be a chapter of this manual.

    Todo

    reference docs for this

The machine.h header is included very early in GCC’s standard sequence of header files, while machine-protos.h is included late in the sequence. Thus machine-protos.h can include declarations referencing types that are not defined when machine.h is included, specifically including those from rtl.h and tree.h. Since both RTL and tree types may not be available in every context where machine-protos.h is included, in this file you should guard declarations using these types inside appropriate #ifdef RTX_CODE or #ifdef TREE_CODE conditional code segments.

If the backend uses shared data structures that require GTY markers for garbage collection (see Memory Management and Type Information), you must declare those in machine.h rather than machine-protos.h. Any definitions required for building libgcc must also go in machine.h.

GCC uses the macro IN_TARGET_CODE to distinguish between machine-specific .c and .cc files and machine-independent .c and .cc files. Machine-specific files should use the directive:

#define IN_TARGET_CODE 1

before including config.h.

If the back end is added to the official GCC source repository, the following are also necessary:

  • An entry for the target architecture in readings.html on the GCC web site, with any relevant links.

  • Details of the properties of the back end and target architecture in backends.html on the GCC web site.

  • A news item about the contribution of support for that target architecture, in index.html on the GCC web site.

  • Normally, one or more maintainers of that target listed in MAINTAINERS. Some existing architectures may be unmaintained, but it would be unusual to add support for a target that does not have a maintainer when support is added.

  • Target triplets covering all config.gcc stanzas for the target, in the list in contrib/config-list.mk.