gcc/doc/gccint/machine-descriptions/c-statements-for-assembler-output.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:: output statements, C statements for assembler output, generating assembler output
   7
   8 .. _output-statement:
   9
  10 C Statements for Assembler Output
  11 *********************************
  12
  13 Often a single fixed template string cannot produce correct and efficient
  14 assembler code for all the cases that are recognized by a single
  15 instruction pattern.  For example, the opcodes may depend on the kinds of
  16 operands; or some unfortunate combinations of operands may require extra
  17 machine instructions.
  18
  19 If the output control string starts with a :samp:`@`, then it is actually
  20 a series of templates, each on a separate line.  (Blank lines and
  21 leading spaces and tabs are ignored.)  The templates correspond to the
  22 pattern's constraint alternatives (see :ref:`multi-alternative`).  For example,
  23 if a target machine has a two-address add instruction :samp:`addr` to add
  24 into a register and another :samp:`addm` to add a register to memory, you
  25 might write this pattern:
  26
  27 .. code-block::
  28
  29   (define_insn "addsi3"
  30     [(set (match_operand:SI 0 "general_operand" "=r,m")
  31           (plus:SI (match_operand:SI 1 "general_operand" "0,0")
  32                    (match_operand:SI 2 "general_operand" "g,r")))]
  33     ""
  34     "@
  35      addr %2,%0
  36      addm %2,%0")
  37
  38 .. index:: * in template, asterisk in template
  39
  40 If the output control string starts with a :samp:`*`, then it is not an
  41 output template but rather a piece of C program that should compute a
  42 template.  It should execute a ``return`` statement to return the
  43 template-string you want.  Most such templates use C string literals, which
  44 require doublequote characters to delimit them.  To include these
  45 doublequote characters in the string, prefix each one with ``\``.
  46
  47 If the output control string is written as a brace block instead of a
  48 double-quoted string, it is automatically assumed to be C code.  In that
  49 case, it is not necessary to put in a leading asterisk, or to escape the
  50 doublequotes surrounding C string literals.
  51
  52 The operands may be found in the array ``operands``, whose C data type
  53 is ``rtx []``.
  54
  55 It is very common to select different ways of generating assembler code
  56 based on whether an immediate operand is within a certain range.  Be
  57 careful when doing this, because the result of ``INTVAL`` is an
  58 integer on the host machine.  If the host machine has more bits in an
  59 ``int`` than the target machine has in the mode in which the constant
  60 will be used, then some of the bits you get from ``INTVAL`` will be
  61 superfluous.  For proper results, you must carefully disregard the
  62 values of those bits.
  63
  64 .. index:: output_asm_insn
  65
  66 It is possible to output an assembler instruction and then go on to output
  67 or compute more of them, using the subroutine ``output_asm_insn``.  This
  68 receives two arguments: a template-string and a vector of operands.  The
  69 vector may be ``operands``, or it may be another array of ``rtx``
  70 that you declare locally and initialize yourself.
  71
  72 .. index:: which_alternative
  73
  74 When an insn pattern has multiple alternatives in its constraints, often
  75 the appearance of the assembler code is determined mostly by which alternative
  76 was matched.  When this is so, the C code can test the variable
  77 ``which_alternative``, which is the ordinal number of the alternative
  78 that was actually satisfied (0 for the first, 1 for the second alternative,
  79 etc.).
  80
  81 For example, suppose there are two opcodes for storing zero, :samp:`clrreg`
  82 for registers and :samp:`clrmem` for memory locations.  Here is how
  83 a pattern could use ``which_alternative`` to choose between them:
  84
  85 .. code-block::
  86
  87   (define_insn ""
  88     [(set (match_operand:SI 0 "general_operand" "=r,m")
  89           (const_int 0))]
  90     ""
  91     {
  92     return (which_alternative == 0
  93             ? "clrreg %0" : "clrmem %0");
  94     })
  95
  96 The example above, where the assembler code to generate was
  97 *solely* determined by the alternative, could also have been specified
  98 as follows, having the output control string start with a :samp:`@`:
  99
 100 .. code-block::
 101
 102   (define_insn ""
 103     [(set (match_operand:SI 0 "general_operand" "=r,m")
 104           (const_int 0))]
 105     ""
 106     "@
 107      clrreg %0
 108      clrmem %0")
 109
 110 If you just need a little bit of C code in one (or a few) alternatives,
 111 you can use :samp:`*` inside of a :samp:`@` multi-alternative template:
 112
 113 .. code-block::
 114
 115   (define_insn ""
 116     [(set (match_operand:SI 0 "general_operand" "=r,<,m")
 117           (const_int 0))]
 118     ""
 119     "@
 120      clrreg %0
 121      * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
 122      clrmem %0")