sphinx: add missing trailing newline

[thirdparty/gcc.git] / gcc / doc / gccint / machine-descriptions / operand-constraints.rst

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. Most of this node appears by itself (in a different place) even
   when the INTERNALS flag is clear.  Passages that require the internals
   manual's context are conditionalized to appear only in the internals manual.

.. index:: operand constraints, constraints

.. _constraints:

Operand Constraints
*******************

Each ``match_operand`` in an instruction pattern can specify
constraints for the operands allowed.  The constraints allow you to
fine-tune matching within the set of operands allowed by the
predicate.

Constraints can say whether
an operand may be in a register, and which kinds of register; whether the
operand can be a memory reference, and which kinds of address; whether the
operand may be an immediate constant, and which possible values it may
have.  Constraints can also require two operands to match.
Side-effects aren't allowed in operands of inline ``asm``, unless
:samp:`<` or :samp:`>` constraints are used, because there is no guarantee
that the side effects will happen exactly once in an instruction that can update
the addressing register.

.. toctree::
  :maxdepth: 2


.. include:: ../../../../doc/md.rst


.. index:: enabled

.. _disable-insn-alternatives:

Disable insn alternatives using the enabled attribute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are three insn attributes that may be used to selectively disable
instruction alternatives:

``enabled``
  Says whether an alternative is available on the current subtarget.

``preferred_for_size``
  Says whether an enabled alternative should be used in code that is
  optimized for size.

``preferred_for_speed``
  Says whether an enabled alternative should be used in code that is
  optimized for speed.

All these attributes should use ``(const_int 1)`` to allow an alternative
or ``(const_int 0)`` to disallow it.  The attributes must be a static
property of the subtarget; they cannot for example depend on the
current operands, on the current optimization level, on the location
of the insn within the body of a loop, on whether register allocation
has finished, or on the current compiler pass.

The ``enabled`` attribute is a correctness property.  It tells GCC to act
as though the disabled alternatives were never defined in the first place.
This is useful when adding new instructions to an existing pattern in
cases where the new instructions are only available for certain cpu
architecture levels (typically mapped to the ``-march=`` command-line
option).

In contrast, the ``preferred_for_size`` and ``preferred_for_speed``
attributes are strong optimization hints rather than correctness properties.
``preferred_for_size`` tells GCC which alternatives to consider when
adding or modifying an instruction that GCC wants to optimize for size.
``preferred_for_speed`` does the same thing for speed.  Note that things
like code motion can lead to cases where code optimized for size uses
alternatives that are not preferred for size, and similarly for speed.

Although ``define_insn`` s can in principle specify the ``enabled``
attribute directly, it is often clearer to have subsiduary attributes
for each architectural feature of interest.  The ``define_insn`` s
can then use these subsiduary attributes to say which alternatives
require which features.  The example below does this for ``cpu_facility``.

E.g. the following two patterns could easily be merged using the ``enabled``
attribute:

.. code-block::

  (define_insn "*movdi_old"
    [(set (match_operand:DI 0 "register_operand" "=d")
          (match_operand:DI 1 "register_operand" " d"))]
    "!TARGET_NEW"
    "lgr %0,%1")

  (define_insn "*movdi_new"
    [(set (match_operand:DI 0 "register_operand" "=d,f,d")
          (match_operand:DI 1 "register_operand" " d,d,f"))]
    "TARGET_NEW"
    "@
     lgr  %0,%1
     ldgr %0,%1
     lgdr %0,%1")

to:

.. code-block::

  (define_insn "*movdi_combined"
    [(set (match_operand:DI 0 "register_operand" "=d,f,d")
          (match_operand:DI 1 "register_operand" " d,d,f"))]
    ""
    "@
     lgr  %0,%1
     ldgr %0,%1
     lgdr %0,%1"
    [(set_attr "cpu_facility" "*,new,new")])

with the ``enabled`` attribute defined like this:

.. code-block::

  (define_attr "cpu_facility" "standard,new" (const_string "standard"))

  (define_attr "enabled" ""
    (cond [(eq_attr "cpu_facility" "standard") (const_int 1)
           (and (eq_attr "cpu_facility" "new")
                (ne (symbol_ref "TARGET_NEW") (const_int 0)))
           (const_int 1)]
          (const_int 0)))

.. index:: defining constraints, constraints, defining

.. _define-constraints:

Defining Machine-Specific Constraints
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Machine-specific constraints fall into two categories: register and
non-register constraints.  Within the latter category, constraints
which allow subsets of all possible memory or address operands should
be specially marked, to give ``reload`` more information.

Machine-specific constraints can be given names of arbitrary length,
but they must be entirely composed of letters, digits, underscores
(:samp:`_`), and angle brackets (:samp:`< >`).  Like C identifiers, they
must begin with a letter or underscore.

In order to avoid ambiguity in operand constraint strings, no
constraint can have a name that begins with any other constraint's
name.  For example, if ``x`` is defined as a constraint name,
``xy`` may not be, and vice versa.  As a consequence of this rule,
no constraint may begin with one of the generic constraint letters:
:samp:`E F V X g i m n o p r s`.

Register constraints correspond directly to register classes.
See :ref:`register-classes`.  There is thus not much flexibility in their
definitions.

.. index:: define_register_constraint

MD Expression define_register_constraint name regclass docstringAll three arguments are string constants.
:samp:`{name}` is the name of the constraint, as it will appear in
``match_operand`` expressions.  If :samp:`{name}` is a multi-letter
constraint its length shall be the same for all constraints starting
with the same letter.  :samp:`{regclass}` can be either the
name of the corresponding register class (see :ref:`register-classes`),
or a C expression which evaluates to the appropriate register class.
If it is an expression, it must have no side effects, and it cannot
look at the operand.  The usual use of expressions is to map some
register constraints to ``NO_REGS`` when the register class
is not available on a given subarchitecture.

:samp:`{docstring}` is a sentence documenting the meaning of the
constraint.  Docstrings are explained further below.

Non-register constraints are more like predicates: the constraint
definition gives a boolean expression which indicates whether the
constraint matches.

.. index:: define_constraint

MD Expression define_constraint name docstring expThe :samp:`{name}` and :samp:`{docstring}` arguments are the same as for
``define_register_constraint``, but note that the docstring comes
immediately after the name for these expressions.  :samp:`{exp}` is an RTL
expression, obeying the same rules as the RTL expressions in predicate
definitions.  See :ref:`defining-predicates`, for details.  If it
evaluates true, the constraint matches; if it evaluates false, it
doesn't. Constraint expressions should indicate which RTL codes they
might match, just like predicate expressions.

``match_test`` C expressions have access to the
following variables:

:samp:`{op}`
  The RTL object defining the operand.

:samp:`{mode}`
  The machine mode of :samp:`{op}`.

:samp:`{ival}`
  :samp:`INTVAL ({op})`, if :samp:`{op}` is a ``const_int``.

:samp:`{hval}`
  :samp:`CONST_DOUBLE_HIGH ({op})`, if :samp:`{op}` is an integer
  ``const_double``.

:samp:`{lval}`
  :samp:`CONST_DOUBLE_LOW ({op})`, if :samp:`{op}` is an integer
  ``const_double``.

:samp:`{rval}`
  :samp:`CONST_DOUBLE_REAL_VALUE ({op})`, if :samp:`{op}` is a floating-point
  ``const_double``.

The :samp:`{*val}` variables should only be used once another piece of the
expression has verified that :samp:`{op}` is the appropriate kind of RTL
object.

Most non-register constraints should be defined with
``define_constraint``.  The remaining two definition expressions
are only appropriate for constraints that should be handled specially
by ``reload`` if they fail to match.

.. index:: define_memory_constraint

MD Expression define_memory_constraint name docstring expUse this expression for constraints that match a subset of all memory
operands: that is, ``reload`` can make them match by converting the
operand to the form :samp:`(mem (reg {X} ))`, where :samp:`{X}` is a
base register (from the register class specified by
``BASE_REG_CLASS``, see :ref:`register-classes`).

For example, on the S/390, some instructions do not accept arbitrary
memory references, but only those that do not make use of an index
register.  The constraint letter :samp:`Q` is defined to represent a
memory address of this type.  If :samp:`Q` is defined with
``define_memory_constraint``, a :samp:`Q` constraint can handle any
memory operand, because ``reload`` knows it can simply copy the
memory address into a base register if required.  This is analogous to
the way an :samp:`o` constraint can handle any memory operand.

The syntax and semantics are otherwise identical to
``define_constraint``.

.. index:: define_special_memory_constraint

MD Expression define_special_memory_constraint name docstring expUse this expression for constraints that match a subset of all memory
operands: that is, ``reload`` cannot make them match by reloading
the address as it is described for ``define_memory_constraint`` or
such address reload is undesirable with the performance point of view.

For example, ``define_special_memory_constraint`` can be useful if
specifically aligned memory is necessary or desirable for some insn
operand.

The syntax and semantics are otherwise identical to
``define_memory_constraint``.

.. index:: define_relaxed_memory_constraint

MD Expression define_relaxed_memory_constraint name docstring expThe test expression in a ``define_memory_constraint`` can assume
that ``TARGET_LEGITIMATE_ADDRESS_P`` holds for the address inside
a ``mem`` rtx and so it does not need to test this condition itself.
In other words, a ``define_memory_constraint`` test of the form:

.. code-block:: c++

  (match_test "mem")

is enough to test whether an rtx is a ``mem`` *and* whether
its address satisfies ``TARGET_MEM_CONSTRAINT`` (which is usually
:samp:`'m'`).  Thus the conditions imposed by a ``define_memory_constraint``
always apply on top of the conditions imposed by ``TARGET_MEM_CONSTRAINT``.

However, it is sometimes useful to define memory constraints that allow
addresses beyond those accepted by ``TARGET_LEGITIMATE_ADDRESS_P``.
``define_relaxed_memory_constraint`` exists for this case.
The test expression in a ``define_relaxed_memory_constraint`` is
applied with no preconditions, so that the expression can determine
'from scratch' exactly which addresses are valid and which are not.

The syntax and semantics are otherwise identical to
``define_memory_constraint``.

.. index:: define_address_constraint

MD Expression define_address_constraint name docstring expUse this expression for constraints that match a subset of all address
operands: that is, ``reload`` can make the constraint match by
converting the operand to the form :samp:`(reg {X} )`, again
with :samp:`{X}` a base register.

Constraints defined with ``define_address_constraint`` can only be
used with the ``address_operand`` predicate, or machine-specific
predicates that work the same way.  They are treated analogously to
the generic :samp:`p` constraint.

The syntax and semantics are otherwise identical to
``define_constraint``.

For historical reasons, names beginning with the letters :samp:`G H`
are reserved for constraints that match only ``const_double`` s, and
names beginning with the letters :samp:`I J K L M N O P` are reserved
for constraints that match only ``const_int`` s.  This may change in
the future.  For the time being, constraints with these names must be
written in a stylized form, so that ``genpreds`` can tell you did
it correctly:

.. code-block::

  (define_constraint "[GHIJKLMNOP]..."
    "doc..."
    (and (match_code "const_int")  ; const_double for G/H
         condition...))            ; usually a match_test

.. the semicolons line up in the formatted manual

It is fine to use names beginning with other letters for constraints
that match ``const_double`` s or ``const_int`` s.

Each docstring in a constraint definition should be one or more complete
sentences, marked up in Texinfo format.  *They are currently unused.*
In the future they will be copied into the GCC manual, in :ref:`machine-constraints`, replacing the hand-maintained tables currently found in
that section.  Also, in the future the compiler may use this to give
more helpful diagnostics when poor choice of ``asm`` constraints
causes a reload failure.

If you put the pseudo-Texinfo directive :samp:`@internal` at the
beginning of a docstring, then (in the future) it will appear only in
the internals manual's version of the machine-specific constraint tables.
Use this for constraints that should not appear in ``asm`` statements.

.. index:: testing constraints, constraints, testing

.. _c-constraint-interface:

Testing constraints from C
^^^^^^^^^^^^^^^^^^^^^^^^^^

It is occasionally useful to test a constraint from C code rather than
implicitly via the constraint string in a ``match_operand``.  The
generated file :samp:`tm_p.h` declares a few interfaces for working
with constraints.  At present these are defined for all constraints
except ``g`` (which is equivalent to ``general_operand``).

Some valid constraint names are not valid C identifiers, so there is a
mangling scheme for referring to them from C.  Constraint names that
do not contain angle brackets or underscores are left unchanged.
Underscores are doubled, each :samp:`<` is replaced with :samp:`_l`, and
each :samp:`>` with :samp:`_g`.  Here are some examples:

.. the @c's prevent double blank lines in the printed manual.

.. list-table::

   * - **Original**
     - **Mangled** ..  c
   * - ``x``
     - ``x`` ..  c
   * - ``P42x``
     - ``P42x`` ..  c
   * - ``P4_x``
     - ``P4__x`` ..  c
   * - ``P4>x``
     - ``P4_gx`` ..  c
   * - ``P4>>``
     - ``P4_g_g`` ..  c
   * - ``P4_g>``
     - ``P4__g_g`` ..  c

Throughout this section, the variable :samp:`{c}` is either a constraint
in the abstract sense, or a constant from ``enum constraint_num`` ;
the variable :samp:`{m}` is a mangled constraint name (usually as part of
a larger identifier).

.. index:: constraint_num

Enum constraint_numFor each constraint except ``g``, there is a corresponding
enumeration constant: :samp:`CONSTRAINT_` plus the mangled name of the
constraint.  Functions that take an ``enum constraint_num`` as an
argument expect one of these constants.

.. function:: inline bool satisfies_constraint_m (rtx exp)

  For each non-register constraint :samp:`{m}` except ``g``, there is
  one of these functions; it returns ``true`` if :samp:`{exp}` satisfies the
  constraint.  These functions are only visible if :samp:`rtl.h` was included
  before :samp:`tm_p.h`.

.. function:: bool constraint_satisfied_p (rtx exp, enum constraint_num c)

  Like the ``satisfies_constraint_m`` functions, but the
  constraint to test is given as an argument, :samp:`{c}`.  If :samp:`{c}`
  specifies a register constraint, this function will always return
  ``false``.

.. function:: enum reg_class reg_class_for_constraint (enum constraint_num c)

  Returns the register class associated with :samp:`{c}`.  If :samp:`{c}` is not
  a register constraint, or those registers are not available for the
  currently selected subtarget, returns ``NO_REGS``.

Here is an example use of ``satisfies_constraint_m``.  In
peephole optimizations (see :ref:`peephole-definitions`), operand
constraint strings are ignored, so if there are relevant constraints,
they must be tested in the C condition.  In the example, the
optimization is applied if operand 2 does *not* satisfy the
:samp:`K` constraint.  (This is a simplified version of a peephole
definition from the i386 machine description.)

.. code-block::

  (define_peephole2
    [(match_scratch:SI 3 "r")
     (set (match_operand:SI 0 "register_operand" "")
          (mult:SI (match_operand:SI 1 "memory_operand" "")
                   (match_operand:SI 2 "immediate_operand" "")))]

    "!satisfies_constraint_K (operands[2])"

    [(set (match_dup 3) (match_dup 1))
     (set (match_dup 0) (mult:SI (match_dup 3) (match_dup 2)))]

    "")