git.ipfire.org Git - thirdparty/gcc.git/blob

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _back-end:
   7
   8 Anatomy of a Target Back End
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 A back end for a target architecture in GCC has the following parts:
  12
  13 * A directory :samp:`{machine}` under :samp:`gcc/config`, containing a
  14   machine description :samp:`{machine}.md` file (see :ref:`machine-desc`), header files :samp:`{machine}.h` and
  15   :samp:`{machine}-protos.h` and a source file :samp:`{machine}.c`
  16   (see :ref:`target-macros`),
  17   possibly a target Makefile fragment :samp:`t-{machine}`
  18   (see :ref:`target-fragment`), and maybe
  19   some other files.  The names of these files may be changed from the
  20   defaults given by explicit specifications in :samp:`config.gcc`.
  21
  22 * If necessary, a file :samp:`{machine}-modes.def` in the
  23   :samp:`{machine}` directory, containing additional machine modes to
  24   represent condition codes.  See :ref:`condition-code`, for further details.
  25
  26 * An optional :samp:`{machine}.opt` file in the :samp:`{machine}`
  27   directory, containing a list of target-specific options.  You can also
  28   add other option files using the ``extra_options`` variable in
  29   :samp:`config.gcc`.  See :ref:`options`.
  30
  31 * Entries in :samp:`config.gcc` (see :ref:`system-config`) for the systems with this target
  32   architecture.
  33
  34 * Documentation in :samp:`gcc/doc/invoke.texi` for any command-line
  35   options supported by this target (see :ref:`run-time-target`).  This means both entries in the summary table
  36   of options and details of the individual options.
  37
  38 * Documentation in :samp:`gcc/doc/extend.texi` for any target-specific
  39   attributes supported (see :ref:`target-attributes`), including where the
  40   same attribute is already supported on some targets, which are
  41   enumerated in the manual.
  42
  43 * Documentation in :samp:`gcc/doc/extend.texi` for any target-specific
  44   pragmas supported.
  45
  46 * Documentation in :samp:`gcc/doc/extend.texi` of any target-specific
  47   built-in functions supported.
  48
  49 * Documentation in :samp:`gcc/doc/extend.texi` of any target-specific
  50   format checking styles supported.
  51
  52 * Documentation in :samp:`gcc/doc/md.texi` of any target-specific
  53   constraint letters (see :ref:`machine-constraints`).
  54
  55 * A note in :samp:`gcc/doc/contrib.texi` under the person or people who
  56   contributed the target support.
  57
  58 * Entries in :samp:`gcc/doc/install.texi` for all target triplets
  59   supported with this target architecture, giving details of any special
  60   notes about installation for this target, or saying that there are no
  61   special notes if there are none.
  62
  63 * Possibly other support outside the :samp:`gcc` directory for runtime
  64   libraries.  The ``libstdc++`` porting
  65   manual needs to be installed as info for this to work, or to be a
  66   chapter of this manual.
  67
  68   .. todo:: reference docs for this
  69
  70 The :samp:`{machine}.h` header is included very early in GCC's
  71 standard sequence of header files, while :samp:`{machine}-protos.h`
  72 is included late in the sequence.  Thus :samp:`{machine}-protos.h`
  73 can include declarations referencing types that are not defined when
  74 :samp:`{machine}.h` is included, specifically including those from
  75 :samp:`rtl.h` and :samp:`tree.h`.  Since both RTL and tree types may not
  76 be available in every context where :samp:`{machine}-protos.h` is
  77 included, in this file you should guard declarations using these types
  78 inside appropriate ``#ifdef RTX_CODE`` or ``#ifdef TREE_CODE``
  79 conditional code segments.
  80
  81 If the backend uses shared data structures that require ``GTY`` markers
  82 for garbage collection (see :ref:`type-information`), you must declare those
  83 in :samp:`{machine}.h` rather than :samp:`{machine}-protos.h`.
  84 Any definitions required for building libgcc must also go in
  85 :samp:`{machine}.h`.
  86
  87 GCC uses the macro ``IN_TARGET_CODE`` to distinguish between
  88 machine-specific :samp:`.c` and :samp:`.cc` files and
  89 machine-independent :samp:`.c` and :samp:`.cc` files.  Machine-specific
  90 files should use the directive:
  91
  92 .. code-block:: c++
  93
  94   #define IN_TARGET_CODE 1
  95
  96 before including ``config.h``.
  97
  98 If the back end is added to the official GCC source repository, the
  99 following are also necessary:
 100
 101 * An entry for the target architecture in :samp:`readings.html` on the
 102   GCC web site, with any relevant links.
 103
 104 * Details of the properties of the back end and target architecture in
 105   :samp:`backends.html` on the GCC web site.
 106
 107 * A news item about the contribution of support for that target
 108   architecture, in :samp:`index.html` on the GCC web site.
 109
 110 * Normally, one or more maintainers of that target listed in
 111   :samp:`MAINTAINERS`.  Some existing architectures may be unmaintained,
 112   but it would be unusual to add support for a target that does not have
 113   a maintainer when support is added.
 114
 115 * Target triplets covering all :samp:`config.gcc` stanzas for the target,
 116   in the list in :samp:`contrib/config-list.mk`.