gcc/doc/gccint/machine-descriptions/defining-rtl-sequences-for-code-generation.rst

   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 .. index:: expander definitions, code generation RTL sequences, defining RTL sequences for code generation
   7
   8 .. _expander-definitions:
   9
  10 Defining RTL Sequences for Code Generation
  11 ******************************************
  12
  13 On some target machines, some standard pattern names for RTL generation
  14 cannot be handled with single insn, but a sequence of RTL insns can
  15 represent them.  For these target machines, you can write a
  16 ``define_expand`` to specify how to generate the sequence of RTL.
  17
  18 .. index:: define_expand
  19
  20 A ``define_expand`` is an RTL expression that looks almost like a
  21 ``define_insn`` ; but, unlike the latter, a ``define_expand`` is used
  22 only for RTL generation and it can produce more than one RTL insn.
  23
  24 A ``define_expand`` RTX has four operands:
  25
  26 * The name.  Each ``define_expand`` must have a name, since the only
  27   use for it is to refer to it by name.
  28
  29 * The RTL template.  This is a vector of RTL expressions representing
  30   a sequence of separate instructions.  Unlike ``define_insn``, there
  31   is no implicit surrounding ``PARALLEL``.
  32
  33 * The condition, a string containing a C expression.  This expression is
  34   used to express how the availability of this pattern depends on
  35   subclasses of target machine, selected by command-line options when GCC
  36   is run.  This is just like the condition of a ``define_insn`` that
  37   has a standard name.  Therefore, the condition (if present) may not
  38   depend on the data in the insn being matched, but only the
  39   target-machine-type flags.  The compiler needs to test these conditions
  40   during initialization in order to learn exactly which named instructions
  41   are available in a particular run.
  42
  43 * The preparation statements, a string containing zero or more C
  44   statements which are to be executed before RTL code is generated from
  45   the RTL template.
  46
  47   Usually these statements prepare temporary registers for use as
  48   internal operands in the RTL template, but they can also generate RTL
  49   insns directly by calling routines such as ``emit_insn``, etc.
  50   Any such insns precede the ones that come from the RTL template.
  51
  52 * Optionally, a vector containing the values of attributes. See :ref:`insn-attributes`.
  53
  54 Every RTL insn emitted by a ``define_expand`` must match some
  55 ``define_insn`` in the machine description.  Otherwise, the compiler
  56 will crash when trying to generate code for the insn or trying to optimize
  57 it.
  58
  59 The RTL template, in addition to controlling generation of RTL insns,
  60 also describes the operands that need to be specified when this pattern
  61 is used.  In particular, it gives a predicate for each operand.
  62
  63 A true operand, which needs to be specified in order to generate RTL from
  64 the pattern, should be described with a ``match_operand`` in its first
  65 occurrence in the RTL template.  This enters information on the operand's
  66 predicate into the tables that record such things.  GCC uses the
  67 information to preload the operand into a register if that is required for
  68 valid RTL code.  If the operand is referred to more than once, subsequent
  69 references should use ``match_dup``.
  70
  71 The RTL template may also refer to internal 'operands' which are
  72 temporary registers or labels used only within the sequence made by the
  73 ``define_expand``.  Internal operands are substituted into the RTL
  74 template with ``match_dup``, never with ``match_operand``.  The
  75 values of the internal operands are not passed in as arguments by the
  76 compiler when it requests use of this pattern.  Instead, they are computed
  77 within the pattern, in the preparation statements.  These statements
  78 compute the values and store them into the appropriate elements of
  79 ``operands`` so that ``match_dup`` can find them.
  80
  81 There are two special macros defined for use in the preparation statements:
  82 ``DONE`` and ``FAIL``.  Use them with a following semicolon,
  83 as a statement.
  84
  85 .. index:: DONE
  86
  87 .. envvar:: DONE
  88
  89   Use the ``DONE`` macro to end RTL generation for the pattern.  The
  90   only RTL insns resulting from the pattern on this occasion will be
  91   those already emitted by explicit calls to ``emit_insn`` within the
  92   preparation statements; the RTL template will not be generated.
  93
  94 .. envvar:: FAIL
  95
  96   Make the pattern fail on this occasion.  When a pattern fails, it means
  97   that the pattern was not truly available.  The calling routines in the
  98   compiler will try other strategies for code generation using other patterns.
  99
 100   Failure is currently supported only for binary (addition, multiplication,
 101   shifting, etc.) and bit-field (``extv``, ``extzv``, and ``insv``)
 102   operations.
 103
 104 If the preparation falls through (invokes neither ``DONE`` nor
 105 ``FAIL``), then the ``define_expand`` acts like a
 106 ``define_insn`` in that the RTL template is used to generate the
 107 insn.
 108
 109 The RTL template is not used for matching, only for generating the
 110 initial insn list.  If the preparation statement always invokes
 111 ``DONE`` or ``FAIL``, the RTL template may be reduced to a simple
 112 list of operands, such as this example:
 113
 114 .. code-block::
 115
 116   (define_expand "addsi3"
 117     [(match_operand:SI 0 "register_operand" "")
 118      (match_operand:SI 1 "register_operand" "")
 119      (match_operand:SI 2 "register_operand" "")]
 120     ""
 121     "
 122   {
 123     handle_add (operands[0], operands[1], operands[2]);
 124     DONE;
 125   }")
 126
 127 Here is an example, the definition of left-shift for the SPUR chip:
 128
 129 .. code-block::
 130
 131   (define_expand "ashlsi3"
 132     [(set (match_operand:SI 0 "register_operand" "")
 133           (ashift:SI
 134             (match_operand:SI 1 "register_operand" "")
 135             (match_operand:SI 2 "nonmemory_operand" "")))]
 136     ""
 137     "
 138   {
 139     if (GET_CODE (operands[2]) != CONST_INT
 140         || (unsigned) INTVAL (operands[2]) > 3)
 141       FAIL;
 142   }")
 143
 144 This example uses ``define_expand`` so that it can generate an RTL insn
 145 for shifting when the shift-count is in the supported range of 0 to 3 but
 146 fail in other cases where machine insns aren't available.  When it fails,
 147 the compiler tries another strategy using different patterns (such as, a
 148 library call).
 149
 150 If the compiler were able to handle nontrivial condition-strings in
 151 patterns with names, then it would be possible to use a
 152 ``define_insn`` in that case.  Here is another case (zero-extension
 153 on the 68000) which makes more use of the power of ``define_expand`` :
 154
 155 .. code-block::
 156
 157   (define_expand "zero_extendhisi2"
 158     [(set (match_operand:SI 0 "general_operand" "")
 159           (const_int 0))
 160      (set (strict_low_part
 161             (subreg:HI
 162               (match_dup 0)
 163               0))
 164           (match_operand:HI 1 "general_operand" ""))]
 165     ""
 166     "operands[1] = make_safe_from (operands[1], operands[0]);")
 167
 168 .. index:: make_safe_from
 169
 170 Here two RTL insns are generated, one to clear the entire output operand
 171 and the other to copy the input operand into its low half.  This sequence
 172 is incorrect if the input operand refers to [the old value of] the output
 173 operand, so the preparation statement makes sure this isn't so.  The
 174 function ``make_safe_from`` copies the ``operands[1]`` into a
 175 temporary register if it refers to ``operands[0]``.  It does this
 176 by emitting another RTL insn.
 177
 178 Finally, a third example shows the use of an internal operand.
 179 Zero-extension on the SPUR chip is done by ``and`` -ing the result
 180 against a halfword mask.  But this mask cannot be represented by a
 181 ``const_int`` because the constant value is too large to be legitimate
 182 on this machine.  So it must be copied into a register with
 183 ``force_reg`` and then the register used in the ``and``.
 184
 185 .. code-block::
 186
 187   (define_expand "zero_extendhisi2"
 188     [(set (match_operand:SI 0 "register_operand" "")
 189           (and:SI (subreg:SI
 190                     (match_operand:HI 1 "register_operand" "")
 191                     0)
 192                   (match_dup 2)))]
 193     ""
 194     "operands[2]
 195        = force_reg (SImode, GEN_INT (65535)); ")
 196
 197 .. note::
 198
 199   If the ``define_expand`` is used to serve a
 200   standard binary or unary arithmetic operation or a bit-field operation,
 201   then the last insn it generates must not be a ``code_label``,
 202   ``barrier`` or ``note``.  It must be an ``insn``,
 203   ``jump_insn`` or ``call_insn``.  If you don't need a real insn
 204   at the end, emit an insn to copy the result of the operation into
 205   itself.  Such an insn will generate no code, but it can avoid problems
 206   in the compiler.