gcc/doc/gccint/machine-descriptions/conditional-execution.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:: conditional execution, predication
   7
   8 .. _conditional-execution:
   9
  10 Conditional Execution
  11 *********************
  12
  13 A number of architectures provide for some form of conditional
  14 execution, or predication.  The hallmark of this feature is the
  15 ability to nullify most of the instructions in the instruction set.
  16 When the instruction set is large and not entirely symmetric, it
  17 can be quite tedious to describe these forms directly in the
  18 :samp:`.md` file.  An alternative is the ``define_cond_exec`` template.
  19
  20 .. index:: define_cond_exec
  21
  22 .. code-block::
  23
  24   (define_cond_exec
  25     [predicate-pattern]
  26     "condition"
  27     "output-template"
  28     "optional-insn-attribues")
  29
  30 :samp:`{predicate-pattern}` is the condition that must be true for the
  31 insn to be executed at runtime and should match a relational operator.
  32 One can use ``match_operator`` to match several relational operators
  33 at once.  Any ``match_operand`` operands must have no more than one
  34 alternative.
  35
  36 :samp:`{condition}` is a C expression that must be true for the generated
  37 pattern to match.
  38
  39 .. index:: current_insn_predicate
  40
  41 :samp:`{output-template}` is a string similar to the ``define_insn``
  42 output template (see :ref:`output-template`), except that the :samp:`*`
  43 and :samp:`@` special cases do not apply.  This is only useful if the
  44 assembly text for the predicate is a simple prefix to the main insn.
  45 In order to handle the general case, there is a global variable
  46 ``current_insn_predicate`` that will contain the entire predicate
  47 if the current insn is predicated, and will otherwise be ``NULL``.
  48
  49 :samp:`{optional-insn-attributes}` is an optional vector of attributes that gets
  50 appended to the insn attributes of the produced cond_exec rtx. It can
  51 be used to add some distinguishing attribute to cond_exec rtxs produced
  52 that way. An example usage would be to use this attribute in conjunction
  53 with attributes on the main pattern to disable particular alternatives under
  54 certain conditions.
  55
  56 When ``define_cond_exec`` is used, an implicit reference to
  57 the ``predicable`` instruction attribute is made.
  58 See :ref:`insn-attributes`.  This attribute must be a boolean (i.e. have
  59 exactly two elements in its :samp:`{list-of-values}`), with the possible
  60 values being ``no`` and ``yes``.  The default and all uses in
  61 the insns must be a simple constant, not a complex expressions.  It
  62 may, however, depend on the alternative, by using a comma-separated
  63 list of values.  If that is the case, the port should also define an
  64 ``enabled`` attribute (see :ref:`disable-insn-alternatives`), which
  65 should also allow only ``no`` and ``yes`` as its values.
  66
  67 For each ``define_insn`` for which the ``predicable``
  68 attribute is true, a new ``define_insn`` pattern will be
  69 generated that matches a predicated version of the instruction.
  70 For example,
  71
  72 .. code-block::
  73
  74   (define_insn "addsi"
  75     [(set (match_operand:SI 0 "register_operand" "r")
  76           (plus:SI (match_operand:SI 1 "register_operand" "r")
  77                    (match_operand:SI 2 "register_operand" "r")))]
  78     "test1"
  79     "add %2,%1,%0")
  80
  81   (define_cond_exec
  82     [(ne (match_operand:CC 0 "register_operand" "c")
  83          (const_int 0))]
  84     "test2"
  85     "(%0)")
  86
  87 generates a new pattern
  88
  89 .. code-block::
  90
  91   (define_insn ""
  92     [(cond_exec
  93        (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
  94        (set (match_operand:SI 0 "register_operand" "r")
  95             (plus:SI (match_operand:SI 1 "register_operand" "r")
  96                      (match_operand:SI 2 "register_operand" "r"))))]
  97     "(test2) && (test1)"
  98     "(%3) add %2,%1,%0")