gcc/doc/md.texi - gcc - Git at Google

 @c Copyright (C) 1988-2019 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.

 @ifset INTERNALS
 @node Machine Desc
 @chapter Machine Descriptions
 @cindex machine descriptions

 A machine description has two parts: a file of instruction patterns
 (@file{.md} file) and a C header file of macro definitions.

 The @file{.md} file for a target machine contains a pattern for each
 instruction that the target machine supports (or at least each instruction
 that is worth telling the compiler about).  It may also contain comments.
 A semicolon causes the rest of the line to be a comment, unless the semicolon
 is inside a quoted string.

 See the next chapter for information on the C header file.

 @menu
 * Overview::            How the machine description is used.
 * Patterns::            How to write instruction patterns.
 * Example::             An explained example of a @code{define_insn} pattern.
 * RTL Template::        The RTL template defines what insns match a pattern.
 * Output Template::     The output template says how to make assembler code
                         from such an insn.
 * Output Statement::    For more generality, write C code to output
                         the assembler code.
 * Predicates::          Controlling what kinds of operands can be used
                         for an insn.
 * Constraints::         Fine-tuning operand selection.
 * Standard Names::      Names mark patterns to use for code generation.
 * Pattern Ordering::    When the order of patterns makes a difference.
 * Dependent Patterns::  Having one pattern may make you need another.
 * Jump Patterns::       Special considerations for patterns for jump insns.
 * Looping Patterns::    How to define patterns for special looping insns.
 * Insn Canonicalizations::Canonicalization of Instructions
 * Expander Definitions::Generating a sequence of several RTL insns
                         for a standard operation.
 * Insn Splitting::      Splitting Instructions into Multiple Instructions.
 * Including Patterns::  Including Patterns in Machine Descriptions.
 * Peephole Definitions::Defining machine-specific peephole optimizations.
 * Insn Attributes::     Specifying the value of attributes for generated insns.
 * Conditional Execution::Generating @code{define_insn} patterns for
                          predication.
 * Define Subst::	Generating @code{define_insn} and @code{define_expand}
 			patterns from other patterns.
 * Constant Definitions::Defining symbolic constants that can be used in the
                         md file.
 * Iterators::           Using iterators to generate patterns from a template.
 @end menu

 @node Overview
 @section Overview of How the Machine Description is Used

 There are three main conversions that happen in the compiler:

 @enumerate

 @item
 The front end reads the source code and builds a parse tree.

 @item
 The parse tree is used to generate an RTL insn list based on named
 instruction patterns.

 @item
 The insn list is matched against the RTL templates to produce assembler
 code.

 @end enumerate

 For the generate pass, only the names of the insns matter, from either a
 named @code{define_insn} or a @code{define_expand}.  The compiler will
 choose the pattern with the right name and apply the operands according
 to the documentation later in this chapter, without regard for the RTL
 template or operand constraints.  Note that the names the compiler looks
 for are hard-coded in the compiler---it will ignore unnamed patterns and
 patterns with names it doesn't know about, but if you don't provide a
 named pattern it needs, it will abort.

 If a @code{define_insn} is used, the template given is inserted into the
 insn list.  If a @code{define_expand} is used, one of three things
 happens, based on the condition logic.  The condition logic may manually
 create new insns for the insn list, say via @code{emit_insn()}, and
 invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
 compiler to use an alternate way of performing that task.  If it invokes
 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
 is inserted, as if the @code{define_expand} were a @code{define_insn}.

 Once the insn list is generated, various optimization passes convert,
 replace, and rearrange the insns in the insn list.  This is where the
 @code{define_split} and @code{define_peephole} patterns get used, for
 example.

 Finally, the insn list's RTL is matched up with the RTL templates in the
 @code{define_insn} patterns, and those patterns are used to emit the
 final assembly code.  For this purpose, each named @code{define_insn}
 acts like it's unnamed, since the names are ignored.

 @node Patterns
 @section Everything about Instruction Patterns
 @cindex patterns
 @cindex instruction patterns

 @findex define_insn
 A @code{define_insn} expression is used to define instruction patterns
 to which insns may be matched.  A @code{define_insn} expression contains
 an incomplete RTL expression, with pieces to be filled in later, operand
 constraints that restrict how the pieces can be filled in, and an output
 template or C code to generate the assembler output.

 A @code{define_insn} is an RTL expression containing four or five operands:

 @enumerate
 @item
 An optional name @var{n}.  When a name is present, the compiler
 automically generates a C++ function @samp{gen_@var{n}} that takes
 the operands of the instruction as arguments and returns the instruction's
 rtx pattern.  The compiler also assigns the instruction a unique code
 @samp{CODE_FOR_@var{n}}, with all such codes belonging to an enum
 called @code{insn_code}.

 These names serve one of two purposes.  The first is to indicate that the
 instruction performs a certain standard job for the RTL-generation
 pass of the compiler, such as a move, an addition, or a conditional
 jump.  The second is to help the target generate certain target-specific
 operations, such as when implementing target-specific intrinsic functions.

 It is better to prefix target-specific names with the name of the
 target, to avoid any clash with current or future standard names.

 The absence of a name is indicated by writing an empty string
 where the name should go.  Nameless instruction patterns are never
 used for generating RTL code, but they may permit several simpler insns
 to be combined later on.

 For the purpose of debugging the compiler, you may also specify a
 name beginning with the @samp{*} character.  Such a name is used only
 for identifying the instruction in RTL dumps; it is equivalent to having
 a nameless pattern for all other purposes.  Names beginning with the
 @samp{*} character are not required to be unique.

 The name may also have the form @samp{@@@var{n}}.  This has the same
 effect as a name @samp{@var{n}}, but in addition tells the compiler to
 generate further helper functions; see @ref{Parameterized Names} for details.

 @item
 The @dfn{RTL template}: This is a vector of incomplete RTL expressions
 which describe the semantics of the instruction (@pxref{RTL Template}).
 It is incomplete because it may contain @code{match_operand},
 @code{match_operator}, and @code{match_dup} expressions that stand for
 operands of the instruction.

 If the vector has multiple elements, the RTL template is treated as a
 @code{parallel} expression.

 @item
 @cindex pattern conditions
 @cindex conditions, in patterns
 The condition: This is a string which contains a C expression.  When the
 compiler attempts to match RTL against a pattern, the condition is
 evaluated.  If the condition evaluates to @code{true}, the match is
 permitted.  The condition may be an empty string, which is treated
 as always @code{true}.

 @cindex named patterns and conditions
 For a named pattern, the condition may not depend on the data in the
 insn being matched, but only the target-machine-type flags.  The compiler
 needs to test these conditions during initialization in order to learn
 exactly which named instructions are available in a particular run.

 @findex operands
 For nameless patterns, the condition is applied only when matching an
 individual insn, and only after the insn has matched the pattern's
 recognition template.  The insn's operands may be found in the vector
 @code{operands}.

 An instruction condition cannot become more restrictive as compilation
 progresses.  If the condition accepts a particular RTL instruction at
 one stage of compilation, it must continue to accept that instruction
 until the final pass.  For example, @samp{!reload_completed} and
 @samp{can_create_pseudo_p ()} are both invalid instruction conditions,
 because they are true during the earlier RTL passes and false during
 the later ones.  For the same reason, if a condition accepts an
 instruction before register allocation, it cannot later try to control
 register allocation by excluding certain register or value combinations.

 Although a condition cannot become more restrictive as compilation
 progresses, the condition for a nameless pattern @emph{can} become
 more permissive.  For example, a nameless instruction can require
 @samp{reload_completed} to be true, in which case it only matches
 after register allocation.

 @item
 The @dfn{output template} or @dfn{output statement}: This is either
 a string, or a fragment of C code which returns a string.

 When simple substitution isn't general enough, you can specify a piece
 of C code to compute the output.  @xref{Output Statement}.

 @item
 The @dfn{insn attributes}: This is an optional vector containing the values of
 attributes for insns matching this pattern (@pxref{Insn Attributes}).
 @end enumerate

 @node Example
 @section Example of @code{define_insn}
 @cindex @code{define_insn} example

 Here is an example of an instruction pattern, taken from the machine
 description for the 68000/68020.

 @smallexample
 (define_insn "tstsi"
   [(set (cc0)
         (match_operand:SI 0 "general_operand" "rm"))]
   ""
   "*
 @{
   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
     return \"tstl %0\";
   return \"cmpl #0,%0\";
 @}")
 @end smallexample

 @noindent
 This can also be written using braced strings:

 @smallexample
 (define_insn "tstsi"
   [(set (cc0)
         (match_operand:SI 0 "general_operand" "rm"))]
   ""
 @{
   if (TARGET_68020 || ! ADDRESS_REG_P (operands[0]))
     return "tstl %0";
   return "cmpl #0,%0";
 @})
 @end smallexample

 This describes an instruction which sets the condition codes based on the
 value of a general operand.  It has no condition, so any insn with an RTL
 description of the form shown may be matched to this pattern.  The name
 @samp{tstsi} means ``test a @code{SImode} value'' and tells the RTL
 generation pass that, when it is necessary to test such a value, an insn
 to do so can be constructed using this pattern.

 The output control string is a piece of C code which chooses which
 output template to return based on the kind of operand and the specific
 type of CPU for which code is being generated.

 @samp{"rm"} is an operand constraint.  Its meaning is explained below.

 @node RTL Template
 @section RTL Template
 @cindex RTL insn template
 @cindex generating insns
 @cindex insns, generating
 @cindex recognizing insns
 @cindex insns, recognizing

 The RTL template is used to define which insns match the particular pattern
 and how to find their operands.  For named patterns, the RTL template also
 says how to construct an insn from specified operands.

 Construction involves substituting specified operands into a copy of the
 template.  Matching involves determining the values that serve as the
 operands in the insn being matched.  Both of these activities are
 controlled by special expression types that direct matching and
 substitution of the operands.

 @table @code
 @findex match_operand
 @item (match_operand:@var{m} @var{n} @var{predicate} @var{constraint})
 This expression is a placeholder for operand number @var{n} of
 the insn.  When constructing an insn, operand number @var{n}
 will be substituted at this point.  When matching an insn, whatever
 appears at this position in the insn will be taken as operand
 number @var{n}; but it must satisfy @var{predicate} or this instruction
 pattern will not match at all.

 Operand numbers must be chosen consecutively counting from zero in
 each instruction pattern.  There may be only one @code{match_operand}
 expression in the pattern for each operand number.  Usually operands
 are numbered in the order of appearance in @code{match_operand}
 expressions.  In the case of a @code{define_expand}, any operand numbers
 used only in @code{match_dup} expressions have higher values than all
 other operand numbers.

 @var{predicate} is a string that is the name of a function that
 accepts two arguments, an expression and a machine mode.
 @xref{Predicates}.  During matching, the function will be called with
 the putative operand as the expression and @var{m} as the mode
 argument (if @var{m} is not specified, @code{VOIDmode} will be used,
 which normally causes @var{predicate} to accept any mode).  If it
 returns zero, this instruction pattern fails to match.
 @var{predicate} may be an empty string; then it means no test is to be
 done on the operand, so anything which occurs in this position is
 valid.

 Most of the time, @var{predicate} will reject modes other than @var{m}---but
 not always.  For example, the predicate @code{address_operand} uses
 @var{m} as the mode of memory ref that the address should be valid for.
 Many predicates accept @code{const_int} nodes even though their mode is
 @code{VOIDmode}.

 @var{constraint} controls reloading and the choice of the best register
 class to use for a value, as explained later (@pxref{Constraints}).
 If the constraint would be an empty string, it can be omitted.

 People are often unclear on the difference between the constraint and the
 predicate.  The predicate helps decide whether a given insn matches the
 pattern.  The constraint plays no role in this decision; instead, it
 controls various decisions in the case of an insn which does match.

 @findex match_scratch
 @item (match_scratch:@var{m} @var{n} @var{constraint})
 This expression is also a placeholder for operand number @var{n}
 and indicates that operand must be a @code{scratch} or @code{reg}
 expression.

 When matching patterns, this is equivalent to

 @smallexample
 (match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
 @end smallexample

 but, when generating RTL, it produces a (@code{scratch}:@var{m})
 expression.

 If the last few expressions in a @code{parallel} are @code{clobber}
 expressions whose operands are either a hard register or
 @code{match_scratch}, the combiner can add or delete them when
 necessary.  @xref{Side Effects}.

 @findex match_dup
 @item (match_dup @var{n})
 This expression is also a placeholder for operand number @var{n}.
 It is used when the operand needs to appear more than once in the
 insn.

 In construction, @code{match_dup} acts just like @code{match_operand}:
 the operand is substituted into the insn being constructed.  But in
 matching, @code{match_dup} behaves differently.  It assumes that operand
 number @var{n} has already been determined by a @code{match_operand}
 appearing earlier in the recognition template, and it matches only an
 identical-looking expression.

 Note that @code{match_dup} should not be used to tell the compiler that
 a particular register is being used for two operands (example:
 @code{add} that adds one register to another; the second register is
 both an input operand and the output operand).  Use a matching
 constraint (@pxref{Simple Constraints}) for those.  @code{match_dup} is for the cases where one
 operand is used in two places in the template, such as an instruction
 that computes both a quotient and a remainder, where the opcode takes
 two input operands but the RTL template has to refer to each of those
 twice; once for the quotient pattern and once for the remainder pattern.

 @findex match_operator
 @item (match_operator:@var{m} @var{n} @var{predicate} [@var{operands}@dots{}])
 This pattern is a kind of placeholder for a variable RTL expression
 code.

 When constructing an insn, it stands for an RTL expression whose
 expression code is taken from that of operand @var{n}, and whose
 operands are constructed from the patterns @var{operands}.

 When matching an expression, it matches an expression if the function
 @var{predicate} returns nonzero on that expression @emph{and} the
 patterns @var{operands} match the operands of the expression.

 Suppose that the function @code{commutative_operator} is defined as
 follows, to match any expression whose operator is one of the
 commutative arithmetic operators of RTL and whose mode is @var{mode}:

 @smallexample
 int
 commutative_integer_operator (x, mode)
      rtx x;
      machine_mode mode;
 @{
   enum rtx_code code = GET_CODE (x);
   if (GET_MODE (x) != mode)
     return 0;
   return (GET_RTX_CLASS (code) == RTX_COMM_ARITH
           || code == EQ || code == NE);
 @}
 @end smallexample

 Then the following pattern will match any RTL expression consisting
 of a commutative operator applied to two general operands:

 @smallexample
 (match_operator:SI 3 "commutative_operator"
   [(match_operand:SI 1 "general_operand" "g")
    (match_operand:SI 2 "general_operand" "g")])
 @end smallexample

 Here the vector @code{[@var{operands}@dots{}]} contains two patterns
 because the expressions to be matched all contain two operands.

 When this pattern does match, the two operands of the commutative
 operator are recorded as operands 1 and 2 of the insn.  (This is done
 by the two instances of @code{match_operand}.)  Operand 3 of the insn
 will be the entire commutative expression: use @code{GET_CODE
 (operands[3])} to see which commutative operator was used.

 The machine mode @var{m} of @code{match_operator} works like that of
 @code{match_operand}: it is passed as the second argument to the
 predicate function, and that function is solely responsible for
 deciding whether the expression to be matched ``has'' that mode.

 When constructing an insn, argument 3 of the gen-function will specify
 the operation (i.e.@: the expression code) for the expression to be
 made.  It should be an RTL expression, whose expression code is copied
 into a new expression whose operands are arguments 1 and 2 of the
 gen-function.  The subexpressions of argument 3 are not used;
 only its expression code matters.

 When @code{match_operator} is used in a pattern for matching an insn,
 it usually best if the operand number of the @code{match_operator}
 is higher than that of the actual operands of the insn.  This improves
 register allocation because the register allocator often looks at
 operands 1 and 2 of insns to see if it can do register tying.

 There is no way to specify constraints in @code{match_operator}.  The
 operand of the insn which corresponds to the @code{match_operator}
 never has any constraints because it is never reloaded as a whole.
 However, if parts of its @var{operands} are matched by
 @code{match_operand} patterns, those parts may have constraints of
 their own.

 @findex match_op_dup
 @item (match_op_dup:@var{m} @var{n}[@var{operands}@dots{}])
 Like @code{match_dup}, except that it applies to operators instead of
 operands.  When constructing an insn, operand number @var{n} will be
 substituted at this point.  But in matching, @code{match_op_dup} behaves
 differently.  It assumes that operand number @var{n} has already been
 determined by a @code{match_operator} appearing earlier in the
 recognition template, and it matches only an identical-looking
 expression.

 @findex match_parallel
 @item (match_parallel @var{n} @var{predicate} [@var{subpat}@dots{}])
 This pattern is a placeholder for an insn that consists of a
 @code{parallel} expression with a variable number of elements.  This
 expression should only appear at the top level of an insn pattern.

 When constructing an insn, operand number @var{n} will be substituted at
 this point.  When matching an insn, it matches if the body of the insn
 is a @code{parallel} expression with at least as many elements as the
 vector of @var{subpat} expressions in the @code{match_parallel}, if each
 @var{subpat} matches the corresponding element of the @code{parallel},
 @emph{and} the function @var{predicate} returns nonzero on the
 @code{parallel} that is the body of the insn.  It is the responsibility
 of the predicate to validate elements of the @code{parallel} beyond
 those listed in the @code{match_parallel}.

 A typical use of @code{match_parallel} is to match load and store
 multiple expressions, which can contain a variable number of elements
 in a @code{parallel}.  For example,

 @smallexample
 (define_insn ""
   [(match_parallel 0 "load_multiple_operation"
      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
            (match_operand:SI 2 "memory_operand" "m"))
       (use (reg:SI 179))
       (clobber (reg:SI 179))])]
   ""
   "loadm 0,0,%1,%2")
 @end smallexample

 This example comes from @file{a29k.md}.  The function
 @code{load_multiple_operation} is defined in @file{a29k.c} and checks
 that subsequent elements in the @code{parallel} are the same as the
 @code{set} in the pattern, except that they are referencing subsequent
 registers and memory locations.

 An insn that matches this pattern might look like:

 @smallexample
 (parallel
  [(set (reg:SI 20) (mem:SI (reg:SI 100)))
   (use (reg:SI 179))
   (clobber (reg:SI 179))
   (set (reg:SI 21)
        (mem:SI (plus:SI (reg:SI 100)
                         (const_int 4))))
   (set (reg:SI 22)
        (mem:SI (plus:SI (reg:SI 100)
                         (const_int 8))))])
 @end smallexample

 @findex match_par_dup
 @item (match_par_dup @var{n} [@var{subpat}@dots{}])
 Like @code{match_op_dup}, but for @code{match_parallel} instead of
 @code{match_operator}.

 @end table

 @node Output Template
 @section Output Templates and Operand Substitution
 @cindex output templates
 @cindex operand substitution

 @cindex @samp{%} in template
 @cindex percent sign
 The @dfn{output template} is a string which specifies how to output the
 assembler code for an instruction pattern.  Most of the template is a
 fixed string which is output literally.  The character @samp{%} is used
 to specify where to substitute an operand; it can also be used to
 identify places where different variants of the assembler require
 different syntax.

 In the simplest case, a @samp{%} followed by a digit @var{n} says to output
 operand @var{n} at that point in the string.

 @samp{%} followed by a letter and a digit says to output an operand in an
 alternate fashion.  Four letters have standard, built-in meanings described
 below.  The machine description macro @code{PRINT_OPERAND} can define
 additional letters with nonstandard meanings.

 @samp{%c@var{digit}} can be used to substitute an operand that is a
 constant value without the syntax that normally indicates an immediate
 operand.

 @samp{%n@var{digit}} is like @samp{%c@var{digit}} except that the value of
 the constant is negated before printing.

 @samp{%a@var{digit}} can be used to substitute an operand as if it were a
 memory reference, with the actual operand treated as the address.  This may
 be useful when outputting a ``load address'' instruction, because often the
 assembler syntax for such an instruction requires you to write the operand
 as if it were a memory reference.

 @samp{%l@var{digit}} is used to substitute a @code{label_ref} into a jump
 instruction.

 @samp{%=} outputs a number which is unique to each instruction in the
 entire compilation.  This is useful for making local labels to be
 referred to more than once in a single template that generates multiple
 assembler instructions.

 @samp{%} followed by a punctuation character specifies a substitution that
 does not use an operand.  Only one case is standard: @samp{%%} outputs a
 @samp{%} into the assembler code.  Other nonstandard cases can be
 defined in the @code{PRINT_OPERAND} macro.  You must also define
 which punctuation characters are valid with the
 @code{PRINT_OPERAND_PUNCT_VALID_P} macro.

 @cindex \
 @cindex backslash
 The template may generate multiple assembler instructions.  Write the text
 for the instructions, with @samp{\;} between them.

 @cindex matching operands
 When the RTL contains two operands which are required by constraint to match
 each other, the output template must refer only to the lower-numbered operand.
 Matching operands are not always identical, and the rest of the compiler
 arranges to put the proper RTL expression for printing into the lower-numbered
 operand.

 One use of nonstandard letters or punctuation following @samp{%} is to
 distinguish between different assembler languages for the same machine; for
 example, Motorola syntax versus MIT syntax for the 68000.  Motorola syntax
 requires periods in most opcode names, while MIT syntax does not.  For
 example, the opcode @samp{movel} in MIT syntax is @samp{move.l} in Motorola
 syntax.  The same file of patterns is used for both kinds of output syntax,
 but the character sequence @samp{%.} is used in each place where Motorola
 syntax wants a period.  The @code{PRINT_OPERAND} macro for Motorola syntax
 defines the sequence to output a period; the macro for MIT syntax defines
 it to do nothing.

 @cindex @code{#} in template
 As a special case, a template consisting of the single character @code{#}
 instructs the compiler to first split the insn, and then output the
 resulting instructions separately.  This helps eliminate redundancy in the
 output templates.   If you have a @code{define_insn} that needs to emit
 multiple assembler instructions, and there is a matching @code{define_split}
 already defined, then you can simply use @code{#} as the output template
 instead of writing an output template that emits the multiple assembler
 instructions.

 Note that @code{#} only has an effect while generating assembly code;
 it does not affect whether a split occurs earlier.  An associated
 @code{define_split} must exist and it must be suitable for use after
 register allocation.

 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
 of the form @samp{@{option0|option1|option2@}} in the templates.  These
 describe multiple variants of assembler language syntax.
 @xref{Instruction Output}.

 @node Output Statement
 @section C Statements for Assembler Output
 @cindex output statements
 @cindex C statements for assembler output
 @cindex generating assembler output

 Often a single fixed template string cannot produce correct and efficient
 assembler code for all the cases that are recognized by a single
 instruction pattern.  For example, the opcodes may depend on the kinds of
 operands; or some unfortunate combinations of operands may require extra
 machine instructions.

 If the output control string starts with a @samp{@@}, then it is actually
 a series of templates, each on a separate line.  (Blank lines and
 leading spaces and tabs are ignored.)  The templates correspond to the
 pattern's constraint alternatives (@pxref{Multi-Alternative}).  For example,
 if a target machine has a two-address add instruction @samp{addr} to add
 into a register and another @samp{addm} to add a register to memory, you
 might write this pattern:

 @smallexample
 (define_insn "addsi3"
   [(set (match_operand:SI 0 "general_operand" "=r,m")
         (plus:SI (match_operand:SI 1 "general_operand" "0,0")
                  (match_operand:SI 2 "general_operand" "g,r")))]
   ""
   "@@
    addr %2,%0
    addm %2,%0")
 @end smallexample

 @cindex @code{*} in template
 @cindex asterisk in template
 If the output control string starts with a @samp{*}, then it is not an
 output template but rather a piece of C program that should compute a
 template.  It should execute a @code{return} statement to return the
 template-string you want.  Most such templates use C string literals, which
 require doublequote characters to delimit them.  To include these
 doublequote characters in the string, prefix each one with @samp{\}.

 If the output control string is written as a brace block instead of a
 double-quoted string, it is automatically assumed to be C code.  In that
 case, it is not necessary to put in a leading asterisk, or to escape the
 doublequotes surrounding C string literals.

 The operands may be found in the array @code{operands}, whose C data type
 is @code{rtx []}.

 It is very common to select different ways of generating assembler code
 based on whether an immediate operand is within a certain range.  Be
 careful when doing this, because the result of @code{INTVAL} is an
 integer on the host machine.  If the host machine has more bits in an
 @code{int} than the target machine has in the mode in which the constant
 will be used, then some of the bits you get from @code{INTVAL} will be
 superfluous.  For proper results, you must carefully disregard the
 values of those bits.

 @findex output_asm_insn
 It is possible to output an assembler instruction and then go on to output
 or compute more of them, using the subroutine @code{output_asm_insn}.  This
 receives two arguments: a template-string and a vector of operands.  The
 vector may be @code{operands}, or it may be another array of @code{rtx}
 that you declare locally and initialize yourself.

 @findex which_alternative
 When an insn pattern has multiple alternatives in its constraints, often
 the appearance of the assembler code is determined mostly by which alternative
 was matched.  When this is so, the C code can test the variable
 @code{which_alternative}, which is the ordinal number of the alternative
 that was actually satisfied (0 for the first, 1 for the second alternative,
 etc.).

 For example, suppose there are two opcodes for storing zero, @samp{clrreg}
 for registers and @samp{clrmem} for memory locations.  Here is how
 a pattern could use @code{which_alternative} to choose between them:

 @smallexample
 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r,m")
         (const_int 0))]
   ""
   @{
   return (which_alternative == 0
           ? "clrreg %0" : "clrmem %0");
   @})
 @end smallexample

 The example above, where the assembler code to generate was
 @emph{solely} determined by the alternative, could also have been specified
 as follows, having the output control string start with a @samp{@@}:

 @smallexample
 @group
 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r,m")
         (const_int 0))]
   ""
   "@@
    clrreg %0
    clrmem %0")
 @end group
 @end smallexample

 If you just need a little bit of C code in one (or a few) alternatives,
 you can use @samp{*} inside of a @samp{@@} multi-alternative template:

 @smallexample
 @group
 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r,<,m")
         (const_int 0))]
   ""
   "@@
    clrreg %0
    * return stack_mem_p (operands[0]) ? \"push 0\" : \"clrmem %0\";
    clrmem %0")
 @end group
 @end smallexample

 @node Predicates
 @section Predicates
 @cindex predicates
 @cindex operand predicates
 @cindex operator predicates

 A predicate determines whether a @code{match_operand} or
 @code{match_operator} expression matches, and therefore whether the
 surrounding instruction pattern will be used for that combination of
 operands.  GCC has a number of machine-independent predicates, and you
 can define machine-specific predicates as needed.  By convention,
 predicates used with @code{match_operand} have names that end in
 @samp{_operand}, and those used with @code{match_operator} have names
 that end in @samp{_operator}.

 All predicates are boolean functions (in the mathematical sense) of
 two arguments: the RTL expression that is being considered at that
 position in the instruction pattern, and the machine mode that the
 @code{match_operand} or @code{match_operator} specifies.  In this
 section, the first argument is called @var{op} and the second argument
 @var{mode}.  Predicates can be called from C as ordinary two-argument
 functions; this can be useful in output templates or other
 machine-specific code.

 Operand predicates can allow operands that are not actually acceptable
 to the hardware, as long as the constraints give reload the ability to
 fix them up (@pxref{Constraints}).  However, GCC will usually generate
 better code if the predicates specify the requirements of the machine
 instructions as closely as possible.  Reload cannot fix up operands
 that must be constants (``immediate operands''); you must use a
 predicate that allows only constants, or else enforce the requirement
 in the extra condition.

 @cindex predicates and machine modes
 @cindex normal predicates
 @cindex special predicates
 Most predicates handle their @var{mode} argument in a uniform manner.
 If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
 any mode.  If @var{mode} is anything else, then @var{op} must have the
 same mode, unless @var{op} is a @code{CONST_INT} or integer
 @code{CONST_DOUBLE}.  These RTL expressions always have
 @code{VOIDmode}, so it would be counterproductive to check that their
 mode matches.  Instead, predicates that accept @code{CONST_INT} and/or
 integer @code{CONST_DOUBLE} check that the value stored in the
 constant will fit in the requested mode.

 Predicates with this behavior are called @dfn{normal}.
 @command{genrecog} can optimize the instruction recognizer based on
 knowledge of how normal predicates treat modes.  It can also diagnose
 certain kinds of common errors in the use of normal predicates; for
 instance, it is almost always an error to use a normal predicate
 without specifying a mode.

 Predicates that do something different with their @var{mode} argument
 are called @dfn{special}.  The generic predicates
 @code{address_operand} and @code{pmode_register_operand} are special
 predicates.  @command{genrecog} does not do any optimizations or
 diagnosis when special predicates are used.

 @menu
 * Machine-Independent Predicates::  Predicates available to all back ends.
 * Defining Predicates::             How to write machine-specific predicate
                                     functions.
 @end menu

 @node Machine-Independent Predicates
 @subsection Machine-Independent Predicates
 @cindex machine-independent predicates
 @cindex generic predicates

 These are the generic predicates available to all back ends.  They are
 defined in @file{recog.c}.  The first category of predicates allow
 only constant, or @dfn{immediate}, operands.

 @defun immediate_operand
 This predicate allows any sort of constant that fits in @var{mode}.
 It is an appropriate choice for instructions that take operands that
 must be constant.
 @end defun

 @defun const_int_operand
 This predicate allows any @code{CONST_INT} expression that fits in
 @var{mode}.  It is an appropriate choice for an immediate operand that
 does not allow a symbol or label.
 @end defun

 @defun const_double_operand
 This predicate accepts any @code{CONST_DOUBLE} expression that has
 exactly @var{mode}.  If @var{mode} is @code{VOIDmode}, it will also
 accept @code{CONST_INT}.  It is intended for immediate floating point
 constants.
 @end defun

 @noindent
 The second category of predicates allow only some kind of machine
 register.

 @defun register_operand
 This predicate allows any @code{REG} or @code{SUBREG} expression that
 is valid for @var{mode}.  It is often suitable for arithmetic
 instruction operands on a RISC machine.
 @end defun

 @defun pmode_register_operand
 This is a slight variant on @code{register_operand} which works around
 a limitation in the machine-description reader.

 @smallexample
 (match_operand @var{n} "pmode_register_operand" @var{constraint})
 @end smallexample

 @noindent
 means exactly what

 @smallexample
 (match_operand:P @var{n} "register_operand" @var{constraint})
 @end smallexample

 @noindent
 would mean, if the machine-description reader accepted @samp{:P}
 mode suffixes.  Unfortunately, it cannot, because @code{Pmode} is an
 alias for some other mode, and might vary with machine-specific
 options.  @xref{Misc}.
 @end defun

 @defun scratch_operand
 This predicate allows hard registers and @code{SCRATCH} expressions,
 but not pseudo-registers.  It is used internally by @code{match_scratch};
 it should not be used directly.
 @end defun

 @noindent
 The third category of predicates allow only some kind of memory reference.

 @defun memory_operand
 This predicate allows any valid reference to a quantity of mode
 @var{mode} in memory, as determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
 @end defun

 @defun address_operand
 This predicate is a little unusual; it allows any operand that is a
 valid expression for the @emph{address} of a quantity of mode
 @var{mode}, again determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS}.  To first order, if
 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
 @code{memory_operand}, then @var{exp} is acceptable to
 @code{address_operand}.  Note that @var{exp} does not necessarily have
 the mode @var{mode}.
 @end defun

 @defun indirect_operand
 This is a stricter form of @code{memory_operand} which allows only
 memory references with a @code{general_operand} as the address
 expression.  New uses of this predicate are discouraged, because
 @code{general_operand} is very permissive, so it's hard to tell what
 an @code{indirect_operand} does or does not allow.  If a target has
 different requirements for memory operands for different instructions,
 it is better to define target-specific predicates which enforce the
 hardware's requirements explicitly.
 @end defun

 @defun push_operand
 This predicate allows a memory reference suitable for pushing a value
 onto the stack.  This will be a @code{MEM} which refers to
 @code{stack_pointer_rtx}, with a side effect in its address expression
 (@pxref{Incdec}); which one is determined by the
 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
 @end defun

 @defun pop_operand
 This predicate allows a memory reference suitable for popping a value
 off the stack.  Again, this will be a @code{MEM} referring to
 @code{stack_pointer_rtx}, with a side effect in its address
 expression.  However, this time @code{STACK_POP_CODE} is expected.
 @end defun

 @noindent
 The fourth category of predicates allow some combination of the above
 operands.

 @defun nonmemory_operand
 This predicate allows any immediate or register operand valid for @var{mode}.
 @end defun

 @defun nonimmediate_operand
 This predicate allows any register or memory operand valid for @var{mode}.
 @end defun

 @defun general_operand
 This predicate allows any immediate, register, or memory operand
 valid for @var{mode}.
 @end defun

 @noindent
 Finally, there are two generic operator predicates.

 @defun comparison_operator
 This predicate matches any expression which performs an arithmetic
 comparison in @var{mode}; that is, @code{COMPARISON_P} is true for the
 expression code.
 @end defun

 @defun ordered_comparison_operator
 This predicate matches any expression which performs an arithmetic
 comparison in @var{mode} and whose expression code is valid for integer
 modes; that is, the expression code will be one of @code{eq}, @code{ne},
 @code{lt}, @code{ltu}, @code{le}, @code{leu}, @code{gt}, @code{gtu},
 @code{ge}, @code{geu}.
 @end defun

 @node Defining Predicates
 @subsection Defining Machine-Specific Predicates
 @cindex defining predicates
 @findex define_predicate
 @findex define_special_predicate

 Many machines have requirements for their operands that cannot be
 expressed precisely using the generic predicates.  You can define
 additional predicates using @code{define_predicate} and
 @code{define_special_predicate} expressions.  These expressions have
 three operands:

 @itemize @bullet
 @item
 The name of the predicate, as it will be referred to in
 @code{match_operand} or @code{match_operator} expressions.

 @item
 An RTL expression which evaluates to true if the predicate allows the
 operand @var{op}, false if it does not.  This expression can only use
 the following RTL codes:

 @table @code
 @item MATCH_OPERAND
 When written inside a predicate expression, a @code{MATCH_OPERAND}
 expression evaluates to true if the predicate it names would allow
 @var{op}.  The operand number and constraint are ignored.  Due to
 limitations in @command{genrecog}, you can only refer to generic
 predicates and predicates that have already been defined.

 @item MATCH_CODE
 This expression evaluates to true if @var{op} or a specified
 subexpression of @var{op} has one of a given list of RTX codes.

 The first operand of this expression is a string constant containing a
 comma-separated list of RTX code names (in lower case).  These are the
 codes for which the @code{MATCH_CODE} will be true.

 The second operand is a string constant which indicates what
 subexpression of @var{op} to examine.  If it is absent or the empty
 string, @var{op} itself is examined.  Otherwise, the string constant
 must be a sequence of digits and/or lowercase letters.  Each character
 indicates a subexpression to extract from the current expression; for
 the first character this is @var{op}, for the second and subsequent
 characters it is the result of the previous character.  A digit
 @var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
 extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
 alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on).  The
 @code{MATCH_CODE} then examines the RTX code of the subexpression
 extracted by the complete string.  It is not possible to extract
 components of an @code{rtvec} that is not at position 0 within its RTX
 object.

 @item MATCH_TEST
 This expression has one operand, a string constant containing a C
 expression.  The predicate's arguments, @var{op} and @var{mode}, are
 available with those names in the C expression.  The @code{MATCH_TEST}
 evaluates to true if the C expression evaluates to a nonzero value.
 @code{MATCH_TEST} expressions must not have side effects.

 @item  AND
 @itemx IOR
 @itemx NOT
 @itemx IF_THEN_ELSE
 The basic @samp{MATCH_} expressions can be combined using these
 logical operators, which have the semantics of the C operators
 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively.  As
 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
 arbitrary number of arguments; this has exactly the same effect as
 writing a chain of two-argument @code{AND} or @code{IOR} expressions.
 @end table

 @item
 An optional block of C code, which should execute
 @samp{@w{return true}} if the predicate is found to match and
 @samp{@w{return false}} if it does not.  It must not have any side
 effects.  The predicate arguments, @var{op} and @var{mode}, are
 available with those names.

 If a code block is present in a predicate definition, then the RTL
 expression must evaluate to true @emph{and} the code block must
 execute @samp{@w{return true}} for the predicate to allow the operand.
 The RTL expression is evaluated first; do not re-check anything in the
 code block that was checked in the RTL expression.
 @end itemize

 The program @command{genrecog} scans @code{define_predicate} and
 @code{define_special_predicate} expressions to determine which RTX
 codes are possibly allowed.  You should always make this explicit in
 the RTL predicate expression, using @code{MATCH_OPERAND} and
 @code{MATCH_CODE}.

 Here is an example of a simple predicate definition, from the IA64
 machine description:

 @smallexample
 @group
 ;; @r{True if @var{op} is a @code{SYMBOL_REF} which refers to the sdata section.}
 (define_predicate "small_addr_symbolic_operand"
   (and (match_code "symbol_ref")
        (match_test "SYMBOL_REF_SMALL_ADDR_P (op)")))
 @end group
 @end smallexample

 @noindent
 And here is another, showing the use of the C block.

 @smallexample
 @group
 ;; @r{True if @var{op} is a register operand that is (or could be) a GR reg.}
 (define_predicate "gr_register_operand"
   (match_operand 0 "register_operand")
 @{
   unsigned int regno;
   if (GET_CODE (op) == SUBREG)
     op = SUBREG_REG (op);

   regno = REGNO (op);
   return (regno >= FIRST_PSEUDO_REGISTER || GENERAL_REGNO_P (regno));
 @})
 @end group
 @end smallexample

 Predicates written with @code{define_predicate} automatically include
 a test that @var{mode} is @code{VOIDmode}, or @var{op} has the same
 mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
 @code{CONST_DOUBLE}.  They do @emph{not} check specifically for
 integer @code{CONST_DOUBLE}, nor do they test that the value of either
 kind of constant fits in the requested mode.  This is because
 target-specific predicates that take constants usually have to do more
 stringent value checks anyway.  If you need the exact same treatment
 of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
 provide, use a @code{MATCH_OPERAND} subexpression to call
 @code{const_int_operand}, @code{const_double_operand}, or
 @code{immediate_operand}.

 Predicates written with @code{define_special_predicate} do not get any
 automatic mode checks, and are treated as having special mode handling
 by @command{genrecog}.

 The program @command{genpreds} is responsible for generating code to
 test predicates.  It also writes a header file containing function
 declarations for all machine-specific predicates.  It is not necessary
 to declare these predicates in @file{@var{cpu}-protos.h}.
 @end ifset

 @c Most of this node appears by itself (in a different place) even
 @c when the INTERNALS flag is clear.  Passages that require the internals
 @c manual's context are conditionalized to appear only in the internals manual.
 @ifset INTERNALS
 @node Constraints
 @section Operand Constraints
 @cindex operand constraints
 @cindex constraints

 Each @code{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.

 @end ifset
 @ifclear INTERNALS
 @node Constraints
 @section Constraints for @code{asm} Operands
 @cindex operand constraints, @code{asm}
 @cindex constraints, @code{asm}
 @cindex @code{asm} constraints

 Here are specific details on what constraint letters you can use with
 @code{asm} operands.
 @end ifclear
 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 @code{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.

 @ifset INTERNALS
 @menu
 * Simple Constraints::  Basic use of constraints.
 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
 * Class Preferences::   Constraints guide which hard register to put things in.
 * Modifiers::           More precise control over effects of constraints.
 * Machine Constraints:: Existing constraints for some particular machines.
 * Disable Insn Alternatives:: Disable insn alternatives using attributes.
 * Define Constraints::  How to define machine-specific constraints.
 * C Constraint Interface:: How to test constraints from C code.
 @end menu
 @end ifset

 @ifclear INTERNALS
 @menu
 * Simple Constraints::  Basic use of constraints.
 * Multi-Alternative::   When an insn has two alternative constraint-patterns.
 * Modifiers::           More precise control over effects of constraints.
 * Machine Constraints:: Special constraints for some particular machines.
 @end menu
 @end ifclear

 @node Simple Constraints
 @subsection Simple Constraints
 @cindex simple constraints

 The simplest kind of constraint is a string full of letters, each of
 which describes one kind of operand that is permitted.  Here are
 the letters that are allowed:

 @table @asis
 @item whitespace
 Whitespace characters are ignored and can be inserted at any position
 except the first.  This enables each alternative for different operands to
 be visually aligned in the machine description even if they have different
 number of constraints and modifiers.

 @cindex @samp{m} in constraint
 @cindex memory references in constraints
 @item @samp{m}
 A memory operand is allowed, with any kind of address that the machine
 supports in general.
 Note that the letter used for the general memory constraint can be
 re-defined by a back end using the @code{TARGET_MEM_CONSTRAINT} macro.

 @cindex offsettable address
 @cindex @samp{o} in constraint
 @item @samp{o}
 A memory operand is allowed, but only if the address is
 @dfn{offsettable}.  This means that adding a small integer (actually,
 the width in bytes of the operand, as determined by its machine mode)
 may be added to the address and the result is also a valid memory
 address.

 @cindex autoincrement/decrement addressing
 For example, an address which is constant is offsettable; so is an
 address that is the sum of a register and a constant (as long as a
 slightly larger constant is also within the range of address-offsets
 supported by the machine); but an autoincrement or autodecrement
 address is not offsettable.  More complicated indirect/indexed
 addresses may or may not be offsettable depending on the other
 addressing modes that the machine supports.

 Note that in an output operand which can be matched by another
 operand, the constraint letter @samp{o} is valid only when accompanied
 by both @samp{<} (if the target machine has predecrement addressing)
 and @samp{>} (if the target machine has preincrement addressing).

 @cindex @samp{V} in constraint
 @item @samp{V}
 A memory operand that is not offsettable.  In other words, anything that
 would fit the @samp{m} constraint but not the @samp{o} constraint.

 @cindex @samp{<} in constraint
 @item @samp{<}
 A memory operand with autodecrement addressing (either predecrement or
 postdecrement) is allowed.  In inline @code{asm} this constraint is only
 allowed if the operand is used exactly once in an instruction that can
 handle the side effects.  Not using an operand with @samp{<} in constraint
 string in the inline @code{asm} pattern at all or using it in multiple
 instructions isn't valid, because the side effects wouldn't be performed
 or would be performed more than once.  Furthermore, on some targets
 the operand with @samp{<} in constraint string must be accompanied by
 special instruction suffixes like @code{%U0} instruction suffix on PowerPC
 or @code{%P0} on IA-64.

 @cindex @samp{>} in constraint
 @item @samp{>}
 A memory operand with autoincrement addressing (either preincrement or
 postincrement) is allowed.  In inline @code{asm} the same restrictions
 as for @samp{<} apply.

 @cindex @samp{r} in constraint
 @cindex registers in constraints
 @item @samp{r}
 A register operand is allowed provided that it is in a general
 register.

 @cindex constants in constraints
 @cindex @samp{i} in constraint
 @item @samp{i}
 An immediate integer operand (one with constant value) is allowed.
 This includes symbolic constants whose values will be known only at
 assembly time or later.

 @cindex @samp{n} in constraint
 @item @samp{n}
 An immediate integer operand with a known numeric value is allowed.
 Many systems cannot support assembly-time constants for operands less
 than a word wide.  Constraints for these operands should use @samp{n}
 rather than @samp{i}.

 @cindex @samp{I} in constraint
 @item @samp{I}, @samp{J}, @samp{K}, @dots{} @samp{P}
 Other letters in the range @samp{I} through @samp{P} may be defined in
 a machine-dependent fashion to permit immediate integer operands with
 explicit integer values in specified ranges.  For example, on the
 68000, @samp{I} is defined to stand for the range of values 1 to 8.
 This is the range permitted as a shift count in the shift
 instructions.

 @cindex @samp{E} in constraint
 @item @samp{E}
 An immediate floating operand (expression code @code{const_double}) is
 allowed, but only if the target floating point format is the same as
 that of the host machine (on which the compiler is running).

 @cindex @samp{F} in constraint
 @item @samp{F}
 An immediate floating operand (expression code @code{const_double} or
 @code{const_vector}) is allowed.

 @cindex @samp{G} in constraint
 @cindex @samp{H} in constraint
 @item @samp{G}, @samp{H}
 @samp{G} and @samp{H} may be defined in a machine-dependent fashion to
 permit immediate floating operands in particular ranges of values.

 @cindex @samp{s} in constraint
 @item @samp{s}
 An immediate integer operand whose value is not an explicit integer is
 allowed.

 This might appear strange; if an insn allows a constant operand with a
 value not known at compile time, it certainly must allow any known
 value.  So why use @samp{s} instead of @samp{i}?  Sometimes it allows
 better code to be generated.

 For example, on the 68000 in a fullword instruction it is possible to
 use an immediate operand; but if the immediate value is between @minus{}128
 and 127, better code results from loading the value into a register and
 using the register.  This is because the load into the register can be
 done with a @samp{moveq} instruction.  We arrange for this to happen
 by defining the letter @samp{K} to mean ``any integer outside the
 range @minus{}128 to 127'', and then specifying @samp{Ks} in the operand
 constraints.

 @cindex @samp{g} in constraint
 @item @samp{g}
 Any register, memory or immediate integer operand is allowed, except for
 registers that are not general registers.

 @cindex @samp{X} in constraint
 @item @samp{X}
 @ifset INTERNALS
 Any operand whatsoever is allowed, even if it does not satisfy
 @code{general_operand}.  This is normally used in the constraint of
 a @code{match_scratch} when certain alternatives will not actually
 require a scratch register.
 @end ifset
 @ifclear INTERNALS
 Any operand whatsoever is allowed.
 @end ifclear

 @cindex @samp{0} in constraint
 @cindex digits in constraint
 @item @samp{0}, @samp{1}, @samp{2}, @dots{} @samp{9}
 An operand that matches the specified operand number is allowed.  If a
 digit is used together with letters within the same alternative, the
 digit should come last.

 This number is allowed to be more than a single digit.  If multiple
 digits are encountered consecutively, they are interpreted as a single
 decimal integer.  There is scant chance for ambiguity, since to-date
 it has never been desirable that @samp{10} be interpreted as matching
 either operand 1 @emph{or} operand 0.  Should this be desired, one
 can use multiple alternatives instead.

 @cindex matching constraint
 @cindex constraint, matching
 This is called a @dfn{matching constraint} and what it really means is
 that the assembler has only a single operand that fills two roles
 @ifset INTERNALS
 considered separate in the RTL insn.  For example, an add insn has two
 input operands and one output operand in the RTL, but on most CISC
 @end ifset
 @ifclear INTERNALS
 which @code{asm} distinguishes.  For example, an add instruction uses
 two input operands and an output operand, but on most CISC
 @end ifclear
 machines an add instruction really has only two operands, one of them an
 input-output operand:

 @smallexample
 addl #35,r12
 @end smallexample

 Matching constraints are used in these circumstances.
 More precisely, the two operands that match must include one input-only
 operand and one output-only operand.  Moreover, the digit must be a
 smaller number than the number of the operand that uses it in the
 constraint.

 @ifset INTERNALS
 For operands to match in a particular case usually means that they
 are identical-looking RTL expressions.  But in a few special cases
 specific kinds of dissimilarity are allowed.  For example, @code{*x}
 as an input operand will match @code{*x++} as an output operand.
 For proper results in such cases, the output template should always
 use the output-operand's number when printing the operand.
 @end ifset

 @cindex load address instruction
 @cindex push address instruction
 @cindex address constraints
 @cindex @samp{p} in constraint
 @item @samp{p}
 An operand that is a valid memory address is allowed.  This is
 for ``load address'' and ``push address'' instructions.

 @findex address_operand
 @samp{p} in the constraint must be accompanied by @code{address_operand}
 as the predicate in the @code{match_operand}.  This predicate interprets
 the mode specified in the @code{match_operand} as the mode of the memory
 reference for which the address would be valid.

 @cindex other register constraints
 @cindex extensible constraints
 @item @var{other-letters}
 Other letters can be defined in machine-dependent fashion to stand for
 particular classes of registers or other arbitrary operand types.
 @samp{d}, @samp{a} and @samp{f} are defined on the 68000/68020 to stand
 for data, address and floating point registers.
 @end table

 @ifset INTERNALS
 In order to have valid assembler code, each operand must satisfy
 its constraint.  But a failure to do so does not prevent the pattern
 from applying to an insn.  Instead, it directs the compiler to modify
 the code so that the constraint will be satisfied.  Usually this is
 done by copying an operand into a register.

 Contrast, therefore, the two instruction patterns that follow:

 @smallexample
 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r")
         (plus:SI (match_dup 0)
                  (match_operand:SI 1 "general_operand" "r")))]
   ""
   "@dots{}")
 @end smallexample

 @noindent
 which has two operands, one of which must appear in two places, and

 @smallexample
 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r")
         (plus:SI (match_operand:SI 1 "general_operand" "0")
                  (match_operand:SI 2 "general_operand" "r")))]
   ""
   "@dots{}")
 @end smallexample

 @noindent
 which has three operands, two of which are required by a constraint to be
 identical.  If we are considering an insn of the form

 @smallexample
 (insn @var{n} @var{prev} @var{next}
   (set (reg:SI 3)
        (plus:SI (reg:SI 6) (reg:SI 109)))
   @dots{})
 @end smallexample

 @noindent
 the first pattern would not apply at all, because this insn does not
 contain two identical subexpressions in the right place.  The pattern would
 say, ``That does not look like an add instruction; try other patterns''.
 The second pattern would say, ``Yes, that's an add instruction, but there
 is something wrong with it''.  It would direct the reload pass of the
 compiler to generate additional insns to make the constraint true.  The
 results might look like this:

 @smallexample
 (insn @var{n2} @var{prev} @var{n}
   (set (reg:SI 3) (reg:SI 6))
   @dots{})

 (insn @var{n} @var{n2} @var{next}
   (set (reg:SI 3)
        (plus:SI (reg:SI 3) (reg:SI 109)))
   @dots{})
 @end smallexample

 It is up to you to make sure that each operand, in each pattern, has
 constraints that can handle any RTL expression that could be present for
 that operand.  (When multiple alternatives are in use, each pattern must,
 for each possible combination of operand expressions, have at least one
 alternative which can handle that combination of operands.)  The
 constraints don't need to @emph{allow} any possible operand---when this is
 the case, they do not constrain---but they must at least point the way to
 reloading any possible operand so that it will fit.

 @itemize @bullet
 @item
 If the constraint accepts whatever operands the predicate permits,
 there is no problem: reloading is never necessary for this operand.

 For example, an operand whose constraints permit everything except
 registers is safe provided its predicate rejects registers.

 An operand whose predicate accepts only constant values is safe
 provided its constraints include the letter @samp{i}.  If any possible
 constant value is accepted, then nothing less than @samp{i} will do;
 if the predicate is more selective, then the constraints may also be
 more selective.

 @item
 Any operand expression can be reloaded by copying it into a register.
 So if an operand's constraints allow some kind of register, it is
 certain to be safe.  It need not permit all classes of registers; the
 compiler knows how to copy a register into another register of the
 proper class in order to make an instruction valid.

 @cindex nonoffsettable memory reference
 @cindex memory reference, nonoffsettable
 @item
 A nonoffsettable memory reference can be reloaded by copying the
 address into a register.  So if the constraint uses the letter
 @samp{o}, all memory references are taken care of.

 @item
 A constant operand can be reloaded by allocating space in memory to
 hold it as preinitialized data.  Then the memory reference can be used
 in place of the constant.  So if the constraint uses the letters
 @samp{o} or @samp{m}, constant operands are not a problem.

 @item
 If the constraint permits a constant and a pseudo register used in an insn
 was not allocated to a hard register and is equivalent to a constant,
 the register will be replaced with the constant.  If the predicate does
 not permit a constant and the insn is re-recognized for some reason, the
 compiler will crash.  Thus the predicate must always recognize any
 objects allowed by the constraint.
 @end itemize

 If the operand's predicate can recognize registers, but the constraint does
 not permit them, it can make the compiler crash.  When this operand happens
 to be a register, the reload pass will be stymied, because it does not know
 how to copy a register temporarily into memory.

 If the predicate accepts a unary operator, the constraint applies to the
 operand.  For example, the MIPS processor at ISA level 3 supports an
 instruction which adds two registers in @code{SImode} to produce a
 @code{DImode} result, but only if the registers are correctly sign
 extended.  This predicate for the input operands accepts a
 @code{sign_extend} of an @code{SImode} register.  Write the constraint
 to indicate the type of register that is required for the operand of the
 @code{sign_extend}.
 @end ifset

 @node Multi-Alternative
 @subsection Multiple Alternative Constraints
 @cindex multiple alternative constraints

 Sometimes a single instruction has multiple alternative sets of possible
 operands.  For example, on the 68000, a logical-or instruction can combine
 register or an immediate value into memory, or it can combine any kind of
 operand into a register; but it cannot combine one memory location into
 another.

 These constraints are represented as multiple alternatives.  An alternative
 can be described by a series of letters for each operand.  The overall
 constraint for an operand is made from the letters for this operand
 from the first alternative, a comma, the letters for this operand from
 the second alternative, a comma, and so on until the last alternative.
 All operands for a single instruction must have the same number of
 alternatives.
 @ifset INTERNALS
 Here is how it is done for fullword logical-or on the 68000:

 @smallexample
 (define_insn "iorsi3"
   [(set (match_operand:SI 0 "general_operand" "=m,d")
         (ior:SI (match_operand:SI 1 "general_operand" "%0,0")
                 (match_operand:SI 2 "general_operand" "dKs,dmKs")))]
   @dots{})
 @end smallexample

 The first alternative has @samp{m} (memory) for operand 0, @samp{0} for
 operand 1 (meaning it must match operand 0), and @samp{dKs} for operand
 2.  The second alternative has @samp{d} (data register) for operand 0,
 @samp{0} for operand 1, and @samp{dmKs} for operand 2.  The @samp{=} and
 @samp{%} in the constraints apply to all the alternatives; their
 meaning is explained in the next section (@pxref{Class Preferences}).

 If all the operands fit any one alternative, the instruction is valid.
 Otherwise, for each alternative, the compiler counts how many instructions
 must be added to copy the operands so that that alternative applies.
 The alternative requiring the least copying is chosen.  If two alternatives
 need the same amount of copying, the one that comes first is chosen.
 These choices can be altered with the @samp{?} and @samp{!} characters:

 @table @code
 @cindex @samp{?} in constraint
 @cindex question mark
 @item ?
 Disparage slightly the alternative that the @samp{?} appears in,
 as a choice when no alternative applies exactly.  The compiler regards
 this alternative as one unit more costly for each @samp{?} that appears
 in it.

 @cindex @samp{!} in constraint
 @cindex exclamation point
 @item !
 Disparage severely the alternative that the @samp{!} appears in.
 This alternative can still be used if it fits without reloading,
 but if reloading is needed, some other alternative will be used.

 @cindex @samp{^} in constraint
 @cindex caret
 @item ^
 This constraint is analogous to @samp{?} but it disparages slightly
 the alternative only if the operand with the @samp{^} needs a reload.

 @cindex @samp{$} in constraint
 @cindex dollar sign
 @item $
 This constraint is analogous to @samp{!} but it disparages severely
 the alternative only if the operand with the @samp{$} needs a reload.
 @end table

 When an insn pattern has multiple alternatives in its constraints, often
 the appearance of the assembler code is determined mostly by which
 alternative was matched.  When this is so, the C code for writing the
 assembler code can use the variable @code{which_alternative}, which is
 the ordinal number of the alternative that was actually satisfied (0 for
 the first, 1 for the second alternative, etc.).  @xref{Output Statement}.
 @end ifset
 @ifclear INTERNALS

 So the first alternative for the 68000's logical-or could be written as
 @code{"+m" (output) : "ir" (input)}.  The second could be @code{"+r"
 (output): "irm" (input)}.  However, the fact that two memory locations
 cannot be used in a single instruction prevents simply using @code{"+rm"
 (output) : "irm" (input)}.  Using multi-alternatives, this might be
 written as @code{"+m,r" (output) : "ir,irm" (input)}.  This describes
 all the available alternatives to the compiler, allowing it to choose
 the most efficient one for the current conditions.

 There is no way within the template to determine which alternative was
 chosen.  However you may be able to wrap your @code{asm} statements with
 builtins such as @code{__builtin_constant_p} to achieve the desired results.
 @end ifclear

 @ifset INTERNALS
 @node Class Preferences
 @subsection Register Class Preferences
 @cindex class preference constraints
 @cindex register class preference constraints

 @cindex voting between constraint alternatives
 The operand constraints have another function: they enable the compiler
 to decide which kind of hardware register a pseudo register is best
 allocated to.  The compiler examines the constraints that apply to the
 insns that use the pseudo register, looking for the machine-dependent
 letters such as @samp{d} and @samp{a} that specify classes of registers.
 The pseudo register is put in whichever class gets the most ``votes''.
 The constraint letters @samp{g} and @samp{r} also vote: they vote in
 favor of a general register.  The machine description says which registers
 are considered general.

 Of course, on some machines all registers are equivalent, and no register
 classes are defined.  Then none of this complexity is relevant.
 @end ifset

 @node Modifiers
 @subsection Constraint Modifier Characters
 @cindex modifiers in constraints
 @cindex constraint modifier characters

 @c prevent bad page break with this line
 Here are constraint modifier characters.

 @table @samp
 @cindex @samp{=} in constraint
 @item =
 Means that this operand is written to by this instruction:
 the previous value is discarded and replaced by new data.

 @cindex @samp{+} in constraint
 @item +
 Means that this operand is both read and written by the instruction.

 When the compiler fixes up the operands to satisfy the constraints,
 it needs to know which operands are read by the instruction and
 which are written by it.  @samp{=} identifies an operand which is only
 written; @samp{+} identifies an operand that is both read and written; all
 other operands are assumed to only be read.

 If you specify @samp{=} or @samp{+} in a constraint, you put it in the
 first character of the constraint string.

 @cindex @samp{&} in constraint
 @cindex earlyclobber operand
 @item &
 Means (in a particular alternative) that this operand is an
 @dfn{earlyclobber} operand, which is written before the instruction is
 finished using the input operands.  Therefore, this operand may not lie
 in a register that is read by the instruction or as part of any memory
 address.

 @samp{&} applies only to the alternative in which it is written.  In
 constraints with multiple alternatives, sometimes one alternative
 requires @samp{&} while others do not.  See, for example, the
 @samp{movdf} insn of the 68000.

 A operand which is read by the instruction can be tied to an earlyclobber
 operand if its only use as an input occurs before the early result is
 written.  Adding alternatives of this form often allows GCC to produce
 better code when only some of the read operands can be affected by the
 earlyclobber. See, for example, the @samp{mulsi3} insn of the ARM@.

 Furthermore, if the @dfn{earlyclobber} operand is also a read/write
 operand, then that operand is written only after it's used.

 @samp{&} does not obviate the need to write @samp{=} or @samp{+}.  As
 @dfn{earlyclobber} operands are always written, a read-only
 @dfn{earlyclobber} operand is ill-formed and will be rejected by the
 compiler.

 @cindex @samp{%} in constraint
 @item %
 Declares the instruction to be commutative for this operand and the
 following operand.  This means that the compiler may interchange the
 two operands if that is the cheapest way to make all operands fit the
 constraints.  @samp{%} applies to all alternatives and must appear as
 the first character in the constraint.  Only read-only operands can use
 @samp{%}.

 @ifset INTERNALS
 This is often used in patterns for addition instructions
 that really have only two operands: the result must go in one of the
 arguments.  Here for example, is how the 68000 halfword-add
 instruction is defined:

 @smallexample
 (define_insn "addhi3"
   [(set (match_operand:HI 0 "general_operand" "=m,r")
      (plus:HI (match_operand:HI 1 "general_operand" "%0,0")
               (match_operand:HI 2 "general_operand" "di,g")))]
   @dots{})
 @end smallexample
 @end ifset
 GCC can only handle one commutative pair in an asm; if you use more,
 the compiler may fail.  Note that you need not use the modifier if
 the two alternatives are strictly identical; this would only waste
 time in the reload pass.
 @ifset INTERNALS
 The modifier is not operational after
 register allocation, so the result of @code{define_peephole2}
 and @code{define_split}s performed after reload cannot rely on
 @samp{%} to make the intended insn match.

 @cindex @samp{#} in constraint
 @item #
 Says that all following characters, up to the next comma, are to be
 ignored as a constraint.  They are significant only for choosing
 register preferences.

 @cindex @samp{*} in constraint
 @item *
 Says that the following character should be ignored when choosing
 register preferences.  @samp{*} has no effect on the meaning of the
 constraint as a constraint, and no effect on reloading.  For LRA
 @samp{*} additionally disparages slightly the alternative if the
 following character matches the operand.

 Here is an example: the 68000 has an instruction to sign-extend a
 halfword in a data register, and can also sign-extend a value by
 copying it into an address register.  While either kind of register is
 acceptable, the constraints on an address-register destination are
 less strict, so it is best if register allocation makes an address
 register its goal.  Therefore, @samp{*} is used so that the @samp{d}
 constraint letter (for data register) is ignored when computing
 register preferences.

 @smallexample
 (define_insn "extendhisi2"
   [(set (match_operand:SI 0 "general_operand" "=*d,a")
         (sign_extend:SI
          (match_operand:HI 1 "general_operand" "0,g")))]
   @dots{})
 @end smallexample
 @end ifset
 @end table

 @node Machine Constraints
 @subsection Constraints for Particular Machines
 @cindex machine specific constraints
 @cindex constraints, machine specific

 Whenever possible, you should use the general-purpose constraint letters
 in @code{asm} arguments, since they will convey meaning more readily to
 people reading your code.  Failing that, use the constraint letters
 that usually have very similar meanings across architectures.  The most
 commonly used constraints are @samp{m} and @samp{r} (for memory and
 general-purpose registers respectively; @pxref{Simple Constraints}), and
 @samp{I}, usually the letter indicating the most common
 immediate-constant format.

 Each architecture defines additional constraints.  These constraints
 are used by the compiler itself for instruction generation, as well as
 for @code{asm} statements; therefore, some of the constraints are not
 particularly useful for @code{asm}.  Here is a summary of some of the
 machine-dependent constraints available on some particular machines;
 it includes both constraints that are useful for @code{asm} and
 constraints that aren't.  The compiler source file mentioned in the
 table heading for each architecture is the definitive reference for
 the meanings of that architecture's constraints.

 @c Please keep this table alphabetized by target!
 @table @emph
 @item AArch64 family---@file{config/aarch64/constraints.md}
 @table @code
 @item k
 The stack pointer register (@code{SP})

 @item w
 Floating point register, Advanced SIMD vector register or SVE vector register

 @item Upl
 One of the low eight SVE predicate registers (@code{P0} to @code{P7})

 @item Upa
 Any of the SVE predicate registers (@code{P0} to @code{P15})

 @item I
 Integer constant that is valid as an immediate operand in an @code{ADD}
 instruction

 @item J
 Integer constant that is valid as an immediate operand in a @code{SUB}
 instruction (once negated)

 @item K
 Integer constant that can be used with a 32-bit logical instruction

 @item L
 Integer constant that can be used with a 64-bit logical instruction

 @item M
 Integer constant that is valid as an immediate operand in a 32-bit @code{MOV}
 pseudo instruction. The @code{MOV} may be assembled to one of several different
 machine instructions depending on the value

 @item N
 Integer constant that is valid as an immediate operand in a 64-bit @code{MOV}
 pseudo instruction

 @item S
 An absolute symbolic address or a label reference

 @item Y
 Floating point constant zero

 @item Z
 Integer constant zero

 @item Ush
 The high part (bits 12 and upwards) of the pc-relative address of a symbol
 within 4GB of the instruction

 @item Q
 A memory address which uses a single base register with no offset

 @item Ump
 A memory address suitable for a load/store pair instruction in SI, DI, SF and
 DF modes

 @end table


 @item AMD GCN ---@file{config/gcn/constraints.md}
 @table @code
 @item I
 Immediate integer in the range @minus{}16 to 64

 @item J
 Immediate 16-bit signed integer

 @item Kf
 Immediate constant @minus{}1

 @item L
 Immediate 15-bit unsigned integer

 @item A
 Immediate constant that can be inlined in an instruction encoding: integer
 @minus{}16..64, or float 0.0, +/@minus{}0.5, +/@minus{}1.0, +/@minus{}2.0,
 +/@minus{}4.0, 1.0/(2.0*PI)

 @item B
 Immediate 32-bit signed integer that can be attached to an instruction encoding

 @item C
 Immediate 32-bit integer in range @minus{}16..4294967295 (i.e. 32-bit unsigned
 integer or @samp{A} constraint)

 @item DA
 Immediate 64-bit constant that can be split into two @samp{A} constants

 @item DB
 Immediate 64-bit constant that can be split into two @samp{B} constants

 @item U
 Any @code{unspec}

 @item Y
 Any @code{symbol_ref} or @code{label_ref}

 @item v
 VGPR register

 @item Sg
 SGPR register

 @item SD
 SGPR registers valid for instruction destinations, including VCC, M0 and EXEC

 @item SS
 SGPR registers valid for instruction sources, including VCC, M0, EXEC and SCC

 @item Sm
 SGPR registers valid as a source for scalar memory instructions (excludes M0
 and EXEC)

 @item Sv
 SGPR registers valid as a source or destination for vector instructions
 (excludes EXEC)

 @item ca
 All condition registers: SCC, VCCZ, EXECZ

 @item cs
 Scalar condition register: SCC

 @item cV
 Vector condition register: VCC, VCC_LO, VCC_HI

 @item e
 EXEC register (EXEC_LO and EXEC_HI)

 @item RB
 Memory operand with address space suitable for @code{buffer_*} instructions

 @item RF
 Memory operand with address space suitable for @code{flat_*} instructions

 @item RS
 Memory operand with address space suitable for @code{s_*} instructions

 @item RL
 Memory operand with address space suitable for @code{ds_*} LDS instructions

 @item RG
 Memory operand with address space suitable for @code{ds_*} GDS instructions

 @item RD
 Memory operand with address space suitable for any @code{ds_*} instructions

 @item RM
 Memory operand with address space suitable for @code{global_*} instructions

 @end table


 @item ARC ---@file{config/arc/constraints.md}
 @table @code
 @item q
 Registers usable in ARCompact 16-bit instructions: @code{r0}-@code{r3},
 @code{r12}-@code{r15}.  This constraint can only match when the @option{-mq}
 option is in effect.

 @item e
 Registers usable as base-regs of memory addresses in ARCompact 16-bit memory
 instructions: @code{r0}-@code{r3}, @code{r12}-@code{r15}, @code{sp}.
 This constraint can only match when the @option{-mq}
 option is in effect.
 @item D
 ARC FPX (dpfp) 64-bit registers. @code{D0}, @code{D1}.

 @item I
 A signed 12-bit integer constant.

 @item Cal
 constant for arithmetic/logical operations.  This might be any constant
 that can be put into a long immediate by the assmbler or linker without
 involving a PIC relocation.

 @item K
 A 3-bit unsigned integer constant.

 @item L
 A 6-bit unsigned integer constant.

 @item CnL
 One's complement of a 6-bit unsigned integer constant.

 @item CmL
 Two's complement of a 6-bit unsigned integer constant.

 @item M
 A 5-bit unsigned integer constant.

 @item O
 A 7-bit unsigned integer constant.

 @item P
 A 8-bit unsigned integer constant.

 @item H
 Any const_double value.
 @end table

 @item ARM family---@file{config/arm/constraints.md}
 @table @code

 @item h
 In Thumb state, the core registers @code{r8}-@code{r15}.

 @item k
 The stack pointer register.

 @item l
 In Thumb State the core registers @code{r0}-@code{r7}.  In ARM state this
 is an alias for the @code{r} constraint.

 @item t
 VFP floating-point registers @code{s0}-@code{s31}.  Used for 32 bit values.

 @item w
 VFP floating-point registers @code{d0}-@code{d31} and the appropriate
 subset @code{d0}-@code{d15} based on command line options.
 Used for 64 bit values only.  Not valid for Thumb1.

 @item y
 The iWMMX co-processor registers.

 @item z
 The iWMMX GR registers.

 @item G
 The floating-point constant 0.0

 @item I
 Integer that is valid as an immediate operand in a data processing
 instruction.  That is, an integer in the range 0 to 255 rotated by a
 multiple of 2

 @item J
 Integer in the range @minus{}4095 to 4095

 @item K
 Integer that satisfies constraint @samp{I} when inverted (ones complement)

 @item L
 Integer that satisfies constraint @samp{I} when negated (twos complement)

 @item M
 Integer in the range 0 to 32

 @item Q
 A memory reference where the exact address is in a single register
 (`@samp{m}' is preferable for @code{asm} statements)

 @item R
 An item in the constant pool

 @item S
 A symbol in the text segment of the current file

 @item Uv
 A memory reference suitable for VFP load/store insns (reg+constant offset)

 @item Uy
 A memory reference suitable for iWMMXt load/store instructions.

 @item Uq
 A memory reference suitable for the ARMv4 ldrsb instruction.
 @end table

 @item AVR family---@file{config/avr/constraints.md}
 @table @code
 @item l
 Registers from r0 to r15

 @item a
 Registers from r16 to r23

 @item d
 Registers from r16 to r31

 @item w
 Registers from r24 to r31.  These registers can be used in @samp{adiw} command

 @item e
 Pointer register (r26--r31)

 @item b
 Base pointer register (r28--r31)

 @item q
 Stack pointer register (SPH:SPL)

 @item t
 Temporary register r0

 @item x
 Register pair X (r27:r26)

 @item y
 Register pair Y (r29:r28)

 @item z
 Register pair Z (r31:r30)

 @item I
 Constant greater than @minus{}1, less than 64

 @item J
 Constant greater than @minus{}64, less than 1

 @item K
 Constant integer 2

 @item L
 Constant integer 0

 @item M
 Constant that fits in 8 bits

 @item N
 Constant integer @minus{}1

 @item O
 Constant integer 8, 16, or 24

 @item P
 Constant integer 1

 @item G
 A floating point constant 0.0

 @item Q
 A memory address based on Y or Z pointer with displacement.
 @end table

 @item Blackfin family---@file{config/bfin/constraints.md}
 @table @code
 @item a
 P register

 @item d
 D register

 @item z
 A call clobbered P register.

 @item q@var{n}
 A single register.  If @var{n} is in the range 0 to 7, the corresponding D
 register.  If it is @code{A}, then the register P0.

 @item D
 Even-numbered D register

 @item W
 Odd-numbered D register

 @item e
 Accumulator register.

 @item A
 Even-numbered accumulator register.

 @item B
 Odd-numbered accumulator register.

 @item b
 I register

 @item v
 B register

 @item f
 M register

 @item c
 Registers used for circular buffering, i.e.@: I, B, or L registers.

 @item C
 The CC register.

 @item t
 LT0 or LT1.

 @item k
 LC0 or LC1.

 @item u
 LB0 or LB1.

 @item x
 Any D, P, B, M, I or L register.

 @item y
 Additional registers typically used only in prologues and epilogues: RETS,
 RETN, RETI, RETX, RETE, ASTAT, SEQSTAT and USP.

 @item w
 Any register except accumulators or CC.

 @item Ksh
 Signed 16 bit integer (in the range @minus{}32768 to 32767)

 @item Kuh
 Unsigned 16 bit integer (in the range 0 to 65535)

 @item Ks7
 Signed 7 bit integer (in the range @minus{}64 to 63)

 @item Ku7
 Unsigned 7 bit integer (in the range 0 to 127)

 @item Ku5
 Unsigned 5 bit integer (in the range 0 to 31)

 @item Ks4
 Signed 4 bit integer (in the range @minus{}8 to 7)

 @item Ks3
 Signed 3 bit integer (in the range @minus{}3 to 4)

 @item Ku3
 Unsigned 3 bit integer (in the range 0 to 7)

 @item P@var{n}
 Constant @var{n}, where @var{n} is a single-digit constant in the range 0 to 4.

 @item PA
 An integer equal to one of the MACFLAG_XXX constants that is suitable for
 use with either accumulator.

 @item PB
 An integer equal to one of the MACFLAG_XXX constants that is suitable for
 use only with accumulator A1.

 @item M1
 Constant 255.

 @item M2
 Constant 65535.

 @item J
 An integer constant with exactly a single bit set.

 @item L
 An integer constant with all bits set except exactly one.

 @item H

 @item Q
 Any SYMBOL_REF.
 @end table

 @item CR16 Architecture---@file{config/cr16/cr16.h}
 @table @code

 @item b
 Registers from r0 to r14 (registers without stack pointer)

 @item t
 Register from r0 to r11 (all 16-bit registers)

 @item p
 Register from r12 to r15 (all 32-bit registers)

 @item I
 Signed constant that fits in 4 bits

 @item J
 Signed constant that fits in 5 bits

 @item K
 Signed constant that fits in 6 bits

 @item L
 Unsigned constant that fits in 4 bits

 @item M
 Signed constant that fits in 32 bits

 @item N
 Check for 64 bits wide constants for add/sub instructions

 @item G
 Floating point constant that is legal for store immediate
 @end table

 @item C-SKY---@file{config/csky/constraints.md}
 @table @code

 @item a
 The mini registers r0 - r7.

 @item b
 The low registers r0 - r15.

 @item c
 C register.

 @item y
 HI and LO registers.

 @item l
 LO register.

 @item h
 HI register.

 @item v
 Vector registers.

 @item z
 Stack pointer register (SP).
 @end table

 @ifset INTERNALS
 The C-SKY back end supports a large set of additional constraints
 that are only useful for instruction selection or splitting rather
 than inline asm, such as constraints representing constant integer
 ranges accepted by particular instruction encodings.
 Refer to the source code for details.
 @end ifset

 @item Epiphany---@file{config/epiphany/constraints.md}
 @table @code
 @item U16
 An unsigned 16-bit constant.

 @item K
 An unsigned 5-bit constant.

 @item L
 A signed 11-bit constant.

 @item Cm1
 A signed 11-bit constant added to @minus{}1.
 Can only match when the @option{-m1reg-@var{reg}} option is active.

 @item Cl1
 Left-shift of @minus{}1, i.e., a bit mask with a block of leading ones, the rest
 being a block of trailing zeroes.
 Can only match when the @option{-m1reg-@var{reg}} option is active.

 @item Cr1
 Right-shift of @minus{}1, i.e., a bit mask with a trailing block of ones, the
 rest being zeroes.  Or to put it another way, one less than a power of two.
 Can only match when the @option{-m1reg-@var{reg}} option is active.

 @item Cal
 Constant for arithmetic/logical operations.
 This is like @code{i}, except that for position independent code,
 no symbols / expressions needing relocations are allowed.

 @item Csy
 Symbolic constant for call/jump instruction.

 @item Rcs
 The register class usable in short insns.  This is a register class
 constraint, and can thus drive register allocation.
 This constraint won't match unless @option{-mprefer-short-insn-regs} is
 in effect.

 @item Rsc
 The the register class of registers that can be used to hold a
 sibcall call address.  I.e., a caller-saved register.

 @item Rct
 Core control register class.

 @item Rgs
 The register group usable in short insns.
 This constraint does not use a register class, so that it only
 passively matches suitable registers, and doesn't drive register allocation.

 @ifset INTERNALS
 @item Car
 Constant suitable for the addsi3_r pattern.  This is a valid offset
 For byte, halfword, or word addressing.
 @end ifset

 @item Rra
 Matches the return address if it can be replaced with the link register.

 @item Rcc
 Matches the integer condition code register.

 @item Sra
 Matches the return address if it is in a stack slot.

 @item Cfm
 Matches control register values to switch fp mode, which are encapsulated in
 @code{UNSPEC_FP_MODE}.
 @end table

 @item FRV---@file{config/frv/frv.h}
 @table @code
 @item a
 Register in the class @code{ACC_REGS} (@code{acc0} to @code{acc7}).

 @item b
 Register in the class @code{EVEN_ACC_REGS} (@code{acc0} to @code{acc7}).

 @item c
 Register in the class @code{CC_REGS} (@code{fcc0} to @code{fcc3} and
 @code{icc0} to @code{icc3}).

 @item d
 Register in the class @code{GPR_REGS} (@code{gr0} to @code{gr63}).

 @item e
 Register in the class @code{EVEN_REGS} (@code{gr0} to @code{gr63}).
 Odd registers are excluded not in the class but through the use of a machine
 mode larger than 4 bytes.

 @item f
 Register in the class @code{FPR_REGS} (@code{fr0} to @code{fr63}).

 @item h
 Register in the class @code{FEVEN_REGS} (@code{fr0} to @code{fr63}).
 Odd registers are excluded not in the class but through the use of a machine
 mode larger than 4 bytes.

 @item l
 Register in the class @code{LR_REG} (the @code{lr} register).

 @item q
 Register in the class @code{QUAD_REGS} (@code{gr2} to @code{gr63}).
 Register numbers not divisible by 4 are excluded not in the class but through
 the use of a machine mode larger than 8 bytes.

 @item t
 Register in the class @code{ICC_REGS} (@code{icc0} to @code{icc3}).

 @item u
 Register in the class @code{FCC_REGS} (@code{fcc0} to @code{fcc3}).

 @item v
 Register in the class @code{ICR_REGS} (@code{cc4} to @code{cc7}).

 @item w
 Register in the class @code{FCR_REGS} (@code{cc0} to @code{cc3}).

 @item x
 Register in the class @code{QUAD_FPR_REGS} (@code{fr0} to @code{fr63}).
 Register numbers not divisible by 4 are excluded not in the class but through
 the use of a machine mode larger than 8 bytes.

 @item z
 Register in the class @code{SPR_REGS} (@code{lcr} and @code{lr}).

 @item A
 Register in the class @code{QUAD_ACC_REGS} (@code{acc0} to @code{acc7}).

 @item B
 Register in the class @code{ACCG_REGS} (@code{accg0} to @code{accg7}).

 @item C
 Register in the class @code{CR_REGS} (@code{cc0} to @code{cc7}).

 @item G
 Floating point constant zero

 @item I
 6-bit signed integer constant

 @item J
 10-bit signed integer constant

 @item L
 16-bit signed integer constant

 @item M
 16-bit unsigned integer constant

 @item N
 12-bit signed integer constant that is negative---i.e.@: in the
 range of @minus{}2048 to @minus{}1

 @item O
 Constant zero

 @item P
 12-bit signed integer constant that is greater than zero---i.e.@: in the
 range of 1 to 2047.

 @end table

 @item FT32---@file{config/ft32/constraints.md}
 @table @code
 @item A
 An absolute address

 @item B
 An offset address

 @item W
 A register indirect memory operand

 @item e
 An offset address.

 @item f
 An offset address.

 @item O
 The constant zero or one

 @item I
 A 16-bit signed constant (@minus{}32768 @dots{} 32767)

 @item w
 A bitfield mask suitable for bext or bins

 @item x
 An inverted bitfield mask suitable for bext or bins

 @item L
 A 16-bit unsigned constant, multiple of 4 (0 @dots{} 65532)

 @item S
 A 20-bit signed constant (@minus{}524288 @dots{} 524287)

 @item b
 A constant for a bitfield width (1 @dots{} 16)

 @item KA
 A 10-bit signed constant (@minus{}512 @dots{} 511)

 @end table

 @item Hewlett-Packard PA-RISC---@file{config/pa/pa.h}
 @table @code
 @item a
 General register 1

 @item f
 Floating point register

 @item q
 Shift amount register

 @item x
 Floating point register (deprecated)

 @item y
 Upper floating point register (32-bit), floating point register (64-bit)

 @item Z
 Any register

 @item I
 Signed 11-bit integer constant

 @item J
 Signed 14-bit integer constant

 @item K
 Integer constant that can be deposited with a @code{zdepi} instruction

 @item L
 Signed 5-bit integer constant

 @item M
 Integer constant 0

 @item N
 Integer constant that can be loaded with a @code{ldil} instruction

 @item O
 Integer constant whose value plus one is a power of 2

 @item P
 Integer constant that can be used for @code{and} operations in @code{depi}
 and @code{extru} instructions

 @item S
 Integer constant 31

 @item U
 Integer constant 63

 @item G
 Floating-point constant 0.0

 @item A
 A @code{lo_sum} data-linkage-table memory operand

 @item Q
 A memory operand that can be used as the destination operand of an
 integer store instruction

 @item R
 A scaled or unscaled indexed memory operand

 @item T
 A memory operand for floating-point loads and stores

 @item W
 A register indirect memory operand
 @end table

 @item Intel IA-64---@file{config/ia64/ia64.h}
 @table @code
 @item a
 General register @code{r0} to @code{r3} for @code{addl} instruction

 @item b
 Branch register

 @item c
 Predicate register (@samp{c} as in ``conditional'')

 @item d
 Application register residing in M-unit

 @item e
 Application register residing in I-unit

 @item f
 Floating-point register

 @item m
 Memory operand.  If used together with @samp{<} or @samp{>},
 the operand can have postincrement and postdecrement which
 require printing with @samp{%Pn} on IA-64.

 @item G
 Floating-point constant 0.0 or 1.0

 @item I
 14-bit signed integer constant

 @item J
 22-bit signed integer constant

 @item K
 8-bit signed integer constant for logical instructions

 @item L
 8-bit adjusted signed integer constant for compare pseudo-ops

 @item M
 6-bit unsigned integer constant for shift counts

 @item N
 9-bit signed integer constant for load and store postincrements

 @item O
 The constant zero

 @item P
 0 or @minus{}1 for @code{dep} instruction

 @item Q
 Non-volatile memory for floating-point loads and stores

 @item R
 Integer constant in the range 1 to 4 for @code{shladd} instruction

 @item S
 Memory operand except postincrement and postdecrement.  This is
 now roughly the same as @samp{m} when not used together with @samp{<}
 or @samp{>}.
 @end table

 @item M32C---@file{config/m32c/m32c.c}
 @table @code
 @item Rsp
 @itemx Rfb
 @itemx Rsb
 @samp{$sp}, @samp{$fb}, @samp{$sb}.

 @item Rcr
 Any control register, when they're 16 bits wide (nothing if control
 registers are 24 bits wide)

 @item Rcl
 Any control register, when they're 24 bits wide.

 @item R0w
 @itemx R1w
 @itemx R2w
 @itemx R3w
 $r0, $r1, $r2, $r3.

 @item R02
 $r0 or $r2, or $r2r0 for 32 bit values.

 @item R13
 $r1 or $r3, or $r3r1 for 32 bit values.

 @item Rdi
 A register that can hold a 64 bit value.

 @item Rhl
 $r0 or $r1 (registers with addressable high/low bytes)

 @item R23
 $r2 or $r3

 @item Raa
 Address registers

 @item Raw
 Address registers when they're 16 bits wide.

 @item Ral
 Address registers when they're 24 bits wide.

 @item Rqi
 Registers that can hold QI values.

 @item Rad
 Registers that can be used with displacements ($a0, $a1, $sb).

 @item Rsi
 Registers that can hold 32 bit values.

 @item Rhi
 Registers that can hold 16 bit values.

 @item Rhc
 Registers chat can hold 16 bit values, including all control
 registers.

 @item Rra
 $r0 through R1, plus $a0 and $a1.

 @item Rfl
 The flags register.

 @item Rmm
 The memory-based pseudo-registers $mem0 through $mem15.

 @item Rpi
 Registers that can hold pointers (16 bit registers for r8c, m16c; 24
 bit registers for m32cm, m32c).

 @item Rpa
 Matches multiple registers in a PARALLEL to form a larger register.
 Used to match function return values.

 @item Is3
 @minus{}8 @dots{} 7

 @item IS1
 @minus{}128 @dots{} 127

 @item IS2
 @minus{}32768 @dots{} 32767

 @item IU2
 0 @dots{} 65535

 @item In4
 @minus{}8 @dots{} @minus{}1 or 1 @dots{} 8

 @item In5
 @minus{}16 @dots{} @minus{}1 or 1 @dots{} 16

 @item In6
 @minus{}32 @dots{} @minus{}1 or 1 @dots{} 32

 @item IM2
 @minus{}65536 @dots{} @minus{}1

 @item Ilb
 An 8 bit value with exactly one bit set.

 @item Ilw
 A 16 bit value with exactly one bit set.

 @item Sd
 The common src/dest memory addressing modes.

 @item Sa
 Memory addressed using $a0 or $a1.

 @item Si
 Memory addressed with immediate addresses.

 @item Ss
 Memory addressed using the stack pointer ($sp).

 @item Sf
 Memory addressed using the frame base register ($fb).

 @item Ss
 Memory addressed using the small base register ($sb).

 @item S1
 $r1h
 @end table

 @item MicroBlaze---@file{config/microblaze/constraints.md}
 @table @code
 @item d
 A general register (@code{r0} to @code{r31}).

 @item z
 A status register (@code{rmsr}, @code{$fcc1} to @code{$fcc7}).

 @end table

 @item MIPS---@file{config/mips/constraints.md}
 @table @code
 @item d
 A general-purpose register.  This is equivalent to @code{r} unless
 generating MIPS16 code, in which case the MIPS16 register set is used.

 @item f
 A floating-point register (if available).

 @item h
 Formerly the @code{hi} register.  This constraint is no longer supported.

 @item l
 The @code{lo} register.  Use this register to store values that are
 no bigger than a word.

 @item x
 The concatenated @code{hi} and @code{lo} registers.  Use this register
 to store doubleword values.

 @item c
 A register suitable for use in an indirect jump.  This will always be
 @code{$25} for @option{-mabicalls}.

 @item v
 Register @code{$3}.  Do not use this constraint in new code;
 it is retained only for compatibility with glibc.

 @item y
 Equivalent to @code{r}; retained for backwards compatibility.

 @item z
 A floating-point condition code register.

 @item I
 A signed 16-bit constant (for arithmetic instructions).

 @item J
 Integer zero.

 @item K
 An unsigned 16-bit constant (for logic instructions).

 @item L
 A signed 32-bit constant in which the lower 16 bits are zero.
 Such constants can be loaded using @code{lui}.

 @item M
 A constant that cannot be loaded using @code{lui}, @code{addiu}
 or @code{ori}.

 @item N
 A constant in the range @minus{}65535 to @minus{}1 (inclusive).

 @item O
 A signed 15-bit constant.

 @item P
 A constant in the range 1 to 65535 (inclusive).

 @item G
 Floating-point zero.

 @item R
 An address that can be used in a non-macro load or store.

 @item ZC
 A memory operand whose address is formed by a base register and offset
 that is suitable for use in instructions with the same addressing mode
 as @code{ll} and @code{sc}.

 @item ZD
 An address suitable for a @code{prefetch} instruction, or for any other
 instruction with the same addressing mode as @code{prefetch}.
 @end table

 @item Motorola 680x0---@file{config/m68k/constraints.md}
 @table @code
 @item a
 Address register

 @item d
 Data register

 @item f
 68881 floating-point register, if available

 @item I
 Integer in the range 1 to 8

 @item J
 16-bit signed number

 @item K
 Signed number whose magnitude is greater than 0x80

 @item L
 Integer in the range @minus{}8 to @minus{}1

 @item M
 Signed number whose magnitude is greater than 0x100

 @item N
 Range 24 to 31, rotatert:SI 8 to 1 expressed as rotate

 @item O
 16 (for rotate using swap)

 @item P
 Range 8 to 15, rotatert:HI 8 to 1 expressed as rotate

 @item R
 Numbers that mov3q can handle

 @item G
 Floating point constant that is not a 68881 constant

 @item S
 Operands that satisfy 'm' when -mpcrel is in effect

 @item T
 Operands that satisfy 's' when -mpcrel is not in effect

 @item Q
 Address register indirect addressing mode

 @item U
 Register offset addressing

 @item W
 const_call_operand

 @item Cs
 symbol_ref or const

 @item Ci
 const_int

 @item C0
 const_int 0

 @item Cj
 Range of signed numbers that don't fit in 16 bits

 @item Cmvq
 Integers valid for mvq

 @item Capsw
 Integers valid for a moveq followed by a swap

 @item Cmvz
 Integers valid for mvz

 @item Cmvs
 Integers valid for mvs

 @item Ap
 push_operand

 @item Ac
 Non-register operands allowed in clr

 @end table

 @item Moxie---@file{config/moxie/constraints.md}
 @table @code
 @item A
 An absolute address

 @item B
 An offset address

 @item W
 A register indirect memory operand

 @item I
 A constant in the range of 0 to 255.

 @item N
 A constant in the range of 0 to @minus{}255.

 @end table

 @item MSP430--@file{config/msp430/constraints.md}
 @table @code

 @item R12
 Register R12.

 @item R13
 Register R13.

 @item K
 Integer constant 1.

 @item L
 Integer constant -1^20..1^19.

 @item M
 Integer constant 1-4.

 @item Ya
 Memory references which do not require an extended MOVX instruction.

 @item Yl
 Memory reference, labels only.

 @item Ys
 Memory reference, stack only.

 @end table

 @item NDS32---@file{config/nds32/constraints.md}
 @table @code
 @item w
 LOW register class $r0 to $r7 constraint for V3/V3M ISA.
 @item l
 LOW register class $r0 to $r7.
 @item d
 MIDDLE register class $r0 to $r11, $r16 to $r19.
 @item h
 HIGH register class $r12 to $r14, $r20 to $r31.
 @item t
 Temporary assist register $ta (i.e.@: $r15).
 @item k
 Stack register $sp.
 @item Iu03
 Unsigned immediate 3-bit value.
 @item In03
 Negative immediate 3-bit value in the range of @minus{}7--0.
 @item Iu04
 Unsigned immediate 4-bit value.
 @item Is05
 Signed immediate 5-bit value.
 @item Iu05
 Unsigned immediate 5-bit value.
 @item In05
 Negative immediate 5-bit value in the range of @minus{}31--0.
 @item Ip05
 Unsigned immediate 5-bit value for movpi45 instruction with range 16--47.
 @item Iu06
 Unsigned immediate 6-bit value constraint for addri36.sp instruction.
 @item Iu08
 Unsigned immediate 8-bit value.
 @item Iu09
 Unsigned immediate 9-bit value.
 @item Is10
 Signed immediate 10-bit value.
 @item Is11
 Signed immediate 11-bit value.
 @item Is15
 Signed immediate 15-bit value.
 @item Iu15
 Unsigned immediate 15-bit value.
 @item Ic15
 A constant which is not in the range of imm15u but ok for bclr instruction.
 @item Ie15
 A constant which is not in the range of imm15u but ok for bset instruction.
 @item It15
 A constant which is not in the range of imm15u but ok for btgl instruction.
 @item Ii15
 A constant whose compliment value is in the range of imm15u
 and ok for bitci instruction.
 @item Is16
 Signed immediate 16-bit value.
 @item Is17
 Signed immediate 17-bit value.
 @item Is19
 Signed immediate 19-bit value.
 @item Is20
 Signed immediate 20-bit value.
 @item Ihig
 The immediate value that can be simply set high 20-bit.
 @item Izeb
 The immediate value 0xff.
 @item Izeh
 The immediate value 0xffff.
 @item Ixls
 The immediate value 0x01.
 @item Ix11
 The immediate value 0x7ff.
 @item Ibms
 The immediate value with power of 2.
 @item Ifex
 The immediate value with power of 2 minus 1.
 @item U33
 Memory constraint for 333 format.
 @item U45
 Memory constraint for 45 format.
 @item U37
 Memory constraint for 37 format.
 @end table

 @item Nios II family---@file{config/nios2/constraints.md}
 @table @code

 @item I
 Integer that is valid as an immediate operand in an
 instruction taking a signed 16-bit number. Range
 @minus{}32768 to 32767.

 @item J
 Integer that is valid as an immediate operand in an
 instruction taking an unsigned 16-bit number. Range
 0 to 65535.

 @item K
 Integer that is valid as an immediate operand in an
 instruction taking only the upper 16-bits of a
 32-bit number. Range 32-bit numbers with the lower
 16-bits being 0.

 @item L
 Integer that is valid as an immediate operand for a
 shift instruction. Range 0 to 31.

 @item M
 Integer that is valid as an immediate operand for
 only the value 0. Can be used in conjunction with
 the format modifier @code{z} to use @code{r0}
 instead of @code{0} in the assembly output.

 @item N
 Integer that is valid as an immediate operand for
 a custom instruction opcode. Range 0 to 255.

 @item P
 An immediate operand for R2 andchi/andci instructions.

 @item S
 Matches immediates which are addresses in the small
 data section and therefore can be added to @code{gp}
 as a 16-bit immediate to re-create their 32-bit value.

 @item U
 Matches constants suitable as an operand for the rdprs and
 cache instructions.

 @item v
 A memory operand suitable for Nios II R2 load/store
 exclusive instructions.

 @item w
 A memory operand suitable for load/store IO and cache
 instructions.

 @ifset INTERNALS
 @item T
 A @code{const} wrapped @code{UNSPEC} expression,
 representing a supported PIC or TLS relocation.
 @end ifset

 @end table

 @item OpenRISC---@file{config/or1k/constraints.md}
 @table @code
 @item I
 Integer that is valid as an immediate operand in an
 instruction taking a signed 16-bit number. Range
 @minus{}32768 to 32767.

 @item K
 Integer that is valid as an immediate operand in an
 instruction taking an unsigned 16-bit number. Range
 0 to 65535.

 @item M
 Signed 16-bit constant shifted left 16 bits. (Used with @code{l.movhi})

 @item O
 Zero

 @ifset INTERNALS
 @item c
 Register usable for sibcalls.
 @end ifset

 @end table

 @item PDP-11---@file{config/pdp11/constraints.md}
 @table @code
 @item a
 Floating point registers AC0 through AC3.  These can be loaded from/to
 memory with a single instruction.

 @item d
 Odd numbered general registers (R1, R3, R5).  These are used for
 16-bit multiply operations.

 @item D
 A memory reference that is encoded within the opcode, but not
 auto-increment or auto-decrement.

 @item f
 Any of the floating point registers (AC0 through AC5).

 @item G
 Floating point constant 0.

 @item h
 Floating point registers AC4 and AC5.  These cannot be loaded from/to
 memory with a single instruction.

 @item I
 An integer constant that fits in 16 bits.

 @item J
 An integer constant whose low order 16 bits are zero.

 @item K
 An integer constant that does not meet the constraints for codes
 @samp{I} or @samp{J}.

 @item L
 The integer constant 1.

 @item M
 The integer constant @minus{}1.

 @item N
 The integer constant 0.

 @item O
 Integer constants 0 through 3; shifts by these
 amounts are handled as multiple single-bit shifts rather than a single
 variable-length shift.

 @item Q
 A memory reference which requires an additional word (address or
 offset) after the opcode.

 @item R
 A memory reference that is encoded within the opcode.

 @end table

 @item PowerPC and IBM RS6000---@file{config/rs6000/constraints.md}
 @table @code
 @item b
 Address base register

 @item d
 Floating point register (containing 64-bit value)

 @item f
 Floating point register (containing 32-bit value)

 @item v
 Altivec vector register

 @item wa
 Any VSX register if the @option{-mvsx} option was used or NO_REGS.

 When using any of the register constraints (@code{wa}, @code{wd},
 @code{wf}, @code{wg}, @code{wh}, @code{wi}, @code{wj}, @code{wk},
 @code{wl}, @code{wm}, @code{wo}, @code{wp}, @code{wq}, @code{ws},
 @code{wt}, @code{wu}, @code{wv}, @code{ww}, or @code{wy})
 that take VSX registers, you must use @code{%x<n>} in the template so
 that the correct register is used.  Otherwise the register number
 output in the assembly file will be incorrect if an Altivec register
 is an operand of a VSX instruction that expects VSX register
 numbering.

 @smallexample
 asm ("xvadddp %x0,%x1,%x2"
      : "=wa" (v1)
      : "wa" (v2), "wa" (v3));
 @end smallexample

 @noindent
 is correct, but:

 @smallexample
 asm ("xvadddp %0,%1,%2"
      : "=wa" (v1)
      : "wa" (v2), "wa" (v3));
 @end smallexample

 @noindent
 is not correct.

 If an instruction only takes Altivec registers, you do not want to use
 @code{%x<n>}.

 @smallexample
 asm ("xsaddqp %0,%1,%2"
      : "=v" (v1)
      : "v" (v2), "v" (v3));
 @end smallexample

 @noindent
 is correct because the @code{xsaddqp} instruction only takes Altivec
 registers, while:

 @smallexample
 asm ("xsaddqp %x0,%x1,%x2"
      : "=v" (v1)
      : "v" (v2), "v" (v3));
 @end smallexample

 @noindent
 is incorrect.

 @item wb
 Altivec register if @option{-mcpu=power9} is used or NO_REGS.

 @item wd
 VSX vector register to hold vector double data or NO_REGS.

 @item we
 VSX register if the @option{-mcpu=power9} and @option{-m64} options
 were used or NO_REGS.

 @item wf
 VSX vector register to hold vector float data or NO_REGS.

 @item wg
 If @option{-mmfpgpr} was used, a floating point register or NO_REGS.

 @item wh
 Floating point register if direct moves are available, or NO_REGS.

 @item wi
 FP or VSX register to hold 64-bit integers for VSX insns or NO_REGS.

 @item wj
 FP or VSX register to hold 64-bit integers for direct moves or NO_REGS.

 @item wk
 FP or VSX register to hold 64-bit doubles for direct moves or NO_REGS.

 @item wl
 Floating point register if the LFIWAX instruction is enabled or NO_REGS.

 @item wm
 VSX register if direct move instructions are enabled, or NO_REGS.

 @item wn
 No register (NO_REGS).

 @item wo
 VSX register to use for ISA 3.0 vector instructions, or NO_REGS.

 @item wp
 VSX register to use for IEEE 128-bit floating point TFmode, or NO_REGS.

 @item wq
 VSX register to use for IEEE 128-bit floating point, or NO_REGS.

 @item wr
 General purpose register if 64-bit instructions are enabled or NO_REGS.

 @item ws
 VSX vector register to hold scalar double values or NO_REGS.

 @item wt
 VSX vector register to hold 128 bit integer or NO_REGS.

 @item wu
 Altivec register to use for float/32-bit int loads/stores  or NO_REGS.

 @item wv
 Altivec register to use for double loads/stores  or NO_REGS.

 @item ww
 FP or VSX register to perform float operations under @option{-mvsx} or NO_REGS.

 @item wx
 Floating point register if the STFIWX instruction is enabled or NO_REGS.

 @item wy
 FP or VSX register to perform ISA 2.07 float ops or NO_REGS.

 @item wz
 Floating point register if the LFIWZX instruction is enabled or NO_REGS.

 @item wA
 Address base register if 64-bit instructions are enabled or NO_REGS.

 @item wB
 Signed 5-bit constant integer that can be loaded into an altivec register.

 @item wD
 Int constant that is the element number of the 64-bit scalar in a vector.

 @item wE
 Vector constant that can be loaded with the XXSPLTIB instruction.

 @item wF
 Memory operand suitable for power8 GPR load fusion

 @item wG
 Memory operand suitable for TOC fusion memory references.

 @item wH
 Altivec register if @option{-mvsx-small-integer}.

 @item wI
 Floating point register if @option{-mvsx-small-integer}.

 @item wJ
 FP register if @option{-mvsx-small-integer} and @option{-mpower9-vector}.

 @item wK
 Altivec register if @option{-mvsx-small-integer} and @option{-mpower9-vector}.

 @item wL
 Int constant that is the element number that the MFVSRLD instruction.
 targets.

 @item wM
 Match vector constant with all 1's if the XXLORC instruction is available.

 @item wO
 A memory operand suitable for the ISA 3.0 vector d-form instructions.

 @item wQ
 A memory address that will work with the @code{lq} and @code{stq}
 instructions.

 @item wS
 Vector constant that can be loaded with XXSPLTIB & sign extension.

 @item h
 @samp{VRSAVE}, @samp{CTR}, or @samp{LINK} register

 @item c
 @samp{CTR} register

 @item l
 @samp{LINK} register

 @item x
 @samp{CR} register (condition register) number 0

 @item y
 @samp{CR} register (condition register)

 @item z
 @samp{XER[CA]} carry bit (part of the XER register)

 @item I
 Signed 16-bit constant

 @item J
 Unsigned 16-bit constant shifted left 16 bits (use @samp{L} instead for
 @code{SImode} constants)

 @item K
 Unsigned 16-bit constant

 @item L
 Signed 16-bit constant shifted left 16 bits

 @item M
 Constant larger than 31

 @item N
 Exact power of 2

 @item O
 Zero

 @item P
 Constant whose negation is a signed 16-bit constant

 @item G
 Floating point constant that can be loaded into a register with one
 instruction per word

 @item H
 Integer/Floating point constant that can be loaded into a register using
 three instructions

 @item m
 Memory operand.
 Normally, @code{m} does not allow addresses that update the base register.
 If @samp{<} or @samp{>} constraint is also used, they are allowed and
 therefore on PowerPC targets in that case it is only safe
 to use @samp{m<>} in an @code{asm} statement if that @code{asm} statement
 accesses the operand exactly once.  The @code{asm} statement must also
 use @samp{%U@var{<opno>}} as a placeholder for the ``update'' flag in the
 corresponding load or store instruction.  For example:

 @smallexample
 asm ("st%U0 %1,%0" : "=m<>" (mem) : "r" (val));
 @end smallexample

 is correct but:

 @smallexample
 asm ("st %1,%0" : "=m<>" (mem) : "r" (val));
 @end smallexample

 is not.

 @item es
 A ``stable'' memory operand; that is, one which does not include any
 automodification of the base register.  This used to be useful when
 @samp{m} allowed automodification of the base register, but as those are now only
 allowed when @samp{<} or @samp{>} is used, @samp{es} is basically the same
 as @samp{m} without @samp{<} and @samp{>}.

 @item Q
 Memory operand that is an offset from a register (it is usually better
 to use @samp{m} or @samp{es} in @code{asm} statements)

 @item Z
 Memory operand that is an indexed or indirect from a register (it is
 usually better to use @samp{m} or @samp{es} in @code{asm} statements)

 @item R
 AIX TOC entry

 @item a
 Address operand that is an indexed or indirect from a register (@samp{p} is
 preferable for @code{asm} statements)

 @item U
 System V Release 4 small data area reference

 @item W
 Vector constant that does not require memory

 @item j
 Vector constant that is all zeros.

 @end table

 @item RL78---@file{config/rl78/constraints.md}
 @table @code

 @item Int3
 An integer constant in the range 1 @dots{} 7.
 @item Int8
 An integer constant in the range 0 @dots{} 255.
 @item J
 An integer constant in the range @minus{}255 @dots{} 0
 @item K
 The integer constant 1.
 @item L
 The integer constant -1.
 @item M
 The integer constant 0.
 @item N
 The integer constant 2.
 @item O
 The integer constant -2.
 @item P
 An integer constant in the range 1 @dots{} 15.
 @item Qbi
 The built-in compare types--eq, ne, gtu, ltu, geu, and leu.
 @item Qsc
 The synthetic compare types--gt, lt, ge, and le.
 @item Wab
 A memory reference with an absolute address.
 @item Wbc
 A memory reference using @code{BC} as a base register, with an optional offset.
 @item Wca
 A memory reference using @code{AX}, @code{BC}, @code{DE}, or @code{HL} for the address, for calls.
 @item Wcv
 A memory reference using any 16-bit register pair for the address, for calls.
 @item Wd2
 A memory reference using @code{DE} as a base register, with an optional offset.
 @item Wde
 A memory reference using @code{DE} as a base register, without any offset.
 @item Wfr
 Any memory reference to an address in the far address space.
 @item Wh1
 A memory reference using @code{HL} as a base register, with an optional one-byte offset.
 @item Whb
 A memory reference using @code{HL} as a base register, with @code{B} or @code{C} as the index register.
 @item Whl
 A memory reference using @code{HL} as a base register, without any offset.
 @item Ws1
 A memory reference using @code{SP} as a base register, with an optional one-byte offset.
 @item Y
 Any memory reference to an address in the near address space.
 @item A
 The @code{AX} register.
 @item B
 The @code{BC} register.
 @item D
 The @code{DE} register.
 @item R
 @code{A} through @code{L} registers.
 @item S
 The @code{SP} register.
 @item T
 The @code{HL} register.
 @item Z08W
 The 16-bit @code{R8} register.
 @item Z10W
 The 16-bit @code{R10} register.
 @item Zint
 The registers reserved for interrupts (@code{R24} to @code{R31}).
 @item a
 The @code{A} register.
 @item b
 The @code{B} register.
 @item c
 The @code{C} register.
 @item d
 The @code{D} register.
 @item e
 The @code{E} register.
 @item h
 The @code{H} register.
 @item l
 The @code{L} register.
 @item v
 The virtual registers.
 @item w
 The @code{PSW} register.
 @item x
 The @code{X} register.

 @end table

 @item RISC-V---@file{config/riscv/constraints.md}
 @table @code

 @item f
 A floating-point register (if available).

 @item I
 An I-type 12-bit signed immediate.

 @item J
 Integer zero.

 @item K
 A 5-bit unsigned immediate for CSR access instructions.

 @item A
 An address that is held in a general-purpose register.

 @end table

 @item RX---@file{config/rx/constraints.md}
 @table @code
 @item Q
 An address which does not involve register indirect addressing or
 pre/post increment/decrement addressing.

 @item Symbol
 A symbol reference.

 @item Int08
 A constant in the range @minus{}256 to 255, inclusive.

 @item Sint08
 A constant in the range @minus{}128 to 127, inclusive.

 @item Sint16
 A constant in the range @minus{}32768 to 32767, inclusive.

 @item Sint24
 A constant in the range @minus{}8388608 to 8388607, inclusive.

 @item Uint04
 A constant in the range 0 to 15, inclusive.

 @end table

 @item S/390 and zSeries---@file{config/s390/s390.h}
 @table @code
 @item a
 Address register (general purpose register except r0)

 @item c
 Condition code register

 @item d
 Data register (arbitrary general purpose register)

 @item f
 Floating-point register

 @item I
 Unsigned 8-bit constant (0--255)

 @item J
 Unsigned 12-bit constant (0--4095)

 @item K
 Signed 16-bit constant (@minus{}32768--32767)

 @item L
 Value appropriate as displacement.
 @table @code
 @item (0..4095)
 for short displacement
 @item (@minus{}524288..524287)
 for long displacement
 @end table

 @item M
 Constant integer with a value of 0x7fffffff.

 @item N
 Multiple letter constraint followed by 4 parameter letters.
 @table @code
 @item 0..9:
 number of the part counting from most to least significant
 @item H,Q:
 mode of the part
 @item D,S,H:
 mode of the containing operand
 @item 0,F:
 value of the other parts (F---all bits set)
 @end table
 The constraint matches if the specified part of a constant
 has a value different from its other parts.

 @item Q
 Memory reference without index register and with short displacement.

 @item R
 Memory reference with index register and short displacement.

 @item S
 Memory reference without index register but with long displacement.

 @item T
 Memory reference with index register and long displacement.

 @item U
 Pointer with short displacement.

 @item W
 Pointer with long displacement.

 @item Y
 Shift count operand.

 @end table

 @need 1000
 @item SPARC---@file{config/sparc/sparc.h}
 @table @code
 @item f
 Floating-point register on the SPARC-V8 architecture and
 lower floating-point register on the SPARC-V9 architecture.

 @item e
 Floating-point register.  It is equivalent to @samp{f} on the
 SPARC-V8 architecture and contains both lower and upper
 floating-point registers on the SPARC-V9 architecture.

 @item c
 Floating-point condition code register.

 @item d
 Lower floating-point register.  It is only valid on the SPARC-V9
 architecture when the Visual Instruction Set is available.

 @item b
 Floating-point register.  It is only valid on the SPARC-V9 architecture
 when the Visual Instruction Set is available.

 @item h
 64-bit global or out register for the SPARC-V8+ architecture.

 @item C
 The constant all-ones, for floating-point.

 @item A
 Signed 5-bit constant

 @item D
 A vector constant

 @item I
 Signed 13-bit constant

 @item J
 Zero

 @item K
 32-bit constant with the low 12 bits clear (a constant that can be
 loaded with the @code{sethi} instruction)

 @item L
 A constant in the range supported by @code{movcc} instructions (11-bit
 signed immediate)

 @item M
 A constant in the range supported by @code{movrcc} instructions (10-bit
 signed immediate)

 @item N
 Same as @samp{K}, except that it verifies that bits that are not in the
 lower 32-bit range are all zero.  Must be used instead of @samp{K} for
 modes wider than @code{SImode}

 @item O
 The constant 4096

 @item G
 Floating-point zero

 @item H
 Signed 13-bit constant, sign-extended to 32 or 64 bits

 @item P
 The constant -1

 @item Q
 Floating-point constant whose integral representation can
 be moved into an integer register using a single sethi
 instruction

 @item R
 Floating-point constant whose integral representation can
 be moved into an integer register using a single mov
 instruction

 @item S
 Floating-point constant whose integral representation can
 be moved into an integer register using a high/lo_sum
 instruction sequence

 @item T
 Memory address aligned to an 8-byte boundary

 @item U
 Even register

 @item W
 Memory address for @samp{e} constraint registers

 @item w
 Memory address with only a base register

 @item Y
 Vector zero

 @end table

 @item SPU---@file{config/spu/spu.h}
 @table @code
 @item a
 An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is treated as a 64 bit value.

 @item c
 An immediate for and/xor/or instructions.  const_int is treated as a 64 bit value.

 @item d
 An immediate for the @code{iohl} instruction.  const_int is treated as a 64 bit value.

 @item f
 An immediate which can be loaded with @code{fsmbi}.

 @item A
 An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is treated as a 32 bit value.

 @item B
 An immediate for most arithmetic instructions.  const_int is treated as a 32 bit value.

 @item C
 An immediate for and/xor/or instructions.  const_int is treated as a 32 bit value.

 @item D
 An immediate for the @code{iohl} instruction.  const_int is treated as a 32 bit value.

 @item I
 A constant in the range [@minus{}64, 63] for shift/rotate instructions.

 @item J
 An unsigned 7-bit constant for conversion/nop/channel instructions.

 @item K
 A signed 10-bit constant for most arithmetic instructions.

 @item M
 A signed 16 bit immediate for @code{stop}.

 @item N
 An unsigned 16-bit constant for @code{iohl} and @code{fsmbi}.

 @item O
 An unsigned 7-bit constant whose 3 least significant bits are 0.

 @item P
 An unsigned 3-bit constant for 16-byte rotates and shifts

 @item R
 Call operand, reg, for indirect calls

 @item S
 Call operand, symbol, for relative calls.

 @item T
 Call operand, const_int, for absolute calls.

 @item U
 An immediate which can be loaded with the il/ila/ilh/ilhu instructions.  const_int is sign extended to 128 bit.

 @item W
 An immediate for shift and rotate instructions.  const_int is treated as a 32 bit value.

 @item Y
 An immediate for and/xor/or instructions.  const_int is sign extended as a 128 bit.

 @item Z
 An immediate for the @code{iohl} instruction.  const_int is sign extended to 128 bit.

 @end table

 @item TI C6X family---@file{config/c6x/constraints.md}
 @table @code
 @item a
 Register file A (A0--A31).

 @item b
 Register file B (B0--B31).

 @item A
 Predicate registers in register file A (A0--A2 on C64X and
 higher, A1 and A2 otherwise).

 @item B
 Predicate registers in register file B (B0--B2).

 @item C
 A call-used register in register file B (B0--B9, B16--B31).

 @item Da
 Register file A, excluding predicate registers (A3--A31,
 plus A0 if not C64X or higher).

 @item Db
 Register file B, excluding predicate registers (B3--B31).

 @item Iu4
 Integer constant in the range 0 @dots{} 15.

 @item Iu5
 Integer constant in the range 0 @dots{} 31.

 @item In5
 Integer constant in the range @minus{}31 @dots{} 0.

 @item Is5
 Integer constant in the range @minus{}16 @dots{} 15.

 @item I5x
 Integer constant that can be the operand of an ADDA or a SUBA insn.

 @item IuB
 Integer constant in the range 0 @dots{} 65535.

 @item IsB
 Integer constant in the range @minus{}32768 @dots{} 32767.

 @item IsC
 Integer constant in the range @math{-2^{20}} @dots{} @math{2^{20} - 1}.

 @item Jc
 Integer constant that is a valid mask for the clr instruction.

 @item Js
 Integer constant that is a valid mask for the set instruction.

 @item Q
 Memory location with A base register.

 @item R
 Memory location with B base register.

 @ifset INTERNALS
 @item S0
 On C64x+ targets, a GP-relative small data reference.

 @item S1
 Any kind of @code{SYMBOL_REF}, for use in a call address.

 @item Si
 Any kind of immediate operand, unless it matches the S0 constraint.

 @item T
 Memory location with B base register, but not using a long offset.

 @item W
 A memory operand with an address that cannot be used in an unaligned access.

 @end ifset
 @item Z
 Register B14 (aka DP).

 @end table

 @item TILE-Gx---@file{config/tilegx/constraints.md}
 @table @code
 @item R00
 @itemx R01
 @itemx R02
 @itemx R03
 @itemx R04
 @itemx R05
 @itemx R06
 @itemx R07
 @itemx R08
 @itemx R09
 @itemx R10
 Each of these represents a register constraint for an individual
 register, from r0 to r10.

 @item I
 Signed 8-bit integer constant.

 @item J
 Signed 16-bit integer constant.

 @item K
 Unsigned 16-bit integer constant.

 @item L
 Integer constant that fits in one signed byte when incremented by one
 (@minus{}129 @dots{} 126).

 @item m
 Memory operand.  If used together with @samp{<} or @samp{>}, the
 operand can have postincrement which requires printing with @samp{%In}
 and @samp{%in} on TILE-Gx.  For example:

 @smallexample
 asm ("st_add %I0,%1,%i0" : "=m<>" (*mem) : "r" (val));
 @end smallexample

 @item M
 A bit mask suitable for the BFINS instruction.

 @item N
 Integer constant that is a byte tiled out eight times.

 @item O
 The integer zero constant.

 @item P
 Integer constant that is a sign-extended byte tiled out as four shorts.

 @item Q
 Integer constant that fits in one signed byte when incremented
 (@minus{}129 @dots{} 126), but excluding -1.

 @item S
 Integer constant that has all 1 bits consecutive and starting at bit 0.

 @item T
 A 16-bit fragment of a got, tls, or pc-relative reference.

 @item U
 Memory operand except postincrement.  This is roughly the same as
 @samp{m} when not used together with @samp{<} or @samp{>}.

 @item W
 An 8-element vector constant with identical elements.

 @item Y
 A 4-element vector constant with identical elements.

 @item Z0
 The integer constant 0xffffffff.

 @item Z1
 The integer constant 0xffffffff00000000.

 @end table

 @item TILEPro---@file{config/tilepro/constraints.md}
 @table @code
 @item R00
 @itemx R01
 @itemx R02
 @itemx R03
 @itemx R04
 @itemx R05
 @itemx R06
 @itemx R07
 @itemx R08
 @itemx R09
 @itemx R10
 Each of these represents a register constraint for an individual
 register, from r0 to r10.

 @item I
 Signed 8-bit integer constant.

 @item J
 Signed 16-bit integer constant.

 @item K
 Nonzero integer constant with low 16 bits zero.

 @item L
 Integer constant that fits in one signed byte when incremented by one
 (@minus{}129 @dots{} 126).

 @item m
 Memory operand.  If used together with @samp{<} or @samp{>}, the
 operand can have postincrement which requires printing with @samp{%In}
 and @samp{%in} on TILEPro.  For example:

 @smallexample
 asm ("swadd %I0,%1,%i0" : "=m<>" (mem) : "r" (val));
 @end smallexample

 @item M
 A bit mask suitable for the MM instruction.

 @item N
 Integer constant that is a byte tiled out four times.

 @item O
 The integer zero constant.

 @item P
 Integer constant that is a sign-extended byte tiled out as two shorts.

 @item Q
 Integer constant that fits in one signed byte when incremented
 (@minus{}129 @dots{} 126), but excluding -1.

 @item T
 A symbolic operand, or a 16-bit fragment of a got, tls, or pc-relative
 reference.

 @item U
 Memory operand except postincrement.  This is roughly the same as
 @samp{m} when not used together with @samp{<} or @samp{>}.

 @item W
 A 4-element vector constant with identical elements.

 @item Y
 A 2-element vector constant with identical elements.

 @end table

 @item Visium---@file{config/visium/constraints.md}
 @table @code
 @item b
 EAM register @code{mdb}

 @item c
 EAM register @code{mdc}

 @item f
 Floating point register

 @ifset INTERNALS
 @item k
 Register for sibcall optimization
 @end ifset

 @item l
 General register, but not @code{r29}, @code{r30} and @code{r31}

 @item t
 Register @code{r1}

 @item u
 Register @code{r2}

 @item v
 Register @code{r3}

 @item G
 Floating-point constant 0.0

 @item J
 Integer constant in the range 0 .. 65535 (16-bit immediate)

 @item K
 Integer constant in the range 1 .. 31 (5-bit immediate)

 @item L
 Integer constant in the range @minus{}65535 .. @minus{}1 (16-bit negative immediate)

 @item M
 Integer constant @minus{}1

 @item O
 Integer constant 0

 @item P
 Integer constant 32
 @end table

 @item x86 family---@file{config/i386/constraints.md}
 @table @code
 @item R
 Legacy register---the eight integer registers available on all
 i386 processors (@code{a}, @code{b}, @code{c}, @code{d},
 @code{si}, @code{di}, @code{bp}, @code{sp}).

 @item q
 Any register accessible as @code{@var{r}l}.  In 32-bit mode, @code{a},
 @code{b}, @code{c}, and @code{d}; in 64-bit mode, any integer register.

 @item Q
 Any register accessible as @code{@var{r}h}: @code{a}, @code{b},
 @code{c}, and @code{d}.

 @ifset INTERNALS
 @item l
 Any register that can be used as the index in a base+index memory
 access: that is, any general register except the stack pointer.
 @end ifset

 @item a
 The @code{a} register.

 @item b
 The @code{b} register.

 @item c
 The @code{c} register.

 @item d
 The @code{d} register.

 @item S
 The @code{si} register.

 @item D
 The @code{di} register.

 @item A
 The @code{a} and @code{d} registers.  This class is used for instructions
 that return double word results in the @code{ax:dx} register pair.  Single
 word values will be allocated either in @code{ax} or @code{dx}.
 For example on i386 the following implements @code{rdtsc}:

 @smallexample
 unsigned long long rdtsc (void)
 @{
   unsigned long long tick;
   __asm__ __volatile__("rdtsc":"=A"(tick));
   return tick;
 @}
 @end smallexample

 This is not correct on x86-64 as it would allocate tick in either @code{ax}
 or @code{dx}.  You have to use the following variant instead:

 @smallexample
 unsigned long long rdtsc (void)
 @{
   unsigned int tickl, tickh;
   __asm__ __volatile__("rdtsc":"=a"(tickl),"=d"(tickh));
   return ((unsigned long long)tickh << 32)|tickl;
 @}
 @end smallexample

 @item U
 The call-clobbered integer registers.

 @item f
 Any 80387 floating-point (stack) register.

 @item t
 Top of 80387 floating-point stack (@code{%st(0)}).

 @item u
 Second from top of 80387 floating-point stack (@code{%st(1)}).

 @ifset INTERNALS
 @item Yk
 Any mask register that can be used as a predicate, i.e.@: @code{k1-k7}.

 @item k
 Any mask register.
 @end ifset

 @item y
 Any MMX register.

 @item x
 Any SSE register.

 @item v
 Any EVEX encodable SSE register (@code{%xmm0-%xmm31}).

 @ifset INTERNALS
 @item w
 Any bound register.
 @end ifset

 @item Yz
 First SSE register (@code{%xmm0}).

 @ifset INTERNALS
 @item Yi
 Any SSE register, when SSE2 and inter-unit moves are enabled.

 @item Yj
 Any SSE register, when SSE2 and inter-unit moves from vector registers are enabled.

 @item Ym
 Any MMX register, when inter-unit moves are enabled.

 @item Yn
 Any MMX register, when inter-unit moves from vector registers are enabled.

 @item Yp
 Any integer register when @code{TARGET_PARTIAL_REG_STALL} is disabled.

 @item Ya
 Any integer register when zero extensions with @code{AND} are disabled.

 @item Yb
 Any register that can be used as the GOT base when calling@*
 @code{___tls_get_addr}: that is, any general register except @code{a}
 and @code{sp} registers, for @option{-fno-plt} if linker supports it.
 Otherwise, @code{b} register.

 @item Yf
 Any x87 register when 80387 floating-point arithmetic is enabled.

 @item Yr
 Lower SSE register when avoiding REX prefix and all SSE registers otherwise.

 @item Yv
 For AVX512VL, any EVEX-encodable SSE register (@code{%xmm0-%xmm31}),
 otherwise any SSE register.

 @item Yh
 Any EVEX-encodable SSE register, that has number factor of four.

 @item Bf
 Flags register operand.

 @item Bg
 GOT memory operand.

 @item Bm
 Vector memory operand.

 @item Bc
 Constant memory operand.

 @item Bn
 Memory operand without REX prefix.

 @item Bs
 Sibcall memory operand.

 @item Bw
 Call memory operand.

 @item Bz
 Constant call address operand.

 @item BC
 SSE constant -1 operand.
 @end ifset

 @item I
 Integer constant in the range 0 @dots{} 31, for 32-bit shifts.

 @item J
 Integer constant in the range 0 @dots{} 63, for 64-bit shifts.

 @item K
 Signed 8-bit integer constant.

 @item L
 @code{0xFF} or @code{0xFFFF}, for andsi as a zero-extending move.

 @item M
 0, 1, 2, or 3 (shifts for the @code{lea} instruction).

 @item N
 Unsigned 8-bit integer constant (for @code{in} and @code{out}
 instructions).

 @ifset INTERNALS
 @item O
 Integer constant in the range 0 @dots{} 127, for 128-bit shifts.
 @end ifset

 @item G
 Standard 80387 floating point constant.

 @item C
 SSE constant zero operand.

 @item e
 32-bit signed integer constant, or a symbolic reference known
 to fit that range (for immediate operands in sign-extending x86-64
 instructions).

 @item We
 32-bit signed integer constant, or a symbolic reference known
 to fit that range (for sign-extending conversion operations that
 require non-@code{VOIDmode} immediate operands).

 @item Wz
 32-bit unsigned integer constant, or a symbolic reference known
 to fit that range (for zero-extending conversion operations that
 require non-@code{VOIDmode} immediate operands).

 @item Wd
 128-bit integer constant where both the high and low 64-bit word
 satisfy the @code{e} constraint.

 @item Z
 32-bit unsigned integer constant, or a symbolic reference known
 to fit that range (for immediate operands in zero-extending x86-64
 instructions).

 @item Tv
 VSIB address operand.

 @item Ts
 Address operand without segment register.

 @end table

 @item Xstormy16---@file{config/stormy16/stormy16.h}
 @table @code
 @item a
 Register r0.

 @item b
 Register r1.

 @item c
 Register r2.

 @item d
 Register r8.

 @item e
 Registers r0 through r7.

 @item t
 Registers r0 and r1.

 @item y
 The carry register.

 @item z
 Registers r8 and r9.

 @item I
 A constant between 0 and 3 inclusive.

 @item J
 A constant that has exactly one bit set.

 @item K
 A constant that has exactly one bit clear.

 @item L
 A constant between 0 and 255 inclusive.

 @item M
 A constant between @minus{}255 and 0 inclusive.

 @item N
 A constant between @minus{}3 and 0 inclusive.

 @item O
 A constant between 1 and 4 inclusive.

 @item P
 A constant between @minus{}4 and @minus{}1 inclusive.

 @item Q
 A memory reference that is a stack push.

 @item R
 A memory reference that is a stack pop.

 @item S
 A memory reference that refers to a constant address of known value.

 @item T
 The register indicated by Rx (not implemented yet).

 @item U
 A constant that is not between 2 and 15 inclusive.

 @item Z
 The constant 0.

 @end table

 @item Xtensa---@file{config/xtensa/constraints.md}
 @table @code
 @item a
 General-purpose 32-bit register

 @item b
 One-bit boolean register

 @item A
 MAC16 40-bit accumulator register

 @item I
 Signed 12-bit integer constant, for use in MOVI instructions

 @item J
 Signed 8-bit integer constant, for use in ADDI instructions

 @item K
 Integer constant valid for BccI instructions

 @item L
 Unsigned constant valid for BccUI instructions

 @end table

 @end table

 @ifset INTERNALS
 @node Disable Insn Alternatives
 @subsection Disable insn alternatives using the @code{enabled} attribute
 @cindex enabled

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

 @table @code
 @item enabled
 Says whether an alternative is available on the current subtarget.

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

 @item preferred_for_speed
 Says whether an enabled alternative should be used in code that is
 optimized for speed.
 @end table

 All these attributes should use @code{(const_int 1)} to allow an alternative
 or @code{(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 @code{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 @code{-march=} command-line
 option).

 In contrast, the @code{preferred_for_size} and @code{preferred_for_speed}
 attributes are strong optimization hints rather than correctness properties.
 @code{preferred_for_size} tells GCC which alternatives to consider when
 adding or modifying an instruction that GCC wants to optimize for size.
 @code{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 @code{define_insn}s can in principle specify the @code{enabled}
 attribute directly, it is often clearer to have subsiduary attributes
 for each architectural feature of interest.  The @code{define_insn}s
 can then use these subsiduary attributes to say which alternatives
 require which features.  The example below does this for @code{cpu_facility}.

 E.g. the following two patterns could easily be merged using the @code{enabled}
 attribute:

 @smallexample

 (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")

 @end smallexample

 to:

 @smallexample

 (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")])

 @end smallexample

 with the @code{enabled} attribute defined like this:

 @smallexample

 (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)))

 @end smallexample

 @end ifset

 @ifset INTERNALS
 @node Define Constraints
 @subsection Defining Machine-Specific Constraints
 @cindex defining constraints
 @cindex constraints, defining

 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 @code{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 @code{x} is defined as a constraint name,
 @code{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.
 @xref{Register Classes}.  There is thus not much flexibility in their
 definitions.

 @deffn {MD Expression} define_register_constraint name regclass docstring
 All three arguments are string constants.
 @var{name} is the name of the constraint, as it will appear in
 @code{match_operand} expressions.  If @var{name} is a multi-letter
 constraint its length shall be the same for all constraints starting
 with the same letter.  @var{regclass} can be either the
 name of the corresponding register class (@pxref{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 @code{NO_REGS} when the register class
 is not available on a given subarchitecture.

 @var{docstring} is a sentence documenting the meaning of the
 constraint.  Docstrings are explained further below.
 @end deffn

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

 @deffn {MD Expression} define_constraint name docstring exp
 The @var{name} and @var{docstring} arguments are the same as for
 @code{define_register_constraint}, but note that the docstring comes
 immediately after the name for these expressions.  @var{exp} is an RTL
 expression, obeying the same rules as the RTL expressions in predicate
 definitions.  @xref{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.

 @code{match_test} C expressions have access to the
 following variables:

 @table @var
 @item op
 The RTL object defining the operand.
 @item mode
 The machine mode of @var{op}.
 @item ival
 @samp{INTVAL (@var{op})}, if @var{op} is a @code{const_int}.
 @item hval
 @samp{CONST_DOUBLE_HIGH (@var{op})}, if @var{op} is an integer
 @code{const_double}.
 @item lval
 @samp{CONST_DOUBLE_LOW (@var{op})}, if @var{op} is an integer
 @code{const_double}.
 @item rval
 @samp{CONST_DOUBLE_REAL_VALUE (@var{op})}, if @var{op} is a floating-point
 @code{const_double}.
 @end table

 The @var{*val} variables should only be used once another piece of the
 expression has verified that @var{op} is the appropriate kind of RTL
 object.
 @end deffn

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

 @deffn {MD Expression} define_memory_constraint name docstring exp
 Use this expression for constraints that match a subset of all memory
 operands: that is, @code{reload} can make them match by converting the
 operand to the form @samp{@w{(mem (reg @var{X}))}}, where @var{X} is a
 base register (from the register class specified by
 @code{BASE_REG_CLASS}, @pxref{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
 @code{define_memory_constraint}, a @samp{Q} constraint can handle any
 memory operand, because @code{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
 @code{define_constraint}.
 @end deffn

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

 For example, @code{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
 @code{define_constraint}.
 @end deffn

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

 Constraints defined with @code{define_address_constraint} can only be
 used with the @code{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
 @code{define_constraint}.
 @end deffn

 For historical reasons, names beginning with the letters @samp{G H}
 are reserved for constraints that match only @code{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 @code{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 @code{genpreds} can tell you did
 it correctly:

 @smallexample
 @group
 (define_constraint "[@var{GHIJKLMNOP}]@dots{}"
   "@var{doc}@dots{}"
   (and (match_code "const_int")  ; @r{@code{const_double} for G/H}
        @var{condition}@dots{}))            ; @r{usually a @code{match_test}}
 @end group
 @end smallexample
 @c the semicolons line up in the formatted manual

 It is fine to use names beginning with other letters for constraints
 that match @code{const_double}s or @code{const_int}s.

 Each docstring in a constraint definition should be one or more complete
 sentences, marked up in Texinfo format.  @emph{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 @code{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 @code{asm} statements.

 @node C Constraint Interface
 @subsection Testing constraints from C
 @cindex testing constraints
 @cindex constraints, testing

 It is occasionally useful to test a constraint from C code rather than
 implicitly via the constraint string in a @code{match_operand}.  The
 generated file @file{tm_p.h} declares a few interfaces for working
 with constraints.  At present these are defined for all constraints
 except @code{g} (which is equivalent to @code{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:

 @c the @c's prevent double blank lines in the printed manual.
 @example
 @multitable {Original} {Mangled}
 @item @strong{Original} @tab @strong{Mangled}  @c
 @item @code{x}     @tab @code{x}       @c
 @item @code{P42x}  @tab @code{P42x}    @c
 @item @code{P4_x}  @tab @code{P4__x}   @c
 @item @code{P4>x}  @tab @code{P4_gx}   @c
 @item @code{P4>>}  @tab @code{P4_g_g}  @c
 @item @code{P4_g>} @tab @code{P4__g_g} @c
 @end multitable
 @end example

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

 @deftp Enum constraint_num
 For each constraint except @code{g}, there is a corresponding
 enumeration constant: @samp{CONSTRAINT_} plus the mangled name of the
 constraint.  Functions that take an @code{enum constraint_num} as an
 argument expect one of these constants.
 @end deftp

 @deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
 For each non-register constraint @var{m} except @code{g}, there is
 one of these functions; it returns @code{true} if @var{exp} satisfies the
 constraint.  These functions are only visible if @file{rtl.h} was included
 before @file{tm_p.h}.
 @end deftypefun

 @deftypefun bool constraint_satisfied_p (rtx @var{exp}, enum constraint_num @var{c})
 Like the @code{satisfies_constraint_@var{m}} functions, but the
 constraint to test is given as an argument, @var{c}.  If @var{c}
 specifies a register constraint, this function will always return
 @code{false}.
 @end deftypefun

 @deftypefun {enum reg_class} reg_class_for_constraint (enum constraint_num @var{c})
 Returns the register class associated with @var{c}.  If @var{c} is not
 a register constraint, or those registers are not available for the
 currently selected subtarget, returns @code{NO_REGS}.
 @end deftypefun

 Here is an example use of @code{satisfies_constraint_@var{m}}.  In
 peephole optimizations (@pxref{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 @emph{not} satisfy the
 @samp{K} constraint.  (This is a simplified version of a peephole
 definition from the i386 machine description.)

 @smallexample
 (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)))]

   "")
 @end smallexample

 @node Standard Names
 @section Standard Pattern Names For Generation
 @cindex standard pattern names
 @cindex pattern names
 @cindex names, pattern

 Here is a table of the instruction names that are meaningful in the RTL
 generation pass of the compiler.  Giving one of these names to an
 instruction pattern tells the RTL generation pass that it can use the
 pattern to accomplish a certain task.

 @table @asis
 @cindex @code{mov@var{m}} instruction pattern
 @item @samp{mov@var{m}}
 Here @var{m} stands for a two-letter machine mode name, in lowercase.
 This instruction pattern moves data with that machine mode from operand
 1 to operand 0.  For example, @samp{movsi} moves full-word data.

 If operand 0 is a @code{subreg} with mode @var{m} of a register whose
 own mode is wider than @var{m}, the effect of this instruction is
 to store the specified value in the part of the register that corresponds
 to mode @var{m}.  Bits outside of @var{m}, but which are within the
 same target word as the @code{subreg} are undefined.  Bits which are
 outside the target word are left unchanged.

 This class of patterns is special in several ways.  First of all, each
 of these names up to and including full word size @emph{must} be defined,
 because there is no other way to copy a datum from one place to another.
 If there are patterns accepting operands in larger modes,
 @samp{mov@var{m}} must be defined for integer modes of those sizes.

 Second, these patterns are not used solely in the RTL generation pass.
 Even the reload pass can generate move insns to copy values from stack
 slots into temporary registers.  When it does so, one of the operands is
 a hard register and the other is an operand that can need to be reloaded
 into a register.

 @findex force_reg
 Therefore, when given such a pair of operands, the pattern must generate
 RTL which needs no reloading and needs no temporary registers---no
 registers other than the operands.  For example, if you support the
 pattern with a @code{define_expand}, then in such a case the
 @code{define_expand} mustn't call @code{force_reg} or any other such
 function which might generate new pseudo registers.

 This requirement exists even for subword modes on a RISC machine where
 fetching those modes from memory normally requires several insns and
 some temporary registers.

 @findex change_address
 During reload a memory reference with an invalid address may be passed
 as an operand.  Such an address will be replaced with a valid address
 later in the reload pass.  In this case, nothing may be done with the
 address except to use it as it stands.  If it is copied, it will not be
 replaced with a valid address.  No attempt should be made to make such
 an address into a valid address and no routine (such as
 @code{change_address}) that will do so may be called.  Note that
 @code{general_operand} will fail when applied to such an address.

 @findex reload_in_progress
 The global variable @code{reload_in_progress} (which must be explicitly
 declared if required) can be used to determine whether such special
 handling is required.

 The variety of operands that have reloads depends on the rest of the
 machine description, but typically on a RISC machine these can only be
 pseudo registers that did not get hard registers, while on other
 machines explicit memory references will get optional reloads.

 If a scratch register is required to move an object to or from memory,
 it can be allocated using @code{gen_reg_rtx} prior to life analysis.

 If there are cases which need scratch registers during or after reload,
 you must provide an appropriate secondary_reload target hook.

 @findex can_create_pseudo_p
 The macro @code{can_create_pseudo_p} can be used to determine if it
 is unsafe to create new pseudo registers.  If this variable is nonzero, then
 it is unsafe to call @code{gen_reg_rtx} to allocate a new pseudo.

 The constraints on a @samp{mov@var{m}} must permit moving any hard
 register to any other hard register provided that
 @code{TARGET_HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
 @code{TARGET_REGISTER_MOVE_COST} applied to their classes returns a value
 of 2.

 It is obligatory to support floating point @samp{mov@var{m}}
 instructions into and out of any registers that can hold fixed point
 values, because unions and structures (which have modes @code{SImode} or
 @code{DImode}) can be in those registers and they may have floating
 point members.

 There may also be a need to support fixed point @samp{mov@var{m}}
 instructions in and out of floating point registers.  Unfortunately, I
 have forgotten why this was so, and I don't know whether it is still
 true.  If @code{TARGET_HARD_REGNO_MODE_OK} rejects fixed point values in
 floating point registers, then the constraints of the fixed point
 @samp{mov@var{m}} instructions must be designed to avoid ever trying to
 reload into a floating point register.

 @cindex @code{reload_in} instruction pattern
 @cindex @code{reload_out} instruction pattern
 @item @samp{reload_in@var{m}}
 @itemx @samp{reload_out@var{m}}
 These named patterns have been obsoleted by the target hook
 @code{secondary_reload}.

 Like @samp{mov@var{m}}, but used when a scratch register is required to
 move between operand 0 and operand 1.  Operand 2 describes the scratch
 register.  See the discussion of the @code{SECONDARY_RELOAD_CLASS}
 macro in @pxref{Register Classes}.

 There are special restrictions on the form of the @code{match_operand}s
 used in these patterns.  First, only the predicate for the reload
 operand is examined, i.e., @code{reload_in} examines operand 1, but not
 the predicates for operand 0 or 2.  Second, there may be only one
 alternative in the constraints.  Third, only a single register class
 letter may be used for the constraint; subsequent constraint letters
 are ignored.  As a special exception, an empty constraint string
 matches the @code{ALL_REGS} register class.  This may relieve ports
 of the burden of defining an @code{ALL_REGS} constraint letter just
 for these patterns.

 @cindex @code{movstrict@var{m}} instruction pattern
 @item @samp{movstrict@var{m}}
 Like @samp{mov@var{m}} except that if operand 0 is a @code{subreg}
 with mode @var{m} of a register whose natural mode is wider,
 the @samp{movstrict@var{m}} instruction is guaranteed not to alter
 any of the register except the part which belongs to mode @var{m}.

 @cindex @code{movmisalign@var{m}} instruction pattern
 @item @samp{movmisalign@var{m}}
 This variant of a move pattern is designed to load or store a value
 from a memory address that is not naturally aligned for its mode.
 For a store, the memory will be in operand 0; for a load, the memory
 will be in operand 1.  The other operand is guaranteed not to be a
 memory, so that it's easy to tell whether this is a load or store.

 This pattern is used by the autovectorizer, and when expanding a
 @code{MISALIGNED_INDIRECT_REF} expression.

 @cindex @code{load_multiple} instruction pattern
 @item @samp{load_multiple}
 Load several consecutive memory locations into consecutive registers.
 Operand 0 is the first of the consecutive registers, operand 1
 is the first memory location, and operand 2 is a constant: the
 number of consecutive registers.

 Define this only if the target machine really has such an instruction;
 do not define this if the most efficient way of loading consecutive
 registers from memory is to do them one at a time.

 On some machines, there are restrictions as to which consecutive
 registers can be stored into memory, such as particular starting or
 ending register numbers or only a range of valid counts.  For those
 machines, use a @code{define_expand} (@pxref{Expander Definitions})
 and make the pattern fail if the restrictions are not met.

 Write the generated insn as a @code{parallel} with elements being a
 @code{set} of one register from the appropriate memory location (you may
 also need @code{use} or @code{clobber} elements).  Use a
 @code{match_parallel} (@pxref{RTL Template}) to recognize the insn.  See
 @file{rs6000.md} for examples of the use of this insn pattern.

 @cindex @samp{store_multiple} instruction pattern
 @item @samp{store_multiple}
 Similar to @samp{load_multiple}, but store several consecutive registers
 into consecutive memory locations.  Operand 0 is the first of the
 consecutive memory locations, operand 1 is the first register, and
 operand 2 is a constant: the number of consecutive registers.

 @cindex @code{vec_load_lanes@var{m}@var{n}} instruction pattern
 @item @samp{vec_load_lanes@var{m}@var{n}}
 Perform an interleaved load of several vectors from memory operand 1
 into register operand 0.  Both operands have mode @var{m}.  The register
 operand is viewed as holding consecutive vectors of mode @var{n},
 while the memory operand is a flat array that contains the same number
 of elements.  The operation is equivalent to:

 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
   for (i = 0; i < c; i++)
     operand0[i][j] = operand1[j * c + i];
 @end smallexample

 For example, @samp{vec_load_lanestiv4hi} loads 8 16-bit values
 from memory into a register of mode @samp{TI}@.  The register
 contains two consecutive vectors of mode @samp{V4HI}@.

 This pattern can only be used if:
 @smallexample
 TARGET_ARRAY_MODE_SUPPORTED_P (@var{n}, @var{c})
 @end smallexample
 is true.  GCC assumes that, if a target supports this kind of
 instruction for some mode @var{n}, it also supports unaligned
 loads for vectors of mode @var{n}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{vec_mask_load_lanes@var{m}@var{n}} instruction pattern
 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
 mask operand (operand 2) that specifies which elements of the destination
 vectors should be loaded.  Other elements of the destination
 vectors are set to zero.  The operation is equivalent to:

 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
   if (operand2[j])
     for (i = 0; i < c; i++)
       operand0[i][j] = operand1[j * c + i];
   else
     for (i = 0; i < c; i++)
       operand0[i][j] = 0;
 @end smallexample

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{vec_store_lanes@var{m}@var{n}} instruction pattern
 @item @samp{vec_store_lanes@var{m}@var{n}}
 Equivalent to @samp{vec_load_lanes@var{m}@var{n}}, with the memory
 and register operands reversed.  That is, the instruction is
 equivalent to:

 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
   for (i = 0; i < c; i++)
     operand0[j * c + i] = operand1[i][j];
 @end smallexample

 for a memory operand 0 and register operand 1.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{vec_mask_store_lanes@var{m}@var{n}} instruction pattern
 @item @samp{vec_mask_store_lanes@var{m}@var{n}}
 Like @samp{vec_store_lanes@var{m}@var{n}}, but takes an additional
 mask operand (operand 2) that specifies which elements of the source
 vectors should be stored.  The operation is equivalent to:

 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
 for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
   if (operand2[j])
     for (i = 0; i < c; i++)
       operand0[j * c + i] = operand1[i][j];
 @end smallexample

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{gather_load@var{m}} instruction pattern
 @item @samp{gather_load@var{m}}
 Load several separate memory locations into a vector of mode @var{m}.
 Operand 1 is a scalar base address and operand 2 is a vector of
 offsets from that base.  Operand 0 is a destination vector with the
 same number of elements as the offset.  For each element index @var{i}:

 @itemize @bullet
 @item
 extend the offset element @var{i} to address width, using zero
 extension if operand 3 is 1 and sign extension if operand 3 is zero;
 @item
 multiply the extended offset by operand 4;
 @item
 add the result to the base; and
 @item
 load the value at that address into element @var{i} of operand 0.
 @end itemize

 The value of operand 3 does not matter if the offsets are already
 address width.

 @cindex @code{mask_gather_load@var{m}} instruction pattern
 @item @samp{mask_gather_load@var{m}}
 Like @samp{gather_load@var{m}}, but takes an extra mask operand as
 operand 5.  Bit @var{i} of the mask is set if element @var{i}
 of the result should be loaded from memory and clear if element @var{i}
 of the result should be set to zero.

 @cindex @code{scatter_store@var{m}} instruction pattern
 @item @samp{scatter_store@var{m}}
 Store a vector of mode @var{m} into several distinct memory locations.
 Operand 0 is a scalar base address and operand 1 is a vector of offsets
 from that base.  Operand 4 is the vector of values that should be stored,
 which has the same number of elements as the offset.  For each element
 index @var{i}:

 @itemize @bullet
 @item
 extend the offset element @var{i} to address width, using zero
 extension if operand 2 is 1 and sign extension if operand 2 is zero;
 @item
 multiply the extended offset by operand 3;
 @item
 add the result to the base; and
 @item
 store element @var{i} of operand 4 to that address.
 @end itemize

 The value of operand 2 does not matter if the offsets are already
 address width.

 @cindex @code{mask_scatter_store@var{m}} instruction pattern
 @item @samp{mask_scatter_store@var{m}}
 Like @samp{scatter_store@var{m}}, but takes an extra mask operand as
 operand 5.  Bit @var{i} of the mask is set if element @var{i}
 of the result should be stored to memory.

 @cindex @code{vec_set@var{m}} instruction pattern
 @item @samp{vec_set@var{m}}
 Set given field in the vector value.  Operand 0 is the vector to modify,
 operand 1 is new value of field and operand 2 specify the field index.

 @cindex @code{vec_extract@var{m}@var{n}} instruction pattern
 @item @samp{vec_extract@var{m}@var{n}}
 Extract given field from the vector value.  Operand 1 is the vector, operand 2
 specify field index and operand 0 place to store value into.  The
 @var{n} mode is the mode of the field or vector of fields that should be
 extracted, should be either element mode of the vector mode @var{m}, or
 a vector mode with the same element mode and smaller number of elements.
 If @var{n} is a vector mode, the index is counted in units of that mode.

 @cindex @code{vec_init@var{m}@var{n}} instruction pattern
 @item @samp{vec_init@var{m}@var{n}}
 Initialize the vector to given values.  Operand 0 is the vector to initialize
 and operand 1 is parallel containing values for individual fields.  The
 @var{n} mode is the mode of the elements, should be either element mode of
 the vector mode @var{m}, or a vector mode with the same element mode and
 smaller number of elements.

 @cindex @code{vec_duplicate@var{m}} instruction pattern
 @item @samp{vec_duplicate@var{m}}
 Initialize vector output operand 0 so that each element has the value given
 by scalar input operand 1.  The vector has mode @var{m} and the scalar has
 the mode appropriate for one element of @var{m}.

 This pattern only handles duplicates of non-constant inputs.  Constant
 vectors go through the @code{mov@var{m}} pattern instead.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{vec_series@var{m}} instruction pattern
 @item @samp{vec_series@var{m}}
 Initialize vector output operand 0 so that element @var{i} is equal to
 operand 1 plus @var{i} times operand 2.  In other words, create a linear
 series whose base value is operand 1 and whose step is operand 2.

 The vector output has mode @var{m} and the scalar inputs have the mode
 appropriate for one element of @var{m}.  This pattern is not used for
 floating-point vectors, in order to avoid having to specify the
 rounding behavior for @var{i} > 1.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{while_ult@var{m}@var{n}} instruction pattern
 @item @code{while_ult@var{m}@var{n}}
 Set operand 0 to a mask that is true while incrementing operand 1
 gives a value that is less than operand 2.  Operand 0 has mode @var{n}
 and operands 1 and 2 are scalar integers of mode @var{m}.
 The operation is equivalent to:

 @smallexample
 operand0[0] = operand1 < operand2;
 for (i = 1; i < GET_MODE_NUNITS (@var{n}); i++)
   operand0[i] = operand0[i - 1] && (operand1 + i < operand2);
 @end smallexample

 @cindex @code{vec_cmp@var{m}@var{n}} instruction pattern
 @item @samp{vec_cmp@var{m}@var{n}}
 Output a vector comparison.  Operand 0 of mode @var{n} is the destination for
 predicate in operand 1 which is a signed vector comparison with operands of
 mode @var{m} in operands 2 and 3.  Predicate is computed by element-wise
 evaluation of the vector comparison with a truth value of all-ones and a false
 value of all-zeros.

 @cindex @code{vec_cmpu@var{m}@var{n}} instruction pattern
 @item @samp{vec_cmpu@var{m}@var{n}}
 Similar to @code{vec_cmp@var{m}@var{n}} but perform unsigned vector comparison.

 @cindex @code{vec_cmpeq@var{m}@var{n}} instruction pattern
 @item @samp{vec_cmpeq@var{m}@var{n}}
 Similar to @code{vec_cmp@var{m}@var{n}} but perform equality or non-equality
 vector comparison only.  If @code{vec_cmp@var{m}@var{n}}
 or @code{vec_cmpu@var{m}@var{n}} instruction pattern is supported,
 it will be preferred over @code{vec_cmpeq@var{m}@var{n}}, so there is
 no need to define this instruction pattern if the others are supported.

 @cindex @code{vcond@var{m}@var{n}} instruction pattern
 @item @samp{vcond@var{m}@var{n}}
 Output a conditional vector move.  Operand 0 is the destination to
 receive a combination of operand 1 and operand 2, which are of mode @var{m},
 dependent on the outcome of the predicate in operand 3 which is a signed
 vector comparison with operands of mode @var{n} in operands 4 and 5.  The
 modes @var{m} and @var{n} should have the same size.  Operand 0
 will be set to the value @var{op1} & @var{msk} | @var{op2} & ~@var{msk}
 where @var{msk} is computed by element-wise evaluation of the vector
 comparison with a truth value of all-ones and a false value of all-zeros.

 @cindex @code{vcondu@var{m}@var{n}} instruction pattern
 @item @samp{vcondu@var{m}@var{n}}
 Similar to @code{vcond@var{m}@var{n}} but performs unsigned vector
 comparison.

 @cindex @code{vcondeq@var{m}@var{n}} instruction pattern
 @item @samp{vcondeq@var{m}@var{n}}
 Similar to @code{vcond@var{m}@var{n}} but performs equality or
 non-equality vector comparison only.  If @code{vcond@var{m}@var{n}}
 or @code{vcondu@var{m}@var{n}} instruction pattern is supported,
 it will be preferred over @code{vcondeq@var{m}@var{n}}, so there is
 no need to define this instruction pattern if the others are supported.

 @cindex @code{vcond_mask_@var{m}@var{n}} instruction pattern
 @item @samp{vcond_mask_@var{m}@var{n}}
 Similar to @code{vcond@var{m}@var{n}} but operand 3 holds a pre-computed
 result of vector comparison.

 @cindex @code{maskload@var{m}@var{n}} instruction pattern
 @item @samp{maskload@var{m}@var{n}}
 Perform a masked load of vector from memory operand 1 of mode @var{m}
 into register operand 0.  Mask is provided in register operand 2 of
 mode @var{n}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{maskstore@var{m}@var{n}} instruction pattern
 @item @samp{maskstore@var{m}@var{n}}
 Perform a masked store of vector from register operand 1 of mode @var{m}
 into memory operand 0.  Mask is provided in register operand 2 of
 mode @var{n}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{vec_perm@var{m}} instruction pattern
 @item @samp{vec_perm@var{m}}
 Output a (variable) vector permutation.  Operand 0 is the destination
 to receive elements from operand 1 and operand 2, which are of mode
 @var{m}.  Operand 3 is the @dfn{selector}.  It is an integral mode
 vector of the same width and number of elements as mode @var{m}.

 The input elements are numbered from 0 in operand 1 through
 @math{2*@var{N}-1} in operand 2.  The elements of the selector must
 be computed modulo @math{2*@var{N}}.  Note that if
 @code{rtx_equal_p(operand1, operand2)}, this can be implemented
 with just operand 1 and selector elements modulo @var{N}.

 In order to make things easy for a number of targets, if there is no
 @samp{vec_perm} pattern for mode @var{m}, but there is for mode @var{q}
 where @var{q} is a vector of @code{QImode} of the same width as @var{m},
 the middle-end will lower the mode @var{m} @code{VEC_PERM_EXPR} to
 mode @var{q}.

 See also @code{TARGET_VECTORIZER_VEC_PERM_CONST}, which performs
 the analogous operation for constant selectors.

 @cindex @code{push@var{m}1} instruction pattern
 @item @samp{push@var{m}1}
 Output a push instruction.  Operand 0 is value to push.  Used only when
 @code{PUSH_ROUNDING} is defined.  For historical reason, this pattern may be
 missing and in such case an @code{mov} expander is used instead, with a
 @code{MEM} expression forming the push operation.  The @code{mov} expander
 method is deprecated.

 @cindex @code{add@var{m}3} instruction pattern
 @item @samp{add@var{m}3}
 Add operand 2 and operand 1, storing the result in operand 0.  All operands
 must have mode @var{m}.  This can be used even on two-address machines, by
 means of constraints requiring operands 1 and 0 to be the same location.

 @cindex @code{ssadd@var{m}3} instruction pattern
 @cindex @code{usadd@var{m}3} instruction pattern
 @cindex @code{sub@var{m}3} instruction pattern
 @cindex @code{sssub@var{m}3} instruction pattern
 @cindex @code{ussub@var{m}3} instruction pattern
 @cindex @code{mul@var{m}3} instruction pattern
 @cindex @code{ssmul@var{m}3} instruction pattern
 @cindex @code{usmul@var{m}3} instruction pattern
 @cindex @code{div@var{m}3} instruction pattern
 @cindex @code{ssdiv@var{m}3} instruction pattern
 @cindex @code{udiv@var{m}3} instruction pattern
 @cindex @code{usdiv@var{m}3} instruction pattern
 @cindex @code{mod@var{m}3} instruction pattern
 @cindex @code{umod@var{m}3} instruction pattern
 @cindex @code{umin@var{m}3} instruction pattern
 @cindex @code{umax@var{m}3} instruction pattern
 @cindex @code{and@var{m}3} instruction pattern
 @cindex @code{ior@var{m}3} instruction pattern
 @cindex @code{xor@var{m}3} instruction pattern
 @item @samp{ssadd@var{m}3}, @samp{usadd@var{m}3}
 @itemx @samp{sub@var{m}3}, @samp{sssub@var{m}3}, @samp{ussub@var{m}3}
 @itemx @samp{mul@var{m}3}, @samp{ssmul@var{m}3}, @samp{usmul@var{m}3}
 @itemx @samp{div@var{m}3}, @samp{ssdiv@var{m}3}
 @itemx @samp{udiv@var{m}3}, @samp{usdiv@var{m}3}
 @itemx @samp{mod@var{m}3}, @samp{umod@var{m}3}
 @itemx @samp{umin@var{m}3}, @samp{umax@var{m}3}
 @itemx @samp{and@var{m}3}, @samp{ior@var{m}3}, @samp{xor@var{m}3}
 Similar, for other arithmetic operations.

 @cindex @code{addv@var{m}4} instruction pattern
 @item @samp{addv@var{m}4}
 Like @code{add@var{m}3} but takes a @code{code_label} as operand 3 and
 emits code to jump to it if signed overflow occurs during the addition.
 This pattern is used to implement the built-in functions performing
 signed integer addition with overflow checking.

 @cindex @code{subv@var{m}4} instruction pattern
 @cindex @code{mulv@var{m}4} instruction pattern
 @item @samp{subv@var{m}4}, @samp{mulv@var{m}4}
 Similar, for other signed arithmetic operations.

 @cindex @code{uaddv@var{m}4} instruction pattern
 @item @samp{uaddv@var{m}4}
 Like @code{addv@var{m}4} but for unsigned addition.  That is to
 say, the operation is the same as signed addition but the jump
 is taken only on unsigned overflow.

 @cindex @code{usubv@var{m}4} instruction pattern
 @cindex @code{umulv@var{m}4} instruction pattern
 @item @samp{usubv@var{m}4}, @samp{umulv@var{m}4}
 Similar, for other unsigned arithmetic operations.

 @cindex @code{addptr@var{m}3} instruction pattern
 @item @samp{addptr@var{m}3}
 Like @code{add@var{m}3} but is guaranteed to only be used for address
 calculations.  The expanded code is not allowed to clobber the
 condition code.  It only needs to be defined if @code{add@var{m}3}
 sets the condition code.  If adds used for address calculations and
 normal adds are not compatible it is required to expand a distinct
 pattern (e.g.@: using an unspec).  The pattern is used by LRA to emit
 address calculations.  @code{add@var{m}3} is used if
 @code{addptr@var{m}3} is not defined.

 @cindex @code{fma@var{m}4} instruction pattern
 @item @samp{fma@var{m}4}
 Multiply operand 2 and operand 1, then add operand 3, storing the
 result in operand 0 without doing an intermediate rounding step.  All
 operands must have mode @var{m}.  This pattern is used to implement
 the @code{fma}, @code{fmaf}, and @code{fmal} builtin functions from
 the ISO C99 standard.

 @cindex @code{fms@var{m}4} instruction pattern
 @item @samp{fms@var{m}4}
 Like @code{fma@var{m}4}, except operand 3 subtracted from the
 product instead of added to the product.  This is represented
 in the rtl as

 @smallexample
 (fma:@var{m} @var{op1} @var{op2} (neg:@var{m} @var{op3}))
 @end smallexample

 @cindex @code{fnma@var{m}4} instruction pattern
 @item @samp{fnma@var{m}4}
 Like @code{fma@var{m}4} except that the intermediate product
 is negated before being added to operand 3.  This is represented
 in the rtl as

 @smallexample
 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} @var{op3})
 @end smallexample

 @cindex @code{fnms@var{m}4} instruction pattern
 @item @samp{fnms@var{m}4}
 Like @code{fms@var{m}4} except that the intermediate product
 is negated before subtracting operand 3.  This is represented
 in the rtl as

 @smallexample
 (fma:@var{m} (neg:@var{m} @var{op1}) @var{op2} (neg:@var{m} @var{op3}))
 @end smallexample

 @cindex @code{min@var{m}3} instruction pattern
 @cindex @code{max@var{m}3} instruction pattern
 @item @samp{smin@var{m}3}, @samp{smax@var{m}3}
 Signed minimum and maximum operations.  When used with floating point,
 if both operands are zeros, or if either operand is @code{NaN}, then
 it is unspecified which of the two operands is returned as the result.

 @cindex @code{fmin@var{m}3} instruction pattern
 @cindex @code{fmax@var{m}3} instruction pattern
 @item @samp{fmin@var{m}3}, @samp{fmax@var{m}3}
 IEEE-conformant minimum and maximum operations.  If one operand is a quiet
 @code{NaN}, then the other operand is returned.  If both operands are quiet
 @code{NaN}, then a quiet @code{NaN} is returned.  In the case when gcc supports
 signaling @code{NaN} (-fsignaling-nans) an invalid floating point exception is
 raised and a quiet @code{NaN} is returned.

 All operands have mode @var{m}, which is a scalar or vector
 floating-point mode.  These patterns are not allowed to @code{FAIL}.

 @cindex @code{reduc_smin_scal_@var{m}} instruction pattern
 @cindex @code{reduc_smax_scal_@var{m}} instruction pattern
 @item @samp{reduc_smin_scal_@var{m}}, @samp{reduc_smax_scal_@var{m}}
 Find the signed minimum/maximum of the elements of a vector. The vector is
 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
 the elements of the input vector.

 @cindex @code{reduc_umin_scal_@var{m}} instruction pattern
 @cindex @code{reduc_umax_scal_@var{m}} instruction pattern
 @item @samp{reduc_umin_scal_@var{m}}, @samp{reduc_umax_scal_@var{m}}
 Find the unsigned minimum/maximum of the elements of a vector. The vector is
 operand 1, and operand 0 is the scalar result, with mode equal to the mode of
 the elements of the input vector.

 @cindex @code{reduc_plus_scal_@var{m}} instruction pattern
 @item @samp{reduc_plus_scal_@var{m}}
 Compute the sum of the elements of a vector. The vector is operand 1, and
 operand 0 is the scalar result, with mode equal to the mode of the elements of
 the input vector.

 @cindex @code{reduc_and_scal_@var{m}} instruction pattern
 @item @samp{reduc_and_scal_@var{m}}
 @cindex @code{reduc_ior_scal_@var{m}} instruction pattern
 @itemx @samp{reduc_ior_scal_@var{m}}
 @cindex @code{reduc_xor_scal_@var{m}} instruction pattern
 @itemx @samp{reduc_xor_scal_@var{m}}
 Compute the bitwise @code{AND}/@code{IOR}/@code{XOR} reduction of the elements
 of a vector of mode @var{m}.  Operand 1 is the vector input and operand 0
 is the scalar result.  The mode of the scalar result is the same as one
 element of @var{m}.

 @cindex @code{extract_last_@var{m}} instruction pattern
 @item @code{extract_last_@var{m}}
 Find the last set bit in mask operand 1 and extract the associated element
 of vector operand 2.  Store the result in scalar operand 0.  Operand 2
 has vector mode @var{m} while operand 0 has the mode appropriate for one
 element of @var{m}.  Operand 1 has the usual mask mode for vectors of mode
 @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.

 @cindex @code{fold_extract_last_@var{m}} instruction pattern
 @item @code{fold_extract_last_@var{m}}
 If any bits of mask operand 2 are set, find the last set bit, extract
 the associated element from vector operand 3, and store the result
 in operand 0.  Store operand 1 in operand 0 otherwise.  Operand 3
 has mode @var{m} and operands 0 and 1 have the mode appropriate for
 one element of @var{m}.  Operand 2 has the usual mask mode for vectors
 of mode @var{m}; see @code{TARGET_VECTORIZE_GET_MASK_MODE}.

 @cindex @code{fold_left_plus_@var{m}} instruction pattern
 @item @code{fold_left_plus_@var{m}}
 Take scalar operand 1 and successively add each element from vector
 operand 2.  Store the result in scalar operand 0.  The vector has
 mode @var{m} and the scalars have the mode appropriate for one
 element of @var{m}.  The operation is strictly in-order: there is
 no reassociation.

 @cindex @code{sdot_prod@var{m}} instruction pattern
 @item @samp{sdot_prod@var{m}}
 @cindex @code{udot_prod@var{m}} instruction pattern
 @itemx @samp{udot_prod@var{m}}
 Compute the sum of the products of two signed/unsigned elements.
 Operand 1 and operand 2 are of the same mode. Their product, which is of a
 wider mode, is computed and added to operand 3. Operand 3 is of a mode equal or
 wider than the mode of the product. The result is placed in operand 0, which
 is of the same mode as operand 3.

 @cindex @code{ssad@var{m}} instruction pattern
 @item @samp{ssad@var{m}}
 @cindex @code{usad@var{m}} instruction pattern
 @item @samp{usad@var{m}}
 Compute the sum of absolute differences of two signed/unsigned elements.
 Operand 1 and operand 2 are of the same mode. Their absolute difference, which
 is of a wider mode, is computed and added to operand 3. Operand 3 is of a mode
 equal or wider than the mode of the absolute difference. The result is placed
 in operand 0, which is of the same mode as operand 3.

 @cindex @code{widen_ssum@var{m3}} instruction pattern
 @item @samp{widen_ssum@var{m3}}
 @cindex @code{widen_usum@var{m3}} instruction pattern
 @itemx @samp{widen_usum@var{m3}}
 Operands 0 and 2 are of the same mode, which is wider than the mode of
 operand 1. Add operand 1 to operand 2 and place the widened result in
 operand 0. (This is used express accumulation of elements into an accumulator
 of a wider mode.)

 @cindex @code{vec_shl_insert_@var{m}} instruction pattern
 @item @samp{vec_shl_insert_@var{m}}
 Shift the elements in vector input operand 1 left one element (i.e.@:
 away from element 0) and fill the vacated element 0 with the scalar
 in operand 2.  Store the result in vector output operand 0.  Operands
 0 and 1 have mode @var{m} and operand 2 has the mode appropriate for
 one element of @var{m}.

 @cindex @code{vec_shr_@var{m}} instruction pattern
 @item @samp{vec_shr_@var{m}}
 Whole vector right shift in bits, i.e.@: towards element 0.
 Operand 1 is a vector to be shifted.
 Operand 2 is an integer shift amount in bits.
 Operand 0 is where the resulting shifted vector is stored.
 The output and input vectors should have the same modes.

 @cindex @code{vec_pack_trunc_@var{m}} instruction pattern
 @item @samp{vec_pack_trunc_@var{m}}
 Narrow (demote) and merge the elements of two vectors. Operands 1 and 2
 are vectors of the same mode having N integral or floating point elements
 of size S@.  Operand 0 is the resulting vector in which 2*N elements of
 size N/2 are concatenated after narrowing them down using truncation.

 @cindex @code{vec_pack_sbool_trunc_@var{m}} instruction pattern
 @item @samp{vec_pack_sbool_trunc_@var{m}}
 Narrow and merge the elements of two vectors.  Operands 1 and 2 are vectors
 of the same type having N boolean elements.  Operand 0 is the resulting
 vector in which 2*N elements are concatenated.  The last operand (operand 3)
 is the number of elements in the output vector 2*N as a @code{CONST_INT}.
 This instruction pattern is used when all the vector input and output
 operands have the same scalar mode @var{m} and thus using
 @code{vec_pack_trunc_@var{m}} would be ambiguous.

 @cindex @code{vec_pack_ssat_@var{m}} instruction pattern
 @cindex @code{vec_pack_usat_@var{m}} instruction pattern
 @item @samp{vec_pack_ssat_@var{m}}, @samp{vec_pack_usat_@var{m}}
 Narrow (demote) and merge the elements of two vectors.  Operands 1 and 2
 are vectors of the same mode having N integral elements of size S.
 Operand 0 is the resulting vector in which the elements of the two input
 vectors are concatenated after narrowing them down using signed/unsigned
 saturating arithmetic.

 @cindex @code{vec_pack_sfix_trunc_@var{m}} instruction pattern
 @cindex @code{vec_pack_ufix_trunc_@var{m}} instruction pattern
 @item @samp{vec_pack_sfix_trunc_@var{m}}, @samp{vec_pack_ufix_trunc_@var{m}}
 Narrow, convert to signed/unsigned integral type and merge the elements
 of two vectors.  Operands 1 and 2 are vectors of the same mode having N
 floating point elements of size S@.  Operand 0 is the resulting vector
 in which 2*N elements of size N/2 are concatenated.

 @cindex @code{vec_packs_float_@var{m}} instruction pattern
 @cindex @code{vec_packu_float_@var{m}} instruction pattern
 @item @samp{vec_packs_float_@var{m}}, @samp{vec_packu_float_@var{m}}
 Narrow, convert to floating point type and merge the elements
 of two vectors.  Operands 1 and 2 are vectors of the same mode having N
 signed/unsigned integral elements of size S@.  Operand 0 is the resulting vector
 in which 2*N elements of size N/2 are concatenated.

 @cindex @code{vec_unpacks_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpacks_lo_@var{m}} instruction pattern
 @item @samp{vec_unpacks_hi_@var{m}}, @samp{vec_unpacks_lo_@var{m}}
 Extract and widen (promote) the high/low part of a vector of signed
 integral or floating point elements.  The input vector (operand 1) has N
 elements of size S@.  Widen (promote) the high/low elements of the vector
 using signed or floating point extension and place the resulting N/2
 values of size 2*S in the output vector (operand 0).

 @cindex @code{vec_unpacku_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpacku_lo_@var{m}} instruction pattern
 @item @samp{vec_unpacku_hi_@var{m}}, @samp{vec_unpacku_lo_@var{m}}
 Extract and widen (promote) the high/low part of a vector of unsigned
 integral elements.  The input vector (operand 1) has N elements of size S.
 Widen (promote) the high/low elements of the vector using zero extension and
 place the resulting N/2 values of size 2*S in the output vector (operand 0).

 @cindex @code{vec_unpacks_sbool_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpacks_sbool_lo_@var{m}} instruction pattern
 @item @samp{vec_unpacks_sbool_hi_@var{m}}, @samp{vec_unpacks_sbool_lo_@var{m}}
 Extract the high/low part of a vector of boolean elements that have scalar
 mode @var{m}.  The input vector (operand 1) has N elements, the output
 vector (operand 0) has N/2 elements.  The last operand (operand 2) is the
 number of elements of the input vector N as a @code{CONST_INT}.  These
 patterns are used if both the input and output vectors have the same scalar
 mode @var{m} and thus using @code{vec_unpacks_hi_@var{m}} or
 @code{vec_unpacks_lo_@var{m}} would be ambiguous.

 @cindex @code{vec_unpacks_float_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpacks_float_lo_@var{m}} instruction pattern
 @cindex @code{vec_unpacku_float_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpacku_float_lo_@var{m}} instruction pattern
 @item @samp{vec_unpacks_float_hi_@var{m}}, @samp{vec_unpacks_float_lo_@var{m}}
 @itemx @samp{vec_unpacku_float_hi_@var{m}}, @samp{vec_unpacku_float_lo_@var{m}}
 Extract, convert to floating point type and widen the high/low part of a
 vector of signed/unsigned integral elements.  The input vector (operand 1)
 has N elements of size S@.  Convert the high/low elements of the vector using
 floating point conversion and place the resulting N/2 values of size 2*S in
 the output vector (operand 0).

 @cindex @code{vec_unpack_sfix_trunc_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpack_sfix_trunc_lo_@var{m}} instruction pattern
 @cindex @code{vec_unpack_ufix_trunc_hi_@var{m}} instruction pattern
 @cindex @code{vec_unpack_ufix_trunc_lo_@var{m}} instruction pattern
 @item @samp{vec_unpack_sfix_trunc_hi_@var{m}},
 @itemx @samp{vec_unpack_sfix_trunc_lo_@var{m}}
 @itemx @samp{vec_unpack_ufix_trunc_hi_@var{m}}
 @itemx @samp{vec_unpack_ufix_trunc_lo_@var{m}}
 Extract, convert to signed/unsigned integer type and widen the high/low part of a
 vector of floating point elements.  The input vector (operand 1)
 has N elements of size S@.  Convert the high/low elements of the vector
 to integers and place the resulting N/2 values of size 2*S in
 the output vector (operand 0).

 @cindex @code{vec_widen_umult_hi_@var{m}} instruction pattern
 @cindex @code{vec_widen_umult_lo_@var{m}} instruction pattern
 @cindex @code{vec_widen_smult_hi_@var{m}} instruction pattern
 @cindex @code{vec_widen_smult_lo_@var{m}} instruction pattern
 @cindex @code{vec_widen_umult_even_@var{m}} instruction pattern
 @cindex @code{vec_widen_umult_odd_@var{m}} instruction pattern
 @cindex @code{vec_widen_smult_even_@var{m}} instruction pattern
 @cindex @code{vec_widen_smult_odd_@var{m}} instruction pattern
 @item @samp{vec_widen_umult_hi_@var{m}}, @samp{vec_widen_umult_lo_@var{m}}
 @itemx @samp{vec_widen_smult_hi_@var{m}}, @samp{vec_widen_smult_lo_@var{m}}
 @itemx @samp{vec_widen_umult_even_@var{m}}, @samp{vec_widen_umult_odd_@var{m}}
 @itemx @samp{vec_widen_smult_even_@var{m}}, @samp{vec_widen_smult_odd_@var{m}}
 Signed/Unsigned widening multiplication.  The two inputs (operands 1 and 2)
 are vectors with N signed/unsigned elements of size S@.  Multiply the high/low
 or even/odd elements of the two vectors, and put the N/2 products of size 2*S
 in the output vector (operand 0). A target shouldn't implement even/odd pattern
 pair if it is less efficient than lo/hi one.

 @cindex @code{vec_widen_ushiftl_hi_@var{m}} instruction pattern
 @cindex @code{vec_widen_ushiftl_lo_@var{m}} instruction pattern
 @cindex @code{vec_widen_sshiftl_hi_@var{m}} instruction pattern
 @cindex @code{vec_widen_sshiftl_lo_@var{m}} instruction pattern
 @item @samp{vec_widen_ushiftl_hi_@var{m}}, @samp{vec_widen_ushiftl_lo_@var{m}}
 @itemx @samp{vec_widen_sshiftl_hi_@var{m}}, @samp{vec_widen_sshiftl_lo_@var{m}}
 Signed/Unsigned widening shift left.  The first input (operand 1) is a vector
 with N signed/unsigned elements of size S@.  Operand 2 is a constant.  Shift
 the high/low elements of operand 1, and put the N/2 results of size 2*S in the
 output vector (operand 0).

 @cindex @code{mulhisi3} instruction pattern
 @item @samp{mulhisi3}
 Multiply operands 1 and 2, which have mode @code{HImode}, and store
 a @code{SImode} product in operand 0.

 @cindex @code{mulqihi3} instruction pattern
 @cindex @code{mulsidi3} instruction pattern
 @item @samp{mulqihi3}, @samp{mulsidi3}
 Similar widening-multiplication instructions of other widths.

 @cindex @code{umulqihi3} instruction pattern
 @cindex @code{umulhisi3} instruction pattern
 @cindex @code{umulsidi3} instruction pattern
 @item @samp{umulqihi3}, @samp{umulhisi3}, @samp{umulsidi3}
 Similar widening-multiplication instructions that do unsigned
 multiplication.

 @cindex @code{usmulqihi3} instruction pattern
 @cindex @code{usmulhisi3} instruction pattern
 @cindex @code{usmulsidi3} instruction pattern
 @item @samp{usmulqihi3}, @samp{usmulhisi3}, @samp{usmulsidi3}
 Similar widening-multiplication instructions that interpret the first
 operand as unsigned and the second operand as signed, then do a signed
 multiplication.

 @cindex @code{smul@var{m}3_highpart} instruction pattern
 @item @samp{smul@var{m}3_highpart}
 Perform a signed multiplication of operands 1 and 2, which have mode
 @var{m}, and store the most significant half of the product in operand 0.
 The least significant half of the product is discarded.

 @cindex @code{umul@var{m}3_highpart} instruction pattern
 @item @samp{umul@var{m}3_highpart}
 Similar, but the multiplication is unsigned.

 @cindex @code{madd@var{m}@var{n}4} instruction pattern
 @item @samp{madd@var{m}@var{n}4}
 Multiply operands 1 and 2, sign-extend them to mode @var{n}, add
 operand 3, and store the result in operand 0.  Operands 1 and 2
 have mode @var{m} and operands 0 and 3 have mode @var{n}.
 Both modes must be integer or fixed-point modes and @var{n} must be twice
 the size of @var{m}.

 In other words, @code{madd@var{m}@var{n}4} is like
 @code{mul@var{m}@var{n}3} except that it also adds operand 3.

 These instructions are not allowed to @code{FAIL}.

 @cindex @code{umadd@var{m}@var{n}4} instruction pattern
 @item @samp{umadd@var{m}@var{n}4}
 Like @code{madd@var{m}@var{n}4}, but zero-extend the multiplication
 operands instead of sign-extending them.

 @cindex @code{ssmadd@var{m}@var{n}4} instruction pattern
 @item @samp{ssmadd@var{m}@var{n}4}
 Like @code{madd@var{m}@var{n}4}, but all involved operations must be
 signed-saturating.

 @cindex @code{usmadd@var{m}@var{n}4} instruction pattern
 @item @samp{usmadd@var{m}@var{n}4}
 Like @code{umadd@var{m}@var{n}4}, but all involved operations must be
 unsigned-saturating.

 @cindex @code{msub@var{m}@var{n}4} instruction pattern
 @item @samp{msub@var{m}@var{n}4}
 Multiply operands 1 and 2, sign-extend them to mode @var{n}, subtract the
 result from operand 3, and store the result in operand 0.  Operands 1 and 2
 have mode @var{m} and operands 0 and 3 have mode @var{n}.
 Both modes must be integer or fixed-point modes and @var{n} must be twice
 the size of @var{m}.

 In other words, @code{msub@var{m}@var{n}4} is like
 @code{mul@var{m}@var{n}3} except that it also subtracts the result
 from operand 3.

 These instructions are not allowed to @code{FAIL}.

 @cindex @code{umsub@var{m}@var{n}4} instruction pattern
 @item @samp{umsub@var{m}@var{n}4}
 Like @code{msub@var{m}@var{n}4}, but zero-extend the multiplication
 operands instead of sign-extending them.

 @cindex @code{ssmsub@var{m}@var{n}4} instruction pattern
 @item @samp{ssmsub@var{m}@var{n}4}
 Like @code{msub@var{m}@var{n}4}, but all involved operations must be
 signed-saturating.

 @cindex @code{usmsub@var{m}@var{n}4} instruction pattern
 @item @samp{usmsub@var{m}@var{n}4}
 Like @code{umsub@var{m}@var{n}4}, but all involved operations must be
 unsigned-saturating.

 @cindex @code{divmod@var{m}4} instruction pattern
 @item @samp{divmod@var{m}4}
 Signed division that produces both a quotient and a remainder.
 Operand 1 is divided by operand 2 to produce a quotient stored
 in operand 0 and a remainder stored in operand 3.

 For machines with an instruction that produces both a quotient and a
 remainder, provide a pattern for @samp{divmod@var{m}4} but do not
 provide patterns for @samp{div@var{m}3} and @samp{mod@var{m}3}.  This
 allows optimization in the relatively common case when both the quotient
 and remainder are computed.

 If an instruction that just produces a quotient or just a remainder
 exists and is more efficient than the instruction that produces both,
 write the output routine of @samp{divmod@var{m}4} to call
 @code{find_reg_note} and look for a @code{REG_UNUSED} note on the
 quotient or remainder and generate the appropriate instruction.

 @cindex @code{udivmod@var{m}4} instruction pattern
 @item @samp{udivmod@var{m}4}
 Similar, but does unsigned division.

 @anchor{shift patterns}
 @cindex @code{ashl@var{m}3} instruction pattern
 @cindex @code{ssashl@var{m}3} instruction pattern
 @cindex @code{usashl@var{m}3} instruction pattern
 @item @samp{ashl@var{m}3}, @samp{ssashl@var{m}3}, @samp{usashl@var{m}3}
 Arithmetic-shift operand 1 left by a number of bits specified by operand
 2, and store the result in operand 0.  Here @var{m} is the mode of
 operand 0 and operand 1; operand 2's mode is specified by the
 instruction pattern, and the compiler will convert the operand to that
 mode before generating the instruction.  The shift or rotate expander
 or instruction pattern should explicitly specify the mode of the operand 2,
 it should never be @code{VOIDmode}.  The meaning of out-of-range shift
 counts can optionally be specified by @code{TARGET_SHIFT_TRUNCATION_MASK}.
 @xref{TARGET_SHIFT_TRUNCATION_MASK}.  Operand 2 is always a scalar type.

 @cindex @code{ashr@var{m}3} instruction pattern
 @cindex @code{lshr@var{m}3} instruction pattern
 @cindex @code{rotl@var{m}3} instruction pattern
 @cindex @code{rotr@var{m}3} instruction pattern
 @item @samp{ashr@var{m}3}, @samp{lshr@var{m}3}, @samp{rotl@var{m}3}, @samp{rotr@var{m}3}
 Other shift and rotate instructions, analogous to the
 @code{ashl@var{m}3} instructions.  Operand 2 is always a scalar type.

 @cindex @code{vashl@var{m}3} instruction pattern
 @cindex @code{vashr@var{m}3} instruction pattern
 @cindex @code{vlshr@var{m}3} instruction pattern
 @cindex @code{vrotl@var{m}3} instruction pattern
 @cindex @code{vrotr@var{m}3} instruction pattern
 @item @samp{vashl@var{m}3}, @samp{vashr@var{m}3}, @samp{vlshr@var{m}3}, @samp{vrotl@var{m}3}, @samp{vrotr@var{m}3}
 Vector shift and rotate instructions that take vectors as operand 2
 instead of a scalar type.

 @cindex @code{avg@var{m}3_floor} instruction pattern
 @cindex @code{uavg@var{m}3_floor} instruction pattern
 @item @samp{avg@var{m}3_floor}
 @itemx @samp{uavg@var{m}3_floor}
 Signed and unsigned average instructions.  These instructions add
 operands 1 and 2 without truncation, divide the result by 2,
 round towards -Inf, and store the result in operand 0.  This is
 equivalent to the C code:
 @smallexample
 narrow op0, op1, op2;
 @dots{}
 op0 = (narrow) (((wide) op1 + (wide) op2) >> 1);
 @end smallexample
 where the sign of @samp{narrow} determines whether this is a signed
 or unsigned operation.

 @cindex @code{avg@var{m}3_ceil} instruction pattern
 @cindex @code{uavg@var{m}3_ceil} instruction pattern
 @item @samp{avg@var{m}3_ceil}
 @itemx @samp{uavg@var{m}3_ceil}
 Like @samp{avg@var{m}3_floor} and @samp{uavg@var{m}3_floor}, but round
 towards +Inf.  This is equivalent to the C code:
 @smallexample
 narrow op0, op1, op2;
 @dots{}
 op0 = (narrow) (((wide) op1 + (wide) op2 + 1) >> 1);
 @end smallexample

 @cindex @code{bswap@var{m}2} instruction pattern
 @item @samp{bswap@var{m}2}
 Reverse the order of bytes of operand 1 and store the result in operand 0.

 @cindex @code{neg@var{m}2} instruction pattern
 @cindex @code{ssneg@var{m}2} instruction pattern
 @cindex @code{usneg@var{m}2} instruction pattern
 @item @samp{neg@var{m}2}, @samp{ssneg@var{m}2}, @samp{usneg@var{m}2}
 Negate operand 1 and store the result in operand 0.

 @cindex @code{negv@var{m}3} instruction pattern
 @item @samp{negv@var{m}3}
 Like @code{neg@var{m}2} but takes a @code{code_label} as operand 2 and
 emits code to jump to it if signed overflow occurs during the negation.

 @cindex @code{abs@var{m}2} instruction pattern
 @item @samp{abs@var{m}2}
 Store the absolute value of operand 1 into operand 0.

 @cindex @code{sqrt@var{m}2} instruction pattern
 @item @samp{sqrt@var{m}2}
 Store the square root of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{rsqrt@var{m}2} instruction pattern
 @item @samp{rsqrt@var{m}2}
 Store the reciprocal of the square root of operand 1 into operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 On most architectures this pattern is only approximate, so either
 its C condition or the @code{TARGET_OPTAB_SUPPORTED_P} hook should
 check for the appropriate math flags.  (Using the C condition is
 more direct, but using @code{TARGET_OPTAB_SUPPORTED_P} can be useful
 if a target-specific built-in also uses the @samp{rsqrt@var{m}2}
 pattern.)

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{fmod@var{m}3} instruction pattern
 @item @samp{fmod@var{m}3}
 Store the remainder of dividing operand 1 by operand 2 into
 operand 0, rounded towards zero to an integer.  All operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{remainder@var{m}3} instruction pattern
 @item @samp{remainder@var{m}3}
 Store the remainder of dividing operand 1 by operand 2 into
 operand 0, rounded to the nearest integer.  All operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{scalb@var{m}3} instruction pattern
 @item @samp{scalb@var{m}3}
 Raise @code{FLT_RADIX} to the power of operand 2, multiply it by
 operand 1, and store the result in operand 0.  All operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{ldexp@var{m}3} instruction pattern
 @item @samp{ldexp@var{m}3}
 Raise 2 to the power of operand 2, multiply it by operand 1, and store
 the result in operand 0.  Operands 0 and 1 have mode @var{m}, which is
 a scalar or vector floating-point mode.  Operand 2's mode has
 the same number of elements as @var{m} and each element is wide
 enough to store an @code{int}.  The integers are signed.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{cos@var{m}2} instruction pattern
 @item @samp{cos@var{m}2}
 Store the cosine of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{sin@var{m}2} instruction pattern
 @item @samp{sin@var{m}2}
 Store the sine of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{sincos@var{m}3} instruction pattern
 @item @samp{sincos@var{m}3}
 Store the cosine of operand 2 into operand 0 and the sine of
 operand 2 into operand 1.  All operands have mode @var{m},
 which is a scalar or vector floating-point mode.

 Targets that can calculate the sine and cosine simultaneously can
 implement this pattern as opposed to implementing individual
 @code{sin@var{m}2} and @code{cos@var{m}2} patterns.  The @code{sin}
 and @code{cos} built-in functions will then be expanded to the
 @code{sincos@var{m}3} pattern, with one of the output values
 left unused.

 @cindex @code{tan@var{m}2} instruction pattern
 @item @samp{tan@var{m}2}
 Store the tangent of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{asin@var{m}2} instruction pattern
 @item @samp{asin@var{m}2}
 Store the arc sine of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{acos@var{m}2} instruction pattern
 @item @samp{acos@var{m}2}
 Store the arc cosine of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{atan@var{m}2} instruction pattern
 @item @samp{atan@var{m}2}
 Store the arc tangent of operand 1 into operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{exp@var{m}2} instruction pattern
 @item @samp{exp@var{m}2}
 Raise e (the base of natural logarithms) to the power of operand 1
 and store the result in operand 0.  Both operands have mode @var{m},
 which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{expm1@var{m}2} instruction pattern
 @item @samp{expm1@var{m}2}
 Raise e (the base of natural logarithms) to the power of operand 1,
 subtract 1, and store the result in operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.

 For inputs close to zero, the pattern is expected to be more
 accurate than a separate @code{exp@var{m}2} and @code{sub@var{m}3}
 would be.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{exp10@var{m}2} instruction pattern
 @item @samp{exp10@var{m}2}
 Raise 10 to the power of operand 1 and store the result in operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{exp2@var{m}2} instruction pattern
 @item @samp{exp2@var{m}2}
 Raise 2 to the power of operand 1 and store the result in operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{log@var{m}2} instruction pattern
 @item @samp{log@var{m}2}
 Store the natural logarithm of operand 1 into operand 0.  Both operands
 have mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{log1p@var{m}2} instruction pattern
 @item @samp{log1p@var{m}2}
 Add 1 to operand 1, compute the natural logarithm, and store
 the result in operand 0.  Both operands have mode @var{m}, which is
 a scalar or vector floating-point mode.

 For inputs close to zero, the pattern is expected to be more
 accurate than a separate @code{add@var{m}3} and @code{log@var{m}2}
 would be.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{log10@var{m}2} instruction pattern
 @item @samp{log10@var{m}2}
 Store the base-10 logarithm of operand 1 into operand 0.  Both operands
 have mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{log2@var{m}2} instruction pattern
 @item @samp{log2@var{m}2}
 Store the base-2 logarithm of operand 1 into operand 0.  Both operands
 have mode @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{logb@var{m}2} instruction pattern
 @item @samp{logb@var{m}2}
 Store the base-@code{FLT_RADIX} logarithm of operand 1 into operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{significand@var{m}2} instruction pattern
 @item @samp{significand@var{m}2}
 Store the significand of floating-point operand 1 in operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{pow@var{m}3} instruction pattern
 @item @samp{pow@var{m}3}
 Store the value of operand 1 raised to the exponent operand 2
 into operand 0.  All operands have mode @var{m}, which is a scalar
 or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{atan2@var{m}3} instruction pattern
 @item @samp{atan2@var{m}3}
 Store the arc tangent (inverse tangent) of operand 1 divided by
 operand 2 into operand 0, using the signs of both arguments to
 determine the quadrant of the result.  All operands have mode
 @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{floor@var{m}2} instruction pattern
 @item @samp{floor@var{m}2}
 Store the largest integral value not greater than operand 1 in operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.  If @option{-ffp-int-builtin-inexact} is in
 effect, the ``inexact'' exception may be raised for noninteger
 operands; otherwise, it may not.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{btrunc@var{m}2} instruction pattern
 @item @samp{btrunc@var{m}2}
 Round operand 1 to an integer, towards zero, and store the result in
 operand 0.  Both operands have mode @var{m}, which is a scalar or
 vector floating-point mode.  If @option{-ffp-int-builtin-inexact} is
 in effect, the ``inexact'' exception may be raised for noninteger
 operands; otherwise, it may not.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{round@var{m}2} instruction pattern
 @item @samp{round@var{m}2}
 Round operand 1 to the nearest integer, rounding away from zero in the
 event of a tie, and store the result in operand 0.  Both operands have
 mode @var{m}, which is a scalar or vector floating-point mode.  If
 @option{-ffp-int-builtin-inexact} is in effect, the ``inexact''
 exception may be raised for noninteger operands; otherwise, it may
 not.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{ceil@var{m}2} instruction pattern
 @item @samp{ceil@var{m}2}
 Store the smallest integral value not less than operand 1 in operand 0.
 Both operands have mode @var{m}, which is a scalar or vector
 floating-point mode.  If @option{-ffp-int-builtin-inexact} is in
 effect, the ``inexact'' exception may be raised for noninteger
 operands; otherwise, it may not.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{nearbyint@var{m}2} instruction pattern
 @item @samp{nearbyint@var{m}2}
 Round operand 1 to an integer, using the current rounding mode, and
 store the result in operand 0.  Do not raise an inexact condition when
 the result is different from the argument.  Both operands have mode
 @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{rint@var{m}2} instruction pattern
 @item @samp{rint@var{m}2}
 Round operand 1 to an integer, using the current rounding mode, and
 store the result in operand 0.  Raise an inexact condition when
 the result is different from the argument.  Both operands have mode
 @var{m}, which is a scalar or vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{lrint@var{m}@var{n}2}
 @item @samp{lrint@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as a signed number according to the current
 rounding mode and store in operand 0 (which has mode @var{n}).

 @cindex @code{lround@var{m}@var{n}2}
 @item @samp{lround@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as a signed number rounding to nearest and away
 from zero and store in operand 0 (which has mode @var{n}).

 @cindex @code{lfloor@var{m}@var{n}2}
 @item @samp{lfloor@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as a signed number rounding down and store in
 operand 0 (which has mode @var{n}).

 @cindex @code{lceil@var{m}@var{n}2}
 @item @samp{lceil@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as a signed number rounding up and store in
 operand 0 (which has mode @var{n}).

 @cindex @code{copysign@var{m}3} instruction pattern
 @item @samp{copysign@var{m}3}
 Store a value with the magnitude of operand 1 and the sign of operand
 2 into operand 0.  All operands have mode @var{m}, which is a scalar or
 vector floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{xorsign@var{m}3} instruction pattern
 @item @samp{xorsign@var{m}3}
 Equivalent to @samp{op0 = op1 * copysign (1.0, op2)}: store a value with
 the magnitude of operand 1 and the sign of operand 2 into operand 0.
 All operands have mode @var{m}, which is a scalar or vector
 floating-point mode.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{ffs@var{m}2} instruction pattern
 @item @samp{ffs@var{m}2}
 Store into operand 0 one plus the index of the least significant 1-bit
 of operand 1.  If operand 1 is zero, store zero.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{clrsb@var{m}2} instruction pattern
 @item @samp{clrsb@var{m}2}
 Count leading redundant sign bits.
 Store into operand 0 the number of redundant sign bits in operand 1, starting
 at the most significant bit position.
 A redundant sign bit is defined as any sign bit after the first. As such,
 this count will be one less than the count of leading sign bits.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{clz@var{m}2} instruction pattern
 @item @samp{clz@var{m}2}
 Store into operand 0 the number of leading 0-bits in operand 1, starting
 at the most significant bit position.  If operand 1 is 0, the
 @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
 the result is undefined or has a useful value.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{ctz@var{m}2} instruction pattern
 @item @samp{ctz@var{m}2}
 Store into operand 0 the number of trailing 0-bits in operand 1, starting
 at the least significant bit position.  If operand 1 is 0, the
 @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
 the result is undefined or has a useful value.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{popcount@var{m}2} instruction pattern
 @item @samp{popcount@var{m}2}
 Store into operand 0 the number of 1-bits in operand 1.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{parity@var{m}2} instruction pattern
 @item @samp{parity@var{m}2}
 Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
 in operand 1 modulo 2.

 @var{m} is either a scalar or vector integer mode.  When it is a scalar,
 operand 1 has mode @var{m} but operand 0 can have whatever scalar
 integer mode is suitable for the target.  The compiler will insert
 conversion instructions as necessary (typically to convert the result
 to the same width as @code{int}).  When @var{m} is a vector, both
 operands must have mode @var{m}.

 This pattern is not allowed to @code{FAIL}.

 @cindex @code{one_cmpl@var{m}2} instruction pattern
 @item @samp{one_cmpl@var{m}2}
 Store the bitwise-complement of operand 1 into operand 0.

 @cindex @code{movmem@var{m}} instruction pattern
 @item @samp{movmem@var{m}}
 Block move instruction.  The destination and source blocks of memory
 are the first two operands, and both are @code{mem:BLK}s with an
 address in mode @code{Pmode}.

 The number of bytes to move is the third operand, in mode @var{m}.
 Usually, you specify @code{Pmode} for @var{m}.  However, if you can
 generate better code knowing the range of valid lengths is smaller than
 those representable in a full Pmode pointer, you should provide
 a pattern with a
 mode corresponding to the range of values you can handle efficiently
 (e.g., @code{QImode} for values in the range 0--127; note we avoid numbers
 that appear negative) and also a pattern with @code{Pmode}.

 The fourth operand is the known shared alignment of the source and
 destination, in the form of a @code{const_int} rtx.  Thus, if the
 compiler knows that both source and destination are word-aligned,
 it may provide the value 4 for this operand.

 Optional operands 5 and 6 specify expected alignment and size of block
 respectively.  The expected alignment differs from alignment in operand 4
 in a way that the blocks are not required to be aligned according to it in
 all cases. This expected alignment is also in bytes, just like operand 4.
 Expected size, when unknown, is set to @code{(const_int -1)}.

 Descriptions of multiple @code{movmem@var{m}} patterns can only be
 beneficial if the patterns for smaller modes have fewer restrictions
 on their first, second and fourth operands.  Note that the mode @var{m}
 in @code{movmem@var{m}} does not impose any restriction on the mode of
 individually moved data units in the block.

 These patterns need not give special consideration to the possibility
 that the source and destination strings might overlap.

 @cindex @code{movstr} instruction pattern
 @item @samp{movstr}
 String copy instruction, with @code{stpcpy} semantics.  Operand 0 is
 an output operand in mode @code{Pmode}.  The addresses of the
 destination and source strings are operands 1 and 2, and both are
 @code{mem:BLK}s with addresses in mode @code{Pmode}.  The execution of
 the expansion of this pattern should store in operand 0 the address in
 which the @code{NUL} terminator was stored in the destination string.

 This patern has also several optional operands that are same as in
 @code{setmem}.

 @cindex @code{setmem@var{m}} instruction pattern
 @item @samp{setmem@var{m}}
 Block set instruction.  The destination string is the first operand,
 given as a @code{mem:BLK} whose address is in mode @code{Pmode}.  The
 number of bytes to set is the second operand, in mode @var{m}.  The value to
 initialize the memory with is the third operand. Targets that only support the
 clearing of memory should reject any value that is not the constant 0.  See
 @samp{movmem@var{m}} for a discussion of the choice of mode.

 The fourth operand is the known alignment of the destination, in the form
 of a @code{const_int} rtx.  Thus, if the compiler knows that the
 destination is word-aligned, it may provide the value 4 for this
 operand.

 Optional operands 5 and 6 specify expected alignment and size of block
 respectively.  The expected alignment differs from alignment in operand 4
 in a way that the blocks are not required to be aligned according to it in
 all cases. This expected alignment is also in bytes, just like operand 4.
 Expected size, when unknown, is set to @code{(const_int -1)}.
 Operand 7 is the minimal size of the block and operand 8 is the
 maximal size of the block (NULL if it cannot be represented as CONST_INT).
 Operand 9 is the probable maximal size (i.e.@: we cannot rely on it for
 correctness, but it can be used for choosing proper code sequence for a
 given size).

 The use for multiple @code{setmem@var{m}} is as for @code{movmem@var{m}}.

 @cindex @code{cmpstrn@var{m}} instruction pattern
 @item @samp{cmpstrn@var{m}}
 String compare instruction, with five operands.  Operand 0 is the output;
 it has mode @var{m}.  The remaining four operands are like the operands
 of @samp{movmem@var{m}}.  The two memory blocks specified are compared
 byte by byte in lexicographic order starting at the beginning of each
 string.  The instruction is not allowed to prefetch more than one byte
 at a time since either string may end in the first byte and reading past
 that may access an invalid page or segment and cause a fault.  The
 comparison terminates early if the fetched bytes are different or if
 they are equal to zero.  The effect of the instruction is to store a
 value in operand 0 whose sign indicates the result of the comparison.

 @cindex @code{cmpstr@var{m}} instruction pattern
 @item @samp{cmpstr@var{m}}
 String compare instruction, without known maximum length.  Operand 0 is the
 output; it has mode @var{m}.  The second and third operand are the blocks of
 memory to be compared; both are @code{mem:BLK} with an address in mode
 @code{Pmode}.

 The fourth operand is the known shared alignment of the source and
 destination, in the form of a @code{const_int} rtx.  Thus, if the
 compiler knows that both source and destination are word-aligned,
 it may provide the value 4 for this operand.

 The two memory blocks specified are compared byte by byte in lexicographic
 order starting at the beginning of each string.  The instruction is not allowed
 to prefetch more than one byte at a time since either string may end in the
 first byte and reading past that may access an invalid page or segment and
 cause a fault.  The comparison will terminate when the fetched bytes
 are different or if they are equal to zero.  The effect of the
 instruction is to store a value in operand 0 whose sign indicates the
 result of the comparison.

 @cindex @code{cmpmem@var{m}} instruction pattern
 @item @samp{cmpmem@var{m}}
 Block compare instruction, with five operands like the operands
 of @samp{cmpstr@var{m}}.  The two memory blocks specified are compared
 byte by byte in lexicographic order starting at the beginning of each
 block.  Unlike @samp{cmpstr@var{m}} the instruction can prefetch
 any bytes in the two memory blocks.  Also unlike @samp{cmpstr@var{m}}
 the comparison will not stop if both bytes are zero.  The effect of
 the instruction is to store a value in operand 0 whose sign indicates
 the result of the comparison.

 @cindex @code{strlen@var{m}} instruction pattern
 @item @samp{strlen@var{m}}
 Compute the length of a string, with three operands.
 Operand 0 is the result (of mode @var{m}), operand 1 is
 a @code{mem} referring to the first character of the string,
 operand 2 is the character to search for (normally zero),
 and operand 3 is a constant describing the known alignment
 of the beginning of the string.

 @cindex @code{float@var{m}@var{n}2} instruction pattern
 @item @samp{float@var{m}@var{n}2}
 Convert signed integer operand 1 (valid for fixed point mode @var{m}) to
 floating point mode @var{n} and store in operand 0 (which has mode
 @var{n}).

 @cindex @code{floatuns@var{m}@var{n}2} instruction pattern
 @item @samp{floatuns@var{m}@var{n}2}
 Convert unsigned integer operand 1 (valid for fixed point mode @var{m})
 to floating point mode @var{n} and store in operand 0 (which has mode
 @var{n}).

 @cindex @code{fix@var{m}@var{n}2} instruction pattern
 @item @samp{fix@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as a signed number and store in operand 0 (which
 has mode @var{n}).  This instruction's result is defined only when
 the value of operand 1 is an integer.

 If the machine description defines this pattern, it also needs to
 define the @code{ftrunc} pattern.

 @cindex @code{fixuns@var{m}@var{n}2} instruction pattern
 @item @samp{fixuns@var{m}@var{n}2}
 Convert operand 1 (valid for floating point mode @var{m}) to fixed
 point mode @var{n} as an unsigned number and store in operand 0 (which
 has mode @var{n}).  This instruction's result is defined only when the
 value of operand 1 is an integer.

 @cindex @code{ftrunc@var{m}2} instruction pattern
 @item @samp{ftrunc@var{m}2}
 Convert operand 1 (valid for floating point mode @var{m}) to an
 integer value, still represented in floating point mode @var{m}, and
 store it in operand 0 (valid for floating point mode @var{m}).

 @cindex @code{fix_trunc@var{m}@var{n}2} instruction pattern
 @item @samp{fix_trunc@var{m}@var{n}2}
 Like @samp{fix@var{m}@var{n}2} but works for any floating point value
 of mode @var{m} by converting the value to an integer.

 @cindex @code{fixuns_trunc@var{m}@var{n}2} instruction pattern
 @item @samp{fixuns_trunc@var{m}@var{n}2}
 Like @samp{fixuns@var{m}@var{n}2} but works for any floating point
 value of mode @var{m} by converting the value to an integer.

 @cindex @code{trunc@var{m}@var{n}2} instruction pattern
 @item @samp{trunc@var{m}@var{n}2}
 Truncate operand 1 (valid for mode @var{m}) to mode @var{n} and
 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
 point or both floating point.

 @cindex @code{extend@var{m}@var{n}2} instruction pattern
 @item @samp{extend@var{m}@var{n}2}
 Sign-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
 point or both floating point.

 @cindex @code{zero_extend@var{m}@var{n}2} instruction pattern
 @item @samp{zero_extend@var{m}@var{n}2}
 Zero-extend operand 1 (valid for mode @var{m}) to mode @var{n} and
 store in operand 0 (which has mode @var{n}).  Both modes must be fixed
 point.

 @cindex @code{fract@var{m}@var{n}2} instruction pattern
 @item @samp{fract@var{m}@var{n}2}
 Convert operand 1 of mode @var{m} to mode @var{n} and store in
 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
 could be fixed-point to fixed-point, signed integer to fixed-point,
 fixed-point to signed integer, floating-point to fixed-point,
 or fixed-point to floating-point.
 When overflows or underflows happen, the results are undefined.

 @cindex @code{satfract@var{m}@var{n}2} instruction pattern
 @item @samp{satfract@var{m}@var{n}2}
 Convert operand 1 of mode @var{m} to mode @var{n} and store in
 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
 could be fixed-point to fixed-point, signed integer to fixed-point,
 or floating-point to fixed-point.
 When overflows or underflows happen, the instruction saturates the
 results to the maximum or the minimum.

 @cindex @code{fractuns@var{m}@var{n}2} instruction pattern
 @item @samp{fractuns@var{m}@var{n}2}
 Convert operand 1 of mode @var{m} to mode @var{n} and store in
 operand 0 (which has mode @var{n}).  Mode @var{m} and mode @var{n}
 could be unsigned integer to fixed-point, or
 fixed-point to unsigned integer.
 When overflows or underflows happen, the results are undefined.

 @cindex @code{satfractuns@var{m}@var{n}2} instruction pattern
 @item @samp{satfractuns@var{m}@var{n}2}
 Convert unsigned integer operand 1 of mode @var{m} to fixed-point mode
 @var{n} and store in operand 0 (which has mode @var{n}).
 When overflows or underflows happen, the instruction saturates the
 results to the maximum or the minimum.

 @cindex @code{extv@var{m}} instruction pattern
 @item @samp{extv@var{m}}
 Extract a bit-field from register operand 1, sign-extend it, and store
 it in operand 0.  Operand 2 specifies the width of the field in bits
 and operand 3 the starting bit, which counts from the most significant
 bit if @samp{BITS_BIG_ENDIAN} is true and from the least significant bit
 otherwise.

 Operands 0 and 1 both have mode @var{m}.  Operands 2 and 3 have a
 target-specific mode.

 @cindex @code{extvmisalign@var{m}} instruction pattern
 @item @samp{extvmisalign@var{m}}
 Extract a bit-field from memory operand 1, sign extend it, and store
 it in operand 0.  Operand 2 specifies the width in bits and operand 3
 the starting bit.  The starting bit is always somewhere in the first byte of
 operand 1; it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
 is true and from the least significant bit otherwise.

 Operand 0 has mode @var{m} while operand 1 has @code{BLK} mode.
 Operands 2 and 3 have a target-specific mode.

 The instruction must not read beyond the last byte of the bit-field.

 @cindex @code{extzv@var{m}} instruction pattern
 @item @samp{extzv@var{m}}
 Like @samp{extv@var{m}} except that the bit-field value is zero-extended.

 @cindex @code{extzvmisalign@var{m}} instruction pattern
 @item @samp{extzvmisalign@var{m}}
 Like @samp{extvmisalign@var{m}} except that the bit-field value is
 zero-extended.

 @cindex @code{insv@var{m}} instruction pattern
 @item @samp{insv@var{m}}
 Insert operand 3 into a bit-field of register operand 0.  Operand 1
 specifies the width of the field in bits and operand 2 the starting bit,
 which counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
 is true and from the least significant bit otherwise.

 Operands 0 and 3 both have mode @var{m}.  Operands 1 and 2 have a
 target-specific mode.

 @cindex @code{insvmisalign@var{m}} instruction pattern
 @item @samp{insvmisalign@var{m}}
 Insert operand 3 into a bit-field of memory operand 0.  Operand 1
 specifies the width of the field in bits and operand 2 the starting bit.
 The starting bit is always somewhere in the first byte of operand 0;
 it counts from the most significant bit if @samp{BITS_BIG_ENDIAN}
 is true and from the least significant bit otherwise.

 Operand 3 has mode @var{m} while operand 0 has @code{BLK} mode.
 Operands 1 and 2 have a target-specific mode.

 The instruction must not read or write beyond the last byte of the bit-field.

 @cindex @code{extv} instruction pattern
 @item @samp{extv}
 Extract a bit-field from operand 1 (a register or memory operand), where
 operand 2 specifies the width in bits and operand 3 the starting bit,
 and store it in operand 0.  Operand 0 must have mode @code{word_mode}.
 Operand 1 may have mode @code{byte_mode} or @code{word_mode}; often
 @code{word_mode} is allowed only for registers.  Operands 2 and 3 must
 be valid for @code{word_mode}.

 The RTL generation pass generates this instruction only with constants
 for operands 2 and 3 and the constant is never zero for operand 2.

 The bit-field value is sign-extended to a full word integer
 before it is stored in operand 0.

 This pattern is deprecated; please use @samp{extv@var{m}} and
 @code{extvmisalign@var{m}} instead.

 @cindex @code{extzv} instruction pattern
 @item @samp{extzv}
 Like @samp{extv} except that the bit-field value is zero-extended.

 This pattern is deprecated; please use @samp{extzv@var{m}} and
 @code{extzvmisalign@var{m}} instead.

 @cindex @code{insv} instruction pattern
 @item @samp{insv}
 Store operand 3 (which must be valid for @code{word_mode}) into a
 bit-field in operand 0, where operand 1 specifies the width in bits and
 operand 2 the starting bit.  Operand 0 may have mode @code{byte_mode} or
 @code{word_mode}; often @code{word_mode} is allowed only for registers.
 Operands 1 and 2 must be valid for @code{word_mode}.

 The RTL generation pass generates this instruction only with constants
 for operands 1 and 2 and the constant is never zero for operand 1.

 This pattern is deprecated; please use @samp{insv@var{m}} and
 @code{insvmisalign@var{m}} instead.

 @cindex @code{mov@var{mode}cc} instruction pattern
 @item @samp{mov@var{mode}cc}
 Conditionally move operand 2 or operand 3 into operand 0 according to the
 comparison in operand 1.  If the comparison is true, operand 2 is moved
 into operand 0, otherwise operand 3 is moved.

 The mode of the operands being compared need not be the same as the operands
 being moved.  Some machines, sparc64 for example, have instructions that
 conditionally move an integer value based on the floating point condition
 codes and vice versa.

 If the machine does not have conditional move instructions, do not
 define these patterns.

 @cindex @code{add@var{mode}cc} instruction pattern
 @item @samp{add@var{mode}cc}
 Similar to @samp{mov@var{mode}cc} but for conditional addition.  Conditionally
 move operand 2 or (operands 2 + operand 3) into operand 0 according to the
 comparison in operand 1.  If the comparison is false, operand 2 is moved into
 operand 0, otherwise (operand 2 + operand 3) is moved.

 @cindex @code{cond_add@var{mode}} instruction pattern
 @cindex @code{cond_sub@var{mode}} instruction pattern
 @cindex @code{cond_mul@var{mode}} instruction pattern
 @cindex @code{cond_div@var{mode}} instruction pattern
 @cindex @code{cond_udiv@var{mode}} instruction pattern
 @cindex @code{cond_mod@var{mode}} instruction pattern
 @cindex @code{cond_umod@var{mode}} instruction pattern
 @cindex @code{cond_and@var{mode}} instruction pattern
 @cindex @code{cond_ior@var{mode}} instruction pattern
 @cindex @code{cond_xor@var{mode}} instruction pattern
 @cindex @code{cond_smin@var{mode}} instruction pattern
 @cindex @code{cond_smax@var{mode}} instruction pattern
 @cindex @code{cond_umin@var{mode}} instruction pattern
 @cindex @code{cond_umax@var{mode}} instruction pattern
 @item @samp{cond_add@var{mode}}
 @itemx @samp{cond_sub@var{mode}}
 @itemx @samp{cond_mul@var{mode}}
 @itemx @samp{cond_div@var{mode}}
 @itemx @samp{cond_udiv@var{mode}}
 @itemx @samp{cond_mod@var{mode}}
 @itemx @samp{cond_umod@var{mode}}
 @itemx @samp{cond_and@var{mode}}
 @itemx @samp{cond_ior@var{mode}}
 @itemx @samp{cond_xor@var{mode}}
 @itemx @samp{cond_smin@var{mode}}
 @itemx @samp{cond_smax@var{mode}}
 @itemx @samp{cond_umin@var{mode}}
 @itemx @samp{cond_umax@var{mode}}
 When operand 1 is true, perform an operation on operands 2 and 3 and
 store the result in operand 0, otherwise store operand 4 in operand 0.
 The operation works elementwise if the operands are vectors.

 The scalar case is equivalent to:

 @smallexample
 op0 = op1 ? op2 @var{op} op3 : op4;
 @end smallexample

 while the vector case is equivalent to:

 @smallexample
 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
   op0[i] = op1[i] ? op2[i] @var{op} op3[i] : op4[i];
 @end smallexample

 where, for example, @var{op} is @code{+} for @samp{cond_add@var{mode}}.

 When defined for floating-point modes, the contents of @samp{op3[i]}
 are not interpreted if @samp{op1[i]} is false, just like they would not
 be in a normal C @samp{?:} condition.

 Operands 0, 2, 3 and 4 all have mode @var{m}.  Operand 1 is a scalar
 integer if @var{m} is scalar, otherwise it has the mode returned by
 @code{TARGET_VECTORIZE_GET_MASK_MODE}.

 @cindex @code{cond_fma@var{mode}} instruction pattern
 @cindex @code{cond_fms@var{mode}} instruction pattern
 @cindex @code{cond_fnma@var{mode}} instruction pattern
 @cindex @code{cond_fnms@var{mode}} instruction pattern
 @item @samp{cond_fma@var{mode}}
 @itemx @samp{cond_fms@var{mode}}
 @itemx @samp{cond_fnma@var{mode}}
 @itemx @samp{cond_fnms@var{mode}}
 Like @samp{cond_add@var{m}}, except that the conditional operation
 takes 3 operands rather than two.  For example, the vector form of
 @samp{cond_fma@var{mode}} is equivalent to:

 @smallexample
 for (i = 0; i < GET_MODE_NUNITS (@var{m}); i++)
   op0[i] = op1[i] ? fma (op2[i], op3[i], op4[i]) : op5[i];
 @end smallexample

 @cindex @code{neg@var{mode}cc} instruction pattern
 @item @samp{neg@var{mode}cc}
 Similar to @samp{mov@var{mode}cc} but for conditional negation.  Conditionally
 move the negation of operand 2 or the unchanged operand 3 into operand 0
 according to the comparison in operand 1.  If the comparison is true, the negation
 of operand 2 is moved into operand 0, otherwise operand 3 is moved.

 @cindex @code{not@var{mode}cc} instruction pattern
 @item @samp{not@var{mode}cc}
 Similar to @samp{neg@var{mode}cc} but for conditional complement.
 Conditionally move the bitwise complement of operand 2 or the unchanged
 operand 3 into operand 0 according to the comparison in operand 1.
 If the comparison is true, the complement of operand 2 is moved into
 operand 0, otherwise operand 3 is moved.

 @cindex @code{cstore@var{mode}4} instruction pattern
 @item @samp{cstore@var{mode}4}
 Store zero or nonzero in operand 0 according to whether a comparison
 is true.  Operand 1 is a comparison operator.  Operand 2 and operand 3
 are the first and second operand of the comparison, respectively.
 You specify the mode that operand 0 must have when you write the
 @code{match_operand} expression.  The compiler automatically sees which
 mode you have used and supplies an operand of that mode.

 The value stored for a true condition must have 1 as its low bit, or
 else must be negative.  Otherwise the instruction is not suitable and
 you should omit it from the machine description.  You describe to the
 compiler exactly which value is stored by defining the macro
 @code{STORE_FLAG_VALUE} (@pxref{Misc}).  If a description cannot be
 found that can be used for all the possible comparison operators, you
 should pick one and use a @code{define_expand} to map all results
 onto the one you chose.

 These operations may @code{FAIL}, but should do so only in relatively
 uncommon cases; if they would @code{FAIL} for common cases involving
 integer comparisons, it is best to restrict the predicates to not
 allow these operands.  Likewise if a given comparison operator will
 always fail, independent of the operands (for floating-point modes, the
 @code{ordered_comparison_operator} predicate is often useful in this case).

 If this pattern is omitted, the compiler will generate a conditional
 branch---for example, it may copy a constant one to the target and branching
 around an assignment of zero to the target---or a libcall.  If the predicate
 for operand 1 only rejects some operators, it will also try reordering the
 operands and/or inverting the result value (e.g.@: by an exclusive OR).
 These possibilities could be cheaper or equivalent to the instructions
 used for the @samp{cstore@var{mode}4} pattern followed by those required
 to convert a positive result from @code{STORE_FLAG_VALUE} to 1; in this
 case, you can and should make operand 1's predicate reject some operators
 in the @samp{cstore@var{mode}4} pattern, or remove the pattern altogether
 from the machine description.

 @cindex @code{cbranch@var{mode}4} instruction pattern
 @item @samp{cbranch@var{mode}4}
 Conditional branch instruction combined with a compare instruction.
 Operand 0 is a comparison operator.  Operand 1 and operand 2 are the
 first and second operands of the comparison, respectively.  Operand 3
 is the @code{code_label} to jump to.

 @cindex @code{jump} instruction pattern
 @item @samp{jump}
 A jump inside a function; an unconditional branch.  Operand 0 is the
 @code{code_label} to jump to.  This pattern name is mandatory on all
 machines.

 @cindex @code{call} instruction pattern
 @item @samp{call}
 Subroutine call instruction returning no value.  Operand 0 is the
 function to call; operand 1 is the number of bytes of arguments pushed
 as a @code{const_int}; operand 2 is the number of registers used as
 operands.

 On most machines, operand 2 is not actually stored into the RTL
 pattern.  It is supplied for the sake of some RISC machines which need
 to put this information into the assembler code; they can put it in
 the RTL instead of operand 1.

 Operand 0 should be a @code{mem} RTX whose address is the address of the
 function.  Note, however, that this address can be a @code{symbol_ref}
 expression even if it would not be a legitimate memory address on the
 target machine.  If it is also not a valid argument for a call
 instruction, the pattern for this operation should be a
 @code{define_expand} (@pxref{Expander Definitions}) that places the
 address into a register and uses that register in the call instruction.

 @cindex @code{call_value} instruction pattern
 @item @samp{call_value}
 Subroutine call instruction returning a value.  Operand 0 is the hard
 register in which the value is returned.  There are three more
 operands, the same as the three operands of the @samp{call}
 instruction (but with numbers increased by one).

 Subroutines that return @code{BLKmode} objects use the @samp{call}
 insn.

 @cindex @code{call_pop} instruction pattern
 @cindex @code{call_value_pop} instruction pattern
 @item @samp{call_pop}, @samp{call_value_pop}
 Similar to @samp{call} and @samp{call_value}, except used if defined and
 if @code{RETURN_POPS_ARGS} is nonzero.  They should emit a @code{parallel}
 that contains both the function call and a @code{set} to indicate the
 adjustment made to the frame pointer.

 For machines where @code{RETURN_POPS_ARGS} can be nonzero, the use of these
 patterns increases the number of functions for which the frame pointer
 can be eliminated, if desired.

 @cindex @code{untyped_call} instruction pattern
 @item @samp{untyped_call}
 Subroutine call instruction returning a value of any type.  Operand 0 is
 the function to call; operand 1 is a memory location where the result of
 calling the function is to be stored; operand 2 is a @code{parallel}
 expression where each element is a @code{set} expression that indicates
 the saving of a function return value into the result block.

 This instruction pattern should be defined to support
 @code{__builtin_apply} on machines where special instructions are needed
 to call a subroutine with arbitrary arguments or to save the value
 returned.  This instruction pattern is required on machines that have
 multiple registers that can hold a return value
 (i.e.@: @code{FUNCTION_VALUE_REGNO_P} is true for more than one register).

 @cindex @code{return} instruction pattern
 @item @samp{return}
 Subroutine return instruction.  This instruction pattern name should be
 defined only if a single instruction can do all the work of returning
 from a function.

 Like the @samp{mov@var{m}} patterns, this pattern is also used after the
 RTL generation phase.  In this case it is to support machines where
 multiple instructions are usually needed to return from a function, but
 some class of functions only requires one instruction to implement a
 return.  Normally, the applicable functions are those which do not need
 to save any registers or allocate stack space.

 It is valid for this pattern to expand to an instruction using
 @code{simple_return} if no epilogue is required.

 @cindex @code{simple_return} instruction pattern
 @item @samp{simple_return}
 Subroutine return instruction.  This instruction pattern name should be
 defined only if a single instruction can do all the work of returning
 from a function on a path where no epilogue is required.  This pattern
 is very similar to the @code{return} instruction pattern, but it is emitted
 only by the shrink-wrapping optimization on paths where the function
 prologue has not been executed, and a function return should occur without
 any of the effects of the epilogue.  Additional uses may be introduced on
 paths where both the prologue and the epilogue have executed.

 @findex reload_completed
 @findex leaf_function_p
 For such machines, the condition specified in this pattern should only
 be true when @code{reload_completed} is nonzero and the function's
 epilogue would only be a single instruction.  For machines with register
 windows, the routine @code{leaf_function_p} may be used to determine if
 a register window push is required.

 Machines that have conditional return instructions should define patterns
 such as

 @smallexample
 (define_insn ""
   [(set (pc)
         (if_then_else (match_operator
                          0 "comparison_operator"
                          [(cc0) (const_int 0)])
                       (return)
                       (pc)))]
   "@var{condition}"
   "@dots{}")
 @end smallexample

 where @var{condition} would normally be the same condition specified on the
 named @samp{return} pattern.

 @cindex @code{untyped_return} instruction pattern
 @item @samp{untyped_return}
 Untyped subroutine return instruction.  This instruction pattern should
 be defined to support @code{__builtin_return} on machines where special
 instructions are needed to return a value of any type.

 Operand 0 is a memory location where the result of calling a function
 with @code{__builtin_apply} is stored; operand 1 is a @code{parallel}
 expression where each element is a @code{set} expression that indicates
 the restoring of a function return value from the result block.

 @cindex @code{nop} instruction pattern
 @item @samp{nop}
 No-op instruction.  This instruction pattern name should always be defined
 to output a no-op in assembler code.  @code{(const_int 0)} will do as an
 RTL pattern.

 @cindex @code{indirect_jump} instruction pattern
 @item @samp{indirect_jump}
 An instruction to jump to an address which is operand zero.
 This pattern name is mandatory on all machines.

 @cindex @code{casesi} instruction pattern
 @item @samp{casesi}
 Instruction to jump through a dispatch table, including bounds checking.
 This instruction takes five operands:

 @enumerate
 @item
 The index to dispatch on, which has mode @code{SImode}.

 @item
 The lower bound for indices in the table, an integer constant.

 @item
 The total range of indices in the table---the largest index
 minus the smallest one (both inclusive).

 @item
 A label that precedes the table itself.

 @item
 A label to jump to if the index has a value outside the bounds.
 @end enumerate

 The table is an @code{addr_vec} or @code{addr_diff_vec} inside of a
 @code{jump_table_data}.  The number of elements in the table is one plus the
 difference between the upper bound and the lower bound.

 @cindex @code{tablejump} instruction pattern
 @item @samp{tablejump}
 Instruction to jump to a variable address.  This is a low-level
 capability which can be used to implement a dispatch table when there
 is no @samp{casesi} pattern.

 This pattern requires two operands: the address or offset, and a label
 which should immediately precede the jump table.  If the macro
 @code{CASE_VECTOR_PC_RELATIVE} evaluates to a nonzero value then the first
 operand is an offset which counts from the address of the table; otherwise,
 it is an absolute address to jump to.  In either case, the first operand has
 mode @code{Pmode}.

 The @samp{tablejump} insn is always the last insn before the jump
 table it uses.  Its assembler code normally has no need to use the
 second operand, but you should incorporate it in the RTL pattern so
 that the jump optimizer will not delete the table as unreachable code.


 @cindex @code{doloop_end} instruction pattern
 @item @samp{doloop_end}
 Conditional branch instruction that decrements a register and
 jumps if the register is nonzero.  Operand 0 is the register to
 decrement and test; operand 1 is the label to jump to if the
 register is nonzero.
 @xref{Looping Patterns}.

 This optional instruction pattern should be defined for machines with
 low-overhead looping instructions as the loop optimizer will try to
 modify suitable loops to utilize it.  The target hook
 @code{TARGET_CAN_USE_DOLOOP_P} controls the conditions under which
 low-overhead loops can be used.

 @cindex @code{doloop_begin} instruction pattern
 @item @samp{doloop_begin}
 Companion instruction to @code{doloop_end} required for machines that
 need to perform some initialization, such as loading a special counter
 register.  Operand 1 is the associated @code{doloop_end} pattern and
 operand 0 is the register that it decrements.

 If initialization insns do not always need to be emitted, use a
 @code{define_expand} (@pxref{Expander Definitions}) and make it fail.

 @cindex @code{canonicalize_funcptr_for_compare} instruction pattern
 @item @samp{canonicalize_funcptr_for_compare}
 Canonicalize the function pointer in operand 1 and store the result
 into operand 0.

 Operand 0 is always a @code{reg} and has mode @code{Pmode}; operand 1
 may be a @code{reg}, @code{mem}, @code{symbol_ref}, @code{const_int}, etc
 and also has mode @code{Pmode}.

 Canonicalization of a function pointer usually involves computing
 the address of the function which would be called if the function
 pointer were used in an indirect call.

 Only define this pattern if function pointers on the target machine
 can have different values but still call the same function when
 used in an indirect call.

 @cindex @code{save_stack_block} instruction pattern
 @cindex @code{save_stack_function} instruction pattern
 @cindex @code{save_stack_nonlocal} instruction pattern
 @cindex @code{restore_stack_block} instruction pattern
 @cindex @code{restore_stack_function} instruction pattern
 @cindex @code{restore_stack_nonlocal} instruction pattern
 @item @samp{save_stack_block}
 @itemx @samp{save_stack_function}
 @itemx @samp{save_stack_nonlocal}
 @itemx @samp{restore_stack_block}
 @itemx @samp{restore_stack_function}
 @itemx @samp{restore_stack_nonlocal}
 Most machines save and restore the stack pointer by copying it to or
 from an object of mode @code{Pmode}.  Do not define these patterns on
 such machines.

 Some machines require special handling for stack pointer saves and
 restores.  On those machines, define the patterns corresponding to the
 non-standard cases by using a @code{define_expand} (@pxref{Expander
 Definitions}) that produces the required insns.  The three types of
 saves and restores are:

 @enumerate
 @item
 @samp{save_stack_block} saves the stack pointer at the start of a block
 that allocates a variable-sized object, and @samp{restore_stack_block}
 restores the stack pointer when the block is exited.

 @item
 @samp{save_stack_function} and @samp{restore_stack_function} do a
 similar job for the outermost block of a function and are used when the
 function allocates variable-sized objects or calls @code{alloca}.  Only
 the epilogue uses the restored stack pointer, allowing a simpler save or
 restore sequence on some machines.

 @item
 @samp{save_stack_nonlocal} is used in functions that contain labels
 branched to by nested functions.  It saves the stack pointer in such a
 way that the inner function can use @samp{restore_stack_nonlocal} to
 restore the stack pointer.  The compiler generates code to restore the
 frame and argument pointer registers, but some machines require saving
 and restoring additional data such as register window information or
 stack backchains.  Place insns in these patterns to save and restore any
 such required data.
 @end enumerate

 When saving the stack pointer, operand 0 is the save area and operand 1
 is the stack pointer.  The mode used to allocate the save area defaults
 to @code{Pmode} but you can override that choice by defining the
 @code{STACK_SAVEAREA_MODE} macro (@pxref{Storage Layout}).  You must
 specify an integral mode, or @code{VOIDmode} if no save area is needed
 for a particular type of save (either because no save is needed or
 because a machine-specific save area can be used).  Operand 0 is the
 stack pointer and operand 1 is the save area for restore operations.  If
 @samp{save_stack_block} is defined, operand 0 must not be
 @code{VOIDmode} since these saves can be arbitrarily nested.

 A save area is a @code{mem} that is at a constant offset from
 @code{virtual_stack_vars_rtx} when the stack pointer is saved for use by
 nonlocal gotos and a @code{reg} in the other two cases.

 @cindex @code{allocate_stack} instruction pattern
 @item @samp{allocate_stack}
 Subtract (or add if @code{STACK_GROWS_DOWNWARD} is undefined) operand 1 from
 the stack pointer to create space for dynamically allocated data.

 Store the resultant pointer to this space into operand 0.  If you
 are allocating space from the main stack, do this by emitting a
 move insn to copy @code{virtual_stack_dynamic_rtx} to operand 0.
 If you are allocating the space elsewhere, generate code to copy the
 location of the space to operand 0.  In the latter case, you must
 ensure this space gets freed when the corresponding space on the main
 stack is free.

 Do not define this pattern if all that must be done is the subtraction.
 Some machines require other operations such as stack probes or
 maintaining the back chain.  Define this pattern to emit those
 operations in addition to updating the stack pointer.

 @cindex @code{check_stack} instruction pattern
 @item @samp{check_stack}
 If stack checking (@pxref{Stack Checking}) cannot be done on your system by
 probing the stack, define this pattern to perform the needed check and signal
 an error if the stack has overflowed.  The single operand is the address in
 the stack farthest from the current stack pointer that you need to validate.
 Normally, on platforms where this pattern is needed, you would obtain the
 stack limit from a global or thread-specific variable or register.

 @cindex @code{probe_stack_address} instruction pattern
 @item @samp{probe_stack_address}
 If stack checking (@pxref{Stack Checking}) can be done on your system by
 probing the stack but without the need to actually access it, define this
 pattern and signal an error if the stack has overflowed.  The single operand
 is the memory address in the stack that needs to be probed.

 @cindex @code{probe_stack} instruction pattern
 @item @samp{probe_stack}
 If stack checking (@pxref{Stack Checking}) can be done on your system by
 probing the stack but doing it with a ``store zero'' instruction is not valid
 or optimal, define this pattern to do the probing differently and signal an
 error if the stack has overflowed.  The single operand is the memory reference
 in the stack that needs to be probed.

 @cindex @code{nonlocal_goto} instruction pattern
 @item @samp{nonlocal_goto}
 Emit code to generate a non-local goto, e.g., a jump from one function
 to a label in an outer function.  This pattern has four arguments,
 each representing a value to be used in the jump.  The first
 argument is to be loaded into the frame pointer, the second is
 the address to branch to (code to dispatch to the actual label),
 the third is the address of a location where the stack is saved,
 and the last is the address of the label, to be placed in the
 location for the incoming static chain.

 On most machines you need not define this pattern, since GCC will
 already generate the correct code, which is to load the frame pointer
 and static chain, restore the stack (using the
 @samp{restore_stack_nonlocal} pattern, if defined), and jump indirectly
 to the dispatcher.  You need only define this pattern if this code will
 not work on your machine.

 @cindex @code{nonlocal_goto_receiver} instruction pattern
 @item @samp{nonlocal_goto_receiver}
 This pattern, if defined, contains code needed at the target of a
 nonlocal goto after the code already generated by GCC@.  You will not
 normally need to define this pattern.  A typical reason why you might
 need this pattern is if some value, such as a pointer to a global table,
 must be restored when the frame pointer is restored.  Note that a nonlocal
 goto only occurs within a unit-of-translation, so a global table pointer
 that is shared by all functions of a given module need not be restored.
 There are no arguments.

 @cindex @code{exception_receiver} instruction pattern
 @item @samp{exception_receiver}
 This pattern, if defined, contains code needed at the site of an
 exception handler that isn't needed at the site of a nonlocal goto.  You
 will not normally need to define this pattern.  A typical reason why you
 might need this pattern is if some value, such as a pointer to a global
 table, must be restored after control flow is branched to the handler of
 an exception.  There are no arguments.

 @cindex @code{builtin_setjmp_setup} instruction pattern
 @item @samp{builtin_setjmp_setup}
 This pattern, if defined, contains additional code needed to initialize
 the @code{jmp_buf}.  You will not normally need to define this pattern.
 A typical reason why you might need this pattern is if some value, such
 as a pointer to a global table, must be restored.  Though it is
 preferred that the pointer value be recalculated if possible (given the
 address of a label for instance).  The single argument is a pointer to
 the @code{jmp_buf}.  Note that the buffer is five words long and that
 the first three are normally used by the generic mechanism.

 @cindex @code{builtin_setjmp_receiver} instruction pattern
 @item @samp{builtin_setjmp_receiver}
 This pattern, if defined, contains code needed at the site of a
 built-in setjmp that isn't needed at the site of a nonlocal goto.  You
 will not normally need to define this pattern.  A typical reason why you
 might need this pattern is if some value, such as a pointer to a global
 table, must be restored.  It takes one argument, which is the label
 to which builtin_longjmp transferred control; this pattern may be emitted
 at a small offset from that label.

 @cindex @code{builtin_longjmp} instruction pattern
 @item @samp{builtin_longjmp}
 This pattern, if defined, performs the entire action of the longjmp.
 You will not normally need to define this pattern unless you also define
 @code{builtin_setjmp_setup}.  The single argument is a pointer to the
 @code{jmp_buf}.

 @cindex @code{eh_return} instruction pattern
 @item @samp{eh_return}
 This pattern, if defined, affects the way @code{__builtin_eh_return},
 and thence the call frame exception handling library routines, are
 built.  It is intended to handle non-trivial actions needed along
 the abnormal return path.

 The address of the exception handler to which the function should return
 is passed as operand to this pattern.  It will normally need to copied by
 the pattern to some special register or memory location.
 If the pattern needs to determine the location of the target call
 frame in order to do so, it may use @code{EH_RETURN_STACKADJ_RTX},
 if defined; it will have already been assigned.

 If this pattern is not defined, the default action will be to simply
 copy the return address to @code{EH_RETURN_HANDLER_RTX}.  Either
 that macro or this pattern needs to be defined if call frame exception
 handling is to be used.

 @cindex @code{prologue} instruction pattern
 @anchor{prologue instruction pattern}
 @item @samp{prologue}
 This pattern, if defined, emits RTL for entry to a function.  The function
 entry is responsible for setting up the stack frame, initializing the frame
 pointer register, saving callee saved registers, etc.

 Using a prologue pattern is generally preferred over defining
 @code{TARGET_ASM_FUNCTION_PROLOGUE} to emit assembly code for the prologue.

 The @code{prologue} pattern is particularly useful for targets which perform
 instruction scheduling.

 @cindex @code{window_save} instruction pattern
 @anchor{window_save instruction pattern}
 @item @samp{window_save}
 This pattern, if defined, emits RTL for a register window save.  It should
 be defined if the target machine has register windows but the window events
 are decoupled from calls to subroutines.  The canonical example is the SPARC
 architecture.

 @cindex @code{epilogue} instruction pattern
 @anchor{epilogue instruction pattern}
 @item @samp{epilogue}
 This pattern emits RTL for exit from a function.  The function
 exit is responsible for deallocating the stack frame, restoring callee saved
 registers and emitting the return instruction.

 Using an epilogue pattern is generally preferred over defining
 @code{TARGET_ASM_FUNCTION_EPILOGUE} to emit assembly code for the epilogue.

 The @code{epilogue} pattern is particularly useful for targets which perform
 instruction scheduling or which have delay slots for their return instruction.

 @cindex @code{sibcall_epilogue} instruction pattern
 @item @samp{sibcall_epilogue}
 This pattern, if defined, emits RTL for exit from a function without the final
 branch back to the calling function.  This pattern will be emitted before any
 sibling call (aka tail call) sites.

 The @code{sibcall_epilogue} pattern must not clobber any arguments used for
 parameter passing or any stack slots for arguments passed to the current
 function.

 @cindex @code{trap} instruction pattern
 @item @samp{trap}
 This pattern, if defined, signals an error, typically by causing some
 kind of signal to be raised.

 @cindex @code{ctrap@var{MM}4} instruction pattern
 @item @samp{ctrap@var{MM}4}
 Conditional trap instruction.  Operand 0 is a piece of RTL which
 performs a comparison, and operands 1 and 2 are the arms of the
 comparison.  Operand 3 is the trap code, an integer.

 A typical @code{ctrap} pattern looks like

 @smallexample
 (define_insn "ctrapsi4"
   [(trap_if (match_operator 0 "trap_operator"
              [(match_operand 1 "register_operand")
               (match_operand 2 "immediate_operand")])
             (match_operand 3 "const_int_operand" "i"))]
   ""
   "@dots{}")
 @end smallexample

 @cindex @code{prefetch} instruction pattern
 @item @samp{prefetch}
 This pattern, if defined, emits code for a non-faulting data prefetch
 instruction.  Operand 0 is the address of the memory to prefetch.  Operand 1
 is a constant 1 if the prefetch is preparing for a write to the memory
 address, or a constant 0 otherwise.  Operand 2 is the expected degree of
 temporal locality of the data and is a value between 0 and 3, inclusive; 0
 means that the data has no temporal locality, so it need not be left in the
 cache after the access; 3 means that the data has a high degree of temporal
 locality and should be left in all levels of cache possible;  1 and 2 mean,
 respectively, a low or moderate degree of temporal locality.

 Targets that do not support write prefetches or locality hints can ignore
 the values of operands 1 and 2.

 @cindex @code{blockage} instruction pattern
 @item @samp{blockage}
 This pattern defines a pseudo insn that prevents the instruction
 scheduler and other passes from moving instructions and using register
 equivalences across the boundary defined by the blockage insn.
 This needs to be an UNSPEC_VOLATILE pattern or a volatile ASM.

 @cindex @code{memory_blockage} instruction pattern
 @item @samp{memory_blockage}
 This pattern, if defined, represents a compiler memory barrier, and will be
 placed at points across which RTL passes may not propagate memory accesses.
 This instruction needs to read and write volatile BLKmode memory.  It does
 not need to generate any machine instruction.  If this pattern is not defined,
 the compiler falls back to emitting an instruction corresponding
 to @code{asm volatile ("" ::: "memory")}.

 @cindex @code{memory_barrier} instruction pattern
 @item @samp{memory_barrier}
 If the target memory model is not fully synchronous, then this pattern
 should be defined to an instruction that orders both loads and stores
 before the instruction with respect to loads and stores after the instruction.
 This pattern has no operands.

 @cindex @code{speculation_barrier} instruction pattern
 @item @samp{speculation_barrier}
 If the target can support speculative execution, then this pattern should
 be defined to an instruction that will block subsequent execution until
 any prior speculation conditions has been resolved.  The pattern must also
 ensure that the compiler cannot move memory operations past the barrier,
 so it needs to be an UNSPEC_VOLATILE pattern.  The pattern has no
 operands.

 If this pattern is not defined then the default expansion of
 @code{__builtin_speculation_safe_value} will emit a warning.  You can
 suppress this warning by defining this pattern with a final condition
 of @code{0} (zero), which tells the compiler that a speculation
 barrier is not needed for this target.

 @cindex @code{sync_compare_and_swap@var{mode}} instruction pattern
 @item @samp{sync_compare_and_swap@var{mode}}
 This pattern, if defined, emits code for an atomic compare-and-swap
 operation.  Operand 1 is the memory on which the atomic operation is
 performed.  Operand 2 is the ``old'' value to be compared against the
 current contents of the memory location.  Operand 3 is the ``new'' value
 to store in the memory if the compare succeeds.  Operand 0 is the result
 of the operation; it should contain the contents of the memory
 before the operation.  If the compare succeeds, this should obviously be
 a copy of operand 2.

 This pattern must show that both operand 0 and operand 1 are modified.

 This pattern must issue any memory barrier instructions such that all
 memory operations before the atomic operation occur before the atomic
 operation and all memory operations after the atomic operation occur
 after the atomic operation.

 For targets where the success or failure of the compare-and-swap
 operation is available via the status flags, it is possible to
 avoid a separate compare operation and issue the subsequent
 branch or store-flag operation immediately after the compare-and-swap.
 To this end, GCC will look for a @code{MODE_CC} set in the
 output of @code{sync_compare_and_swap@var{mode}}; if the machine
 description includes such a set, the target should also define special
 @code{cbranchcc4} and/or @code{cstorecc4} instructions.  GCC will then
 be able to take the destination of the @code{MODE_CC} set and pass it
 to the @code{cbranchcc4} or @code{cstorecc4} pattern as the first
 operand of the comparison (the second will be @code{(const_int 0)}).

 For targets where the operating system may provide support for this
 operation via library calls, the @code{sync_compare_and_swap_optab}
 may be initialized to a function with the same interface as the
 @code{__sync_val_compare_and_swap_@var{n}} built-in.  If the entire
 set of @var{__sync} builtins are supported via library calls, the
 target can initialize all of the optabs at once with
 @code{init_sync_libfuncs}.
 For the purposes of C++11 @code{std::atomic::is_lock_free}, it is
 assumed that these library calls do @emph{not} use any kind of
 interruptable locking.

 @cindex @code{sync_add@var{mode}} instruction pattern
 @cindex @code{sync_sub@var{mode}} instruction pattern
 @cindex @code{sync_ior@var{mode}} instruction pattern
 @cindex @code{sync_and@var{mode}} instruction pattern
 @cindex @code{sync_xor@var{mode}} instruction pattern
 @cindex @code{sync_nand@var{mode}} instruction pattern
 @item @samp{sync_add@var{mode}}, @samp{sync_sub@var{mode}}
 @itemx @samp{sync_ior@var{mode}}, @samp{sync_and@var{mode}}
 @itemx @samp{sync_xor@var{mode}}, @samp{sync_nand@var{mode}}
 These patterns emit code for an atomic operation on memory.
 Operand 0 is the memory on which the atomic operation is performed.
 Operand 1 is the second operand to the binary operator.

 This pattern must issue any memory barrier instructions such that all
 memory operations before the atomic operation occur before the atomic
 operation and all memory operations after the atomic operation occur
 after the atomic operation.

 If these patterns are not defined, the operation will be constructed
 from a compare-and-swap operation, if defined.

 @cindex @code{sync_old_add@var{mode}} instruction pattern
 @cindex @code{sync_old_sub@var{mode}} instruction pattern
 @cindex @code{sync_old_ior@var{mode}} instruction pattern
 @cindex @code{sync_old_and@var{mode}} instruction pattern
 @cindex @code{sync_old_xor@var{mode}} instruction pattern
 @cindex @code{sync_old_nand@var{mode}} instruction pattern
 @item @samp{sync_old_add@var{mode}}, @samp{sync_old_sub@var{mode}}
 @itemx @samp{sync_old_ior@var{mode}}, @samp{sync_old_and@var{mode}}
 @itemx @samp{sync_old_xor@var{mode}}, @samp{sync_old_nand@var{mode}}
 These patterns emit code for an atomic operation on memory,
 and return the value that the memory contained before the operation.
 Operand 0 is the result value, operand 1 is the memory on which the
 atomic operation is performed, and operand 2 is the second operand
 to the binary operator.

 This pattern must issue any memory barrier instructions such that all
 memory operations before the atomic operation occur before the atomic
 operation and all memory operations after the atomic operation occur
 after the atomic operation.

 If these patterns are not defined, the operation will be constructed
 from a compare-and-swap operation, if defined.

 @cindex @code{sync_new_add@var{mode}} instruction pattern
 @cindex @code{sync_new_sub@var{mode}} instruction pattern
 @cindex @code{sync_new_ior@var{mode}} instruction pattern
 @cindex @code{sync_new_and@var{mode}} instruction pattern
 @cindex @code{sync_new_xor@var{mode}} instruction pattern
 @cindex @code{sync_new_nand@var{mode}} instruction pattern
 @item @samp{sync_new_add@var{mode}}, @samp{sync_new_sub@var{mode}}
 @itemx @samp{sync_new_ior@var{mode}}, @samp{sync_new_and@var{mode}}
 @itemx @samp{sync_new_xor@var{mode}}, @samp{sync_new_nand@var{mode}}
 These patterns are like their @code{sync_old_@var{op}} counterparts,
 except that they return the value that exists in the memory location
 after the operation, rather than before the operation.

 @cindex @code{sync_lock_test_and_set@var{mode}} instruction pattern
 @item @samp{sync_lock_test_and_set@var{mode}}
 This pattern takes two forms, based on the capabilities of the target.
 In either case, operand 0 is the result of the operand, operand 1 is
 the memory on which the atomic operation is performed, and operand 2
 is the value to set in the lock.

 In the ideal case, this operation is an atomic exchange operation, in
 which the previous value in memory operand is copied into the result
 operand, and the value operand is stored in the memory operand.

 For less capable targets, any value operand that is not the constant 1
 should be rejected with @code{FAIL}.  In this case the target may use
 an atomic test-and-set bit operation.  The result operand should contain
 1 if the bit was previously set and 0 if the bit was previously clear.
 The true contents of the memory operand are implementation defined.

 This pattern must issue any memory barrier instructions such that the
 pattern as a whole acts as an acquire barrier, that is all memory
 operations after the pattern do not occur until the lock is acquired.

 If this pattern is not defined, the operation will be constructed from
 a compare-and-swap operation, if defined.

 @cindex @code{sync_lock_release@var{mode}} instruction pattern
 @item @samp{sync_lock_release@var{mode}}
 This pattern, if defined, releases a lock set by
 @code{sync_lock_test_and_set@var{mode}}.  Operand 0 is the memory
 that contains the lock; operand 1 is the value to store in the lock.

 If the target doesn't implement full semantics for
 @code{sync_lock_test_and_set@var{mode}}, any value operand which is not
 the constant 0 should be rejected with @code{FAIL}, and the true contents
 of the memory operand are implementation defined.

 This pattern must issue any memory barrier instructions such that the
 pattern as a whole acts as a release barrier, that is the lock is
 released only after all previous memory operations have completed.

 If this pattern is not defined, then a @code{memory_barrier} pattern
 will be emitted, followed by a store of the value to the memory operand.

 @cindex @code{atomic_compare_and_swap@var{mode}} instruction pattern
 @item @samp{atomic_compare_and_swap@var{mode}}
 This pattern, if defined, emits code for an atomic compare-and-swap
 operation with memory model semantics.  Operand 2 is the memory on which
 the atomic operation is performed.  Operand 0 is an output operand which
 is set to true or false based on whether the operation succeeded.  Operand
 1 is an output operand which is set to the contents of the memory before
 the operation was attempted.  Operand 3 is the value that is expected to
 be in memory.  Operand 4 is the value to put in memory if the expected
 value is found there.  Operand 5 is set to 1 if this compare and swap is to
 be treated as a weak operation.  Operand 6 is the memory model to be used
 if the operation is a success.  Operand 7 is the memory model to be used
 if the operation fails.

 If memory referred to in operand 2 contains the value in operand 3, then
 operand 4 is stored in memory pointed to by operand 2 and fencing based on
 the memory model in operand 6 is issued.

 If memory referred to in operand 2 does not contain the value in operand 3,
 then fencing based on the memory model in operand 7 is issued.

 If a target does not support weak compare-and-swap operations, or the port
 elects not to implement weak operations, the argument in operand 5 can be
 ignored.  Note a strong implementation must be provided.

 If this pattern is not provided, the @code{__atomic_compare_exchange}
 built-in functions will utilize the legacy @code{sync_compare_and_swap}
 pattern with an @code{__ATOMIC_SEQ_CST} memory model.

 @cindex @code{atomic_load@var{mode}} instruction pattern
 @item @samp{atomic_load@var{mode}}
 This pattern implements an atomic load operation with memory model
 semantics.  Operand 1 is the memory address being loaded from.  Operand 0
 is the result of the load.  Operand 2 is the memory model to be used for
 the load operation.

 If not present, the @code{__atomic_load} built-in function will either
 resort to a normal load with memory barriers, or a compare-and-swap
 operation if a normal load would not be atomic.

 @cindex @code{atomic_store@var{mode}} instruction pattern
 @item @samp{atomic_store@var{mode}}
 This pattern implements an atomic store operation with memory model
 semantics.  Operand 0 is the memory address being stored to.  Operand 1
 is the value to be written.  Operand 2 is the memory model to be used for
 the operation.

 If not present, the @code{__atomic_store} built-in function will attempt to
 perform a normal store and surround it with any required memory fences.  If
 the store would not be atomic, then an @code{__atomic_exchange} is
 attempted with the result being ignored.

 @cindex @code{atomic_exchange@var{mode}} instruction pattern
 @item @samp{atomic_exchange@var{mode}}
 This pattern implements an atomic exchange operation with memory model
 semantics.  Operand 1 is the memory location the operation is performed on.
 Operand 0 is an output operand which is set to the original value contained
 in the memory pointed to by operand 1.  Operand 2 is the value to be
 stored.  Operand 3 is the memory model to be used.

 If this pattern is not present, the built-in function
 @code{__atomic_exchange} will attempt to preform the operation with a
 compare and swap loop.

 @cindex @code{atomic_add@var{mode}} instruction pattern
 @cindex @code{atomic_sub@var{mode}} instruction pattern
 @cindex @code{atomic_or@var{mode}} instruction pattern
 @cindex @code{atomic_and@var{mode}} instruction pattern
 @cindex @code{atomic_xor@var{mode}} instruction pattern
 @cindex @code{atomic_nand@var{mode}} instruction pattern
 @item @samp{atomic_add@var{mode}}, @samp{atomic_sub@var{mode}}
 @itemx @samp{atomic_or@var{mode}}, @samp{atomic_and@var{mode}}
 @itemx @samp{atomic_xor@var{mode}}, @samp{atomic_nand@var{mode}}
 These patterns emit code for an atomic operation on memory with memory
 model semantics. Operand 0 is the memory on which the atomic operation is
 performed.  Operand 1 is the second operand to the binary operator.
 Operand 2 is the memory model to be used by the operation.

 If these patterns are not defined, attempts will be made to use legacy
 @code{sync} patterns, or equivalent patterns which return a result.  If
 none of these are available a compare-and-swap loop will be used.

 @cindex @code{atomic_fetch_add@var{mode}} instruction pattern
 @cindex @code{atomic_fetch_sub@var{mode}} instruction pattern
 @cindex @code{atomic_fetch_or@var{mode}} instruction pattern
 @cindex @code{atomic_fetch_and@var{mode}} instruction pattern
 @cindex @code{atomic_fetch_xor@var{mode}} instruction pattern
 @cindex @code{atomic_fetch_nand@var{mode}} instruction pattern
 @item @samp{atomic_fetch_add@var{mode}}, @samp{atomic_fetch_sub@var{mode}}
 @itemx @samp{atomic_fetch_or@var{mode}}, @samp{atomic_fetch_and@var{mode}}
 @itemx @samp{atomic_fetch_xor@var{mode}}, @samp{atomic_fetch_nand@var{mode}}
 These patterns emit code for an atomic operation on memory with memory
 model semantics, and return the original value. Operand 0 is an output
 operand which contains the value of the memory location before the
 operation was performed.  Operand 1 is the memory on which the atomic
 operation is performed.  Operand 2 is the second operand to the binary
 operator.  Operand 3 is the memory model to be used by the operation.

 If these patterns are not defined, attempts will be made to use legacy
 @code{sync} patterns.  If none of these are available a compare-and-swap
 loop will be used.

 @cindex @code{atomic_add_fetch@var{mode}} instruction pattern
 @cindex @code{atomic_sub_fetch@var{mode}} instruction pattern
 @cindex @code{atomic_or_fetch@var{mode}} instruction pattern
 @cindex @code{atomic_and_fetch@var{mode}} instruction pattern
 @cindex @code{atomic_xor_fetch@var{mode}} instruction pattern
 @cindex @code{atomic_nand_fetch@var{mode}} instruction pattern
 @item @samp{atomic_add_fetch@var{mode}}, @samp{atomic_sub_fetch@var{mode}}
 @itemx @samp{atomic_or_fetch@var{mode}}, @samp{atomic_and_fetch@var{mode}}
 @itemx @samp{atomic_xor_fetch@var{mode}}, @samp{atomic_nand_fetch@var{mode}}
 These patterns emit code for an atomic operation on memory with memory
 model semantics and return the result after the operation is performed.
 Operand 0 is an output operand which contains the value after the
 operation.  Operand 1 is the memory on which the atomic operation is
 performed.  Operand 2 is the second operand to the binary operator.
 Operand 3 is the memory model to be used by the operation.

 If these patterns are not defined, attempts will be made to use legacy
 @code{sync} patterns, or equivalent patterns which return the result before
 the operation followed by the arithmetic operation required to produce the
 result.  If none of these are available a compare-and-swap loop will be
 used.

 @cindex @code{atomic_test_and_set} instruction pattern
 @item @samp{atomic_test_and_set}
 This pattern emits code for @code{__builtin_atomic_test_and_set}.
 Operand 0 is an output operand which is set to true if the previous
 previous contents of the byte was "set", and false otherwise.  Operand 1
 is the @code{QImode} memory to be modified.  Operand 2 is the memory
 model to be used.

 The specific value that defines "set" is implementation defined, and
 is normally based on what is performed by the native atomic test and set
 instruction.

 @cindex @code{atomic_bit_test_and_set@var{mode}} instruction pattern
 @cindex @code{atomic_bit_test_and_complement@var{mode}} instruction pattern
 @cindex @code{atomic_bit_test_and_reset@var{mode}} instruction pattern
 @item @samp{atomic_bit_test_and_set@var{mode}}
 @itemx @samp{atomic_bit_test_and_complement@var{mode}}
 @itemx @samp{atomic_bit_test_and_reset@var{mode}}
 These patterns emit code for an atomic bitwise operation on memory with memory
 model semantics, and return the original value of the specified bit.
 Operand 0 is an output operand which contains the value of the specified bit
 from the memory location before the operation was performed.  Operand 1 is the
 memory on which the atomic operation is performed.  Operand 2 is the bit within
 the operand, starting with least significant bit.  Operand 3 is the memory model
 to be used by the operation.  Operand 4 is a flag - it is @code{const1_rtx}
 if operand 0 should contain the original value of the specified bit in the
 least significant bit of the operand, and @code{const0_rtx} if the bit should
 be in its original position in the operand.
 @code{atomic_bit_test_and_set@var{mode}} atomically sets the specified bit after
 remembering its original value, @code{atomic_bit_test_and_complement@var{mode}}
 inverts the specified bit and @code{atomic_bit_test_and_reset@var{mode}} clears
 the specified bit.

 If these patterns are not defined, attempts will be made to use
 @code{atomic_fetch_or@var{mode}}, @code{atomic_fetch_xor@var{mode}} or
 @code{atomic_fetch_and@var{mode}} instruction patterns, or their @code{sync}
 counterparts.  If none of these are available a compare-and-swap
 loop will be used.

 @cindex @code{mem_thread_fence} instruction pattern
 @item @samp{mem_thread_fence}
 This pattern emits code required to implement a thread fence with
 memory model semantics.  Operand 0 is the memory model to be used.

 For the @code{__ATOMIC_RELAXED} model no instructions need to be issued
 and this expansion is not invoked.

 The compiler always emits a compiler memory barrier regardless of what
 expanding this pattern produced.

 If this pattern is not defined, the compiler falls back to expanding the
 @code{memory_barrier} pattern, then to emitting @code{__sync_synchronize}
 library call, and finally to just placing a compiler memory barrier.

 @cindex @code{get_thread_pointer@var{mode}} instruction pattern
 @cindex @code{set_thread_pointer@var{mode}} instruction pattern
 @item @samp{get_thread_pointer@var{mode}}
 @itemx @samp{set_thread_pointer@var{mode}}
 These patterns emit code that reads/sets the TLS thread pointer. Currently,
 these are only needed if the target needs to support the
 @code{__builtin_thread_pointer} and @code{__builtin_set_thread_pointer}
 builtins.

 The get/set patterns have a single output/input operand respectively,
 with @var{mode} intended to be @code{Pmode}.

 @cindex @code{stack_protect_combined_set} instruction pattern
 @item @samp{stack_protect_combined_set}
 This pattern, if defined, moves a @code{ptr_mode} value from an address
 whose declaration RTX is given in operand 1 to the memory in operand 0
 without leaving the value in a register afterward.  If several
 instructions are needed by the target to perform the operation (eg. to
 load the address from a GOT entry then load the @code{ptr_mode} value
 and finally store it), it is the backend's responsibility to ensure no
 intermediate result gets spilled.  This is to avoid leaking the value
 some place that an attacker might use to rewrite the stack guard slot
 after having clobbered it.

 If this pattern is not defined, then the address declaration is
 expanded first in the standard way and a @code{stack_protect_set}
 pattern is then generated to move the value from that address to the
 address in operand 0.

 @cindex @code{stack_protect_set} instruction pattern
 @item @samp{stack_protect_set}
 This pattern, if defined, moves a @code{ptr_mode} value from the valid
 memory location in operand 1 to the memory in operand 0 without leaving
 the value in a register afterward.  This is to avoid leaking the value
 some place that an attacker might use to rewrite the stack guard slot
 after having clobbered it.

 Note: on targets where the addressing modes do not allow to load
 directly from stack guard address, the address is expanded in a standard
 way first which could cause some spills.

 If this pattern is not defined, then a plain move pattern is generated.

 @cindex @code{stack_protect_combined_test} instruction pattern
 @item @samp{stack_protect_combined_test}
 This pattern, if defined, compares a @code{ptr_mode} value from an
 address whose declaration RTX is given in operand 1 with the memory in
 operand 0 without leaving the value in a register afterward and
 branches to operand 2 if the values were equal.  If several
 instructions are needed by the target to perform the operation (eg. to
 load the address from a GOT entry then load the @code{ptr_mode} value
 and finally store it), it is the backend's responsibility to ensure no
 intermediate result gets spilled.  This is to avoid leaking the value
 some place that an attacker might use to rewrite the stack guard slot
 after having clobbered it.

 If this pattern is not defined, then the address declaration is
 expanded first in the standard way and a @code{stack_protect_test}
 pattern is then generated to compare the value from that address to the
 value at the memory in operand 0.

 @cindex @code{stack_protect_test} instruction pattern
 @item @samp{stack_protect_test}
 This pattern, if defined, compares a @code{ptr_mode} value from the
 valid memory location in operand 1 with the memory in operand 0 without
 leaving the value in a register afterward and branches to operand 2 if
 the values were equal.

 If this pattern is not defined, then a plain compare pattern and
 conditional branch pattern is used.

 @cindex @code{clear_cache} instruction pattern
 @item @samp{clear_cache}
 This pattern, if defined, flushes the instruction cache for a region of
 memory.  The region is bounded to by the Pmode pointers in operand 0
 inclusive and operand 1 exclusive.

 If this pattern is not defined, a call to the library function
 @code{__clear_cache} is used.

 @end table

 @end ifset
 @c Each of the following nodes are wrapped in separate
 @c "@ifset INTERNALS" to work around memory limits for the default
 @c configuration in older tetex distributions.  Known to not work:
 @c tetex-1.0.7, known to work: tetex-2.0.2.
 @ifset INTERNALS
 @node Pattern Ordering
 @section When the Order of Patterns Matters
 @cindex Pattern Ordering
 @cindex Ordering of Patterns

 Sometimes an insn can match more than one instruction pattern.  Then the
 pattern that appears first in the machine description is the one used.
 Therefore, more specific patterns (patterns that will match fewer things)
 and faster instructions (those that will produce better code when they
 do match) should usually go first in the description.

 In some cases the effect of ordering the patterns can be used to hide
 a pattern when it is not valid.  For example, the 68000 has an
 instruction for converting a fullword to floating point and another
 for converting a byte to floating point.  An instruction converting
 an integer to floating point could match either one.  We put the
 pattern to convert the fullword first to make sure that one will
 be used rather than the other.  (Otherwise a large integer might
 be generated as a single-byte immediate quantity, which would not work.)
 Instead of using this pattern ordering it would be possible to make the
 pattern for convert-a-byte smart enough to deal properly with any
 constant value.

 @end ifset
 @ifset INTERNALS
 @node Dependent Patterns
 @section Interdependence of Patterns
 @cindex Dependent Patterns
 @cindex Interdependence of Patterns

 In some cases machines support instructions identical except for the
 machine mode of one or more operands.  For example, there may be
 ``sign-extend halfword'' and ``sign-extend byte'' instructions whose
 patterns are

 @smallexample
 (set (match_operand:SI 0 @dots{})
      (extend:SI (match_operand:HI 1 @dots{})))

 (set (match_operand:SI 0 @dots{})
      (extend:SI (match_operand:QI 1 @dots{})))
 @end smallexample

 @noindent
 Constant integers do not specify a machine mode, so an instruction to
 extend a constant value could match either pattern.  The pattern it
 actually will match is the one that appears first in the file.  For correct
 results, this must be the one for the widest possible mode (@code{HImode},
 here).  If the pattern matches the @code{QImode} instruction, the results
 will be incorrect if the constant value does not actually fit that mode.

 Such instructions to extend constants are rarely generated because they are
 optimized away, but they do occasionally happen in nonoptimized
 compilations.

 If a constraint in a pattern allows a constant, the reload pass may
 replace a register with a constant permitted by the constraint in some
 cases.  Similarly for memory references.  Because of this substitution,
 you should not provide separate patterns for increment and decrement
 instructions.  Instead, they should be generated from the same pattern
 that supports register-register add insns by examining the operands and
 generating the appropriate machine instruction.

 @end ifset
 @ifset INTERNALS
 @node Jump Patterns
 @section Defining Jump Instruction Patterns
 @cindex jump instruction patterns
 @cindex defining jump instruction patterns

 GCC does not assume anything about how the machine realizes jumps.
 The machine description should define a single pattern, usually
 a @code{define_expand}, which expands to all the required insns.

 Usually, this would be a comparison insn to set the condition code
 and a separate branch insn testing the condition code and branching
 or not according to its value.  For many machines, however,
 separating compares and branches is limiting, which is why the
 more flexible approach with one @code{define_expand} is used in GCC.
 The machine description becomes clearer for architectures that
 have compare-and-branch instructions but no condition code.  It also
 works better when different sets of comparison operators are supported
 by different kinds of conditional branches (e.g.@: integer vs.@:
 floating-point), or by conditional branches with respect to conditional stores.

 Two separate insns are always used if the machine description represents
 a condition code register using the legacy RTL expression @code{(cc0)},
 and on most machines that use a separate condition code register
 (@pxref{Condition Code}).  For machines that use @code{(cc0)}, in
 fact, the set and use of the condition code must be separate and
 adjacent@footnote{@code{note} insns can separate them, though.}, thus
 allowing flags in @code{cc_status} to be used (@pxref{Condition Code}) and
 so that the comparison and branch insns could be located from each other
 by using the functions @code{prev_cc0_setter} and @code{next_cc0_user}.

 Even in this case having a single entry point for conditional branches
 is advantageous, because it handles equally well the case where a single
 comparison instruction records the results of both signed and unsigned
 comparison of the given operands (with the branch insns coming in distinct
 signed and unsigned flavors) as in the x86 or SPARC, and the case where
 there are distinct signed and unsigned compare instructions and only
 one set of conditional branch instructions as in the PowerPC.

 @end ifset
 @ifset INTERNALS
 @node Looping Patterns
 @section Defining Looping Instruction Patterns
 @cindex looping instruction patterns
 @cindex defining looping instruction patterns

 Some machines have special jump instructions that can be utilized to
 make loops more efficient.  A common example is the 68000 @samp{dbra}
 instruction which performs a decrement of a register and a branch if the
 result was greater than zero.  Other machines, in particular digital
 signal processors (DSPs), have special block repeat instructions to
 provide low-overhead loop support.  For example, the TI TMS320C3x/C4x
 DSPs have a block repeat instruction that loads special registers to
 mark the top and end of a loop and to count the number of loop
 iterations.  This avoids the need for fetching and executing a
 @samp{dbra}-like instruction and avoids pipeline stalls associated with
 the jump.

 GCC has two special named patterns to support low overhead looping.
 They are @samp{doloop_begin} and @samp{doloop_end}.  These are emitted
 by the loop optimizer for certain well-behaved loops with a finite
 number of loop iterations using information collected during strength
 reduction.

 The @samp{doloop_end} pattern describes the actual looping instruction
 (or the implicit looping operation) and the @samp{doloop_begin} pattern
 is an optional companion pattern that can be used for initialization
 needed for some low-overhead looping instructions.

 Note that some machines require the actual looping instruction to be
 emitted at the top of the loop (e.g., the TMS320C3x/C4x DSPs).  Emitting
 the true RTL for a looping instruction at the top of the loop can cause
 problems with flow analysis.  So instead, a dummy @code{doloop} insn is
 emitted at the end of the loop.  The machine dependent reorg pass checks
 for the presence of this @code{doloop} insn and then searches back to
 the top of the loop, where it inserts the true looping insn (provided
 there are no instructions in the loop which would cause problems).  Any
 additional labels can be emitted at this point.  In addition, if the
 desired special iteration counter register was not allocated, this
 machine dependent reorg pass could emit a traditional compare and jump
 instruction pair.

 For the @samp{doloop_end} pattern, the loop optimizer allocates an
 additional pseudo register as an iteration counter.  This pseudo
 register cannot be used within the loop (i.e., general induction
 variables cannot be derived from it), however, in many cases the loop
 induction variable may become redundant and removed by the flow pass.

 The @samp{doloop_end} pattern must have a specific structure to be
 handled correctly by GCC.  The example below is taken (slightly
 simplified) from the PDP-11 target:

 @smallexample
 @group
 (define_expand "doloop_end"
   [(parallel [(set (pc)
                    (if_then_else
                     (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
                         (const_int 1))
                     (label_ref (match_operand 1 "" ""))
                     (pc)))
               (set (match_dup 0)
                    (plus:HI (match_dup 0)
                          (const_int -1)))])]
   ""
   "@{
     if (GET_MODE (operands[0]) != HImode)
       FAIL;
   @}")

 (define_insn "doloop_end_insn"
   [(set (pc)
         (if_then_else
          (ne (match_operand:HI 0 "nonimmediate_operand" "+r,!m")
              (const_int 1))
          (label_ref (match_operand 1 "" ""))
          (pc)))
    (set (match_dup 0)
         (plus:HI (match_dup 0)
               (const_int -1)))]
   ""

   @{
     if (which_alternative == 0)
       return "sob %0,%l1";

     /* emulate sob */
     output_asm_insn ("dec %0", operands);
     return "bne %l1";
   @})
 @end group
 @end smallexample

 The first part of the pattern describes the branch condition.  GCC
 supports three cases for the way the target machine handles the loop
 counter:
 @itemize @bullet
 @item Loop terminates when the loop register decrements to zero.  This
 is represented by a @code{ne} comparison of the register (its old value)
 with constant 1 (as in the example above).
 @item Loop terminates when the loop register decrements to @minus{}1.
 This is represented by a @code{ne} comparison of the register with
 constant zero.
 @item Loop terminates when the loop register decrements to a negative
 value.  This is represented by a @code{ge} comparison of the register
 with constant zero.  For this case, GCC will attach a @code{REG_NONNEG}
 note to the @code{doloop_end} insn if it can determine that the register
 will be non-negative.
 @end itemize

 Since the @code{doloop_end} insn is a jump insn that also has an output,
 the reload pass does not handle the output operand.  Therefore, the
 constraint must allow for that operand to be in memory rather than a
 register.  In the example shown above, that is handled (in the
 @code{doloop_end_insn} pattern) by using a loop instruction sequence
 that can handle memory operands when the memory alternative appears.

 GCC does not check the mode of the loop register operand when generating
 the @code{doloop_end} pattern.  If the pattern is only valid for some
 modes but not others, the pattern should be a @code{define_expand}
 pattern that checks the operand mode in the preparation code, and issues
 @code{FAIL} if an unsupported mode is found.  The example above does
 this, since the machine instruction to be used only exists for
 @code{HImode}.

 If the @code{doloop_end} pattern is a @code{define_expand}, there must
 also be a @code{define_insn} or @code{define_insn_and_split} matching
 the generated pattern.  Otherwise, the compiler will fail during loop
 optimization.

 @end ifset
 @ifset INTERNALS
 @node Insn Canonicalizations
 @section Canonicalization of Instructions
 @cindex canonicalization of instructions
 @cindex insn canonicalization

 There are often cases where multiple RTL expressions could represent an
 operation performed by a single machine instruction.  This situation is
 most commonly encountered with logical, branch, and multiply-accumulate
 instructions.  In such cases, the compiler attempts to convert these
 multiple RTL expressions into a single canonical form to reduce the
 number of insn patterns required.

 In addition to algebraic simplifications, following canonicalizations
 are performed:

 @itemize @bullet
 @item
 For commutative and comparison operators, a constant is always made the
 second operand.  If a machine only supports a constant as the second
 operand, only patterns that match a constant in the second operand need
 be supplied.

 @item
 For associative operators, a sequence of operators will always chain
 to the left; for instance, only the left operand of an integer @code{plus}
 can itself be a @code{plus}.  @code{and}, @code{ior}, @code{xor},
 @code{plus}, @code{mult}, @code{smin}, @code{smax}, @code{umin}, and
 @code{umax} are associative when applied to integers, and sometimes to
 floating-point.

 @item
 @cindex @code{neg}, canonicalization of
 @cindex @code{not}, canonicalization of
 @cindex @code{mult}, canonicalization of
 @cindex @code{plus}, canonicalization of
 @cindex @code{minus}, canonicalization of
 For these operators, if only one operand is a @code{neg}, @code{not},
 @code{mult}, @code{plus}, or @code{minus} expression, it will be the
 first operand.

 @item
 In combinations of @code{neg}, @code{mult}, @code{plus}, and
 @code{minus}, the @code{neg} operations (if any) will be moved inside
 the operations as far as possible.  For instance,
 @code{(neg (mult A B))} is canonicalized as @code{(mult (neg A) B)}, but
 @code{(plus (mult (neg B) C) A)} is canonicalized as
 @code{(minus A (mult B C))}.

 @cindex @code{compare}, canonicalization of
 @item
 For the @code{compare} operator, a constant is always the second operand
 if the first argument is a condition code register or @code{(cc0)}.

 @item
 For instructions that inherently set a condition code register, the
 @code{compare} operator is always written as the first RTL expression of
 the @code{parallel} instruction pattern.  For example,

 @smallexample
 (define_insn ""
   [(set (reg:CCZ FLAGS_REG)
 	(compare:CCZ
 	  (plus:SI
 	    (match_operand:SI 1 "register_operand" "%r")
 	    (match_operand:SI 2 "register_operand" "r"))
 	  (const_int 0)))
    (set (match_operand:SI 0 "register_operand" "=r")
 	(plus:SI (match_dup 1) (match_dup 2)))]
   ""
   "addl %0, %1, %2")
 @end smallexample

 @item
 An operand of @code{neg}, @code{not}, @code{mult}, @code{plus}, or
 @code{minus} is made the first operand under the same conditions as
 above.

 @item
 @code{(ltu (plus @var{a} @var{b}) @var{b})} is converted to
 @code{(ltu (plus @var{a} @var{b}) @var{a})}. Likewise with @code{geu} instead
 of @code{ltu}.

 @item
 @code{(minus @var{x} (const_int @var{n}))} is converted to
 @code{(plus @var{x} (const_int @var{-n}))}.

 @item
 Within address computations (i.e., inside @code{mem}), a left shift is
 converted into the appropriate multiplication by a power of two.

 @cindex @code{ior}, canonicalization of
 @cindex @code{and}, canonicalization of
 @cindex De Morgan's law
 @item
 De Morgan's Law is used to move bitwise negation inside a bitwise
 logical-and or logical-or operation.  If this results in only one
 operand being a @code{not} expression, it will be the first one.

 A machine that has an instruction that performs a bitwise logical-and of one
 operand with the bitwise negation of the other should specify the pattern
 for that instruction as

 @smallexample
 (define_insn ""
   [(set (match_operand:@var{m} 0 @dots{})
         (and:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
                      (match_operand:@var{m} 2 @dots{})))]
   "@dots{}"
   "@dots{}")
 @end smallexample

 @noindent
 Similarly, a pattern for a ``NAND'' instruction should be written

 @smallexample
 (define_insn ""
   [(set (match_operand:@var{m} 0 @dots{})
         (ior:@var{m} (not:@var{m} (match_operand:@var{m} 1 @dots{}))
                      (not:@var{m} (match_operand:@var{m} 2 @dots{}))))]
   "@dots{}"
   "@dots{}")
 @end smallexample

 In both cases, it is not necessary to include patterns for the many
 logically equivalent RTL expressions.

 @cindex @code{xor}, canonicalization of
 @item
 The only possible RTL expressions involving both bitwise exclusive-or
 and bitwise negation are @code{(xor:@var{m} @var{x} @var{y})}
 and @code{(not:@var{m} (xor:@var{m} @var{x} @var{y}))}.

 @item
 The sum of three items, one of which is a constant, will only appear in
 the form

 @smallexample
 (plus:@var{m} (plus:@var{m} @var{x} @var{y}) @var{constant})
 @end smallexample

 @cindex @code{zero_extract}, canonicalization of
 @cindex @code{sign_extract}, canonicalization of
 @item
 Equality comparisons of a group of bits (usually a single bit) with zero
 will be written using @code{zero_extract} rather than the equivalent
 @code{and} or @code{sign_extract} operations.

 @cindex @code{mult}, canonicalization of
 @item
 @code{(sign_extend:@var{m1} (mult:@var{m2} (sign_extend:@var{m2} @var{x})
 (sign_extend:@var{m2} @var{y})))} is converted to @code{(mult:@var{m1}
 (sign_extend:@var{m1} @var{x}) (sign_extend:@var{m1} @var{y}))}, and likewise
 for @code{zero_extend}.

 @item
 @code{(sign_extend:@var{m1} (mult:@var{m2} (ashiftrt:@var{m2}
 @var{x} @var{s}) (sign_extend:@var{m2} @var{y})))} is converted
 to @code{(mult:@var{m1} (sign_extend:@var{m1} (ashiftrt:@var{m2}
 @var{x} @var{s})) (sign_extend:@var{m1} @var{y}))}, and likewise for
 patterns using @code{zero_extend} and @code{lshiftrt}.  If the second
 operand of @code{mult} is also a shift, then that is extended also.
 This transformation is only applied when it can be proven that the
 original operation had sufficient precision to prevent overflow.

 @end itemize

 Further canonicalization rules are defined in the function
 @code{commutative_operand_precedence} in @file{gcc/rtlanal.c}.

 @end ifset
 @ifset INTERNALS
 @node Expander Definitions
 @section Defining RTL Sequences for Code Generation
 @cindex expander definitions
 @cindex code generation RTL sequences
 @cindex defining RTL sequences for code generation

 On some target machines, some standard pattern names for RTL generation
 cannot be handled with single insn, but a sequence of RTL insns can
 represent them.  For these target machines, you can write a
 @code{define_expand} to specify how to generate the sequence of RTL@.

 @findex define_expand
 A @code{define_expand} is an RTL expression that looks almost like a
 @code{define_insn}; but, unlike the latter, a @code{define_expand} is used
 only for RTL generation and it can produce more than one RTL insn.

 A @code{define_expand} RTX has four operands:

 @itemize @bullet
 @item
 The name.  Each @code{define_expand} must have a name, since the only
 use for it is to refer to it by name.

 @item
 The RTL template.  This is a vector of RTL expressions representing
 a sequence of separate instructions.  Unlike @code{define_insn}, there
 is no implicit surrounding @code{PARALLEL}.

 @item
 The condition, a string containing a C expression.  This expression is
 used to express how the availability of this pattern depends on
 subclasses of target machine, selected by command-line options when GCC
 is run.  This is just like the condition of a @code{define_insn} that
 has a standard name.  Therefore, the condition (if present) may not
 depend on the data in the insn being matched, but only the
 target-machine-type flags.  The compiler needs to test these conditions
 during initialization in order to learn exactly which named instructions
 are available in a particular run.

 @item
 The preparation statements, a string containing zero or more C
 statements which are to be executed before RTL code is generated from
 the RTL template.

 Usually these statements prepare temporary registers for use as
 internal operands in the RTL template, but they can also generate RTL
 insns directly by calling routines such as @code{emit_insn}, etc.
 Any such insns precede the ones that come from the RTL template.

 @item
 Optionally, a vector containing the values of attributes. @xref{Insn
 Attributes}.
 @end itemize

 Every RTL insn emitted by a @code{define_expand} must match some
 @code{define_insn} in the machine description.  Otherwise, the compiler
 will crash when trying to generate code for the insn or trying to optimize
 it.

 The RTL template, in addition to controlling generation of RTL insns,
 also describes the operands that need to be specified when this pattern
 is used.  In particular, it gives a predicate for each operand.

 A true operand, which needs to be specified in order to generate RTL from
 the pattern, should be described with a @code{match_operand} in its first
 occurrence in the RTL template.  This enters information on the operand's
 predicate into the tables that record such things.  GCC uses the
 information to preload the operand into a register if that is required for
 valid RTL code.  If the operand is referred to more than once, subsequent
 references should use @code{match_dup}.

 The RTL template may also refer to internal ``operands'' which are
 temporary registers or labels used only within the sequence made by the
 @code{define_expand}.  Internal operands are substituted into the RTL
 template with @code{match_dup}, never with @code{match_operand}.  The
 values of the internal operands are not passed in as arguments by the
 compiler when it requests use of this pattern.  Instead, they are computed
 within the pattern, in the preparation statements.  These statements
 compute the values and store them into the appropriate elements of
 @code{operands} so that @code{match_dup} can find them.

 There are two special macros defined for use in the preparation statements:
 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
 as a statement.

 @table @code

 @findex DONE
 @item DONE
 Use the @code{DONE} macro to end RTL generation for the pattern.  The
 only RTL insns resulting from the pattern on this occasion will be
 those already emitted by explicit calls to @code{emit_insn} within the
 preparation statements; the RTL template will not be generated.

 @findex FAIL
 @item FAIL
 Make the pattern fail on this occasion.  When a pattern fails, it means
 that the pattern was not truly available.  The calling routines in the
 compiler will try other strategies for code generation using other patterns.

 Failure is currently supported only for binary (addition, multiplication,
 shifting, etc.) and bit-field (@code{extv}, @code{extzv}, and @code{insv})
 operations.
 @end table

 If the preparation falls through (invokes neither @code{DONE} nor
 @code{FAIL}), then the @code{define_expand} acts like a
 @code{define_insn} in that the RTL template is used to generate the
 insn.

 The RTL template is not used for matching, only for generating the
 initial insn list.  If the preparation statement always invokes
 @code{DONE} or @code{FAIL}, the RTL template may be reduced to a simple
 list of operands, such as this example:

 @smallexample
 @group
 (define_expand "addsi3"
   [(match_operand:SI 0 "register_operand" "")
    (match_operand:SI 1 "register_operand" "")
    (match_operand:SI 2 "register_operand" "")]
 @end group
 @group
   ""
   "
 @{
   handle_add (operands[0], operands[1], operands[2]);
   DONE;
 @}")
 @end group
 @end smallexample

 Here is an example, the definition of left-shift for the SPUR chip:

 @smallexample
 @group
 (define_expand "ashlsi3"
   [(set (match_operand:SI 0 "register_operand" "")
         (ashift:SI
 @end group
 @group
           (match_operand:SI 1 "register_operand" "")
           (match_operand:SI 2 "nonmemory_operand" "")))]
   ""
   "
 @end group
 @end smallexample

 @smallexample
 @group
 @{
   if (GET_CODE (operands[2]) != CONST_INT
       || (unsigned) INTVAL (operands[2]) > 3)
     FAIL;
 @}")
 @end group
 @end smallexample

 @noindent
 This example uses @code{define_expand} so that it can generate an RTL insn
 for shifting when the shift-count is in the supported range of 0 to 3 but
 fail in other cases where machine insns aren't available.  When it fails,
 the compiler tries another strategy using different patterns (such as, a
 library call).

 If the compiler were able to handle nontrivial condition-strings in
 patterns with names, then it would be possible to use a
 @code{define_insn} in that case.  Here is another case (zero-extension
 on the 68000) which makes more use of the power of @code{define_expand}:

 @smallexample
 (define_expand "zero_extendhisi2"
   [(set (match_operand:SI 0 "general_operand" "")
         (const_int 0))
    (set (strict_low_part
           (subreg:HI
             (match_dup 0)
             0))
         (match_operand:HI 1 "general_operand" ""))]
   ""
   "operands[1] = make_safe_from (operands[1], operands[0]);")
 @end smallexample

 @noindent
 @findex make_safe_from
 Here two RTL insns are generated, one to clear the entire output operand
 and the other to copy the input operand into its low half.  This sequence
 is incorrect if the input operand refers to [the old value of] the output
 operand, so the preparation statement makes sure this isn't so.  The
 function @code{make_safe_from} copies the @code{operands[1]} into a
 temporary register if it refers to @code{operands[0]}.  It does this
 by emitting another RTL insn.

 Finally, a third example shows the use of an internal operand.
 Zero-extension on the SPUR chip is done by @code{and}-ing the result
 against a halfword mask.  But this mask cannot be represented by a
 @code{const_int} because the constant value is too large to be legitimate
 on this machine.  So it must be copied into a register with
 @code{force_reg} and then the register used in the @code{and}.

 @smallexample
 (define_expand "zero_extendhisi2"
   [(set (match_operand:SI 0 "register_operand" "")
         (and:SI (subreg:SI
                   (match_operand:HI 1 "register_operand" "")
                   0)
                 (match_dup 2)))]
   ""
   "operands[2]
      = force_reg (SImode, GEN_INT (65535)); ")
 @end smallexample

 @emph{Note:} If the @code{define_expand} is used to serve a
 standard binary or unary arithmetic operation or a bit-field operation,
 then the last insn it generates must not be a @code{code_label},
 @code{barrier} or @code{note}.  It must be an @code{insn},
 @code{jump_insn} or @code{call_insn}.  If you don't need a real insn
 at the end, emit an insn to copy the result of the operation into
 itself.  Such an insn will generate no code, but it can avoid problems
 in the compiler.

 @end ifset
 @ifset INTERNALS
 @node Insn Splitting
 @section Defining How to Split Instructions
 @cindex insn splitting
 @cindex instruction splitting
 @cindex splitting instructions

 There are two cases where you should specify how to split a pattern
 into multiple insns.  On machines that have instructions requiring
 delay slots (@pxref{Delay Slots}) or that have instructions whose
 output is not available for multiple cycles (@pxref{Processor pipeline
 description}), the compiler phases that optimize these cases need to
 be able to move insns into one-instruction delay slots.  However, some
 insns may generate more than one machine instruction.  These insns
 cannot be placed into a delay slot.

 Often you can rewrite the single insn as a list of individual insns,
 each corresponding to one machine instruction.  The disadvantage of
 doing so is that it will cause the compilation to be slower and require
 more space.  If the resulting insns are too complex, it may also
 suppress some optimizations.  The compiler splits the insn if there is a
 reason to believe that it might improve instruction or delay slot
 scheduling.

 The insn combiner phase also splits putative insns.  If three insns are
 merged into one insn with a complex expression that cannot be matched by
 some @code{define_insn} pattern, the combiner phase attempts to split
 the complex pattern into two insns that are recognized.  Usually it can
 break the complex pattern into two patterns by splitting out some
 subexpression.  However, in some other cases, such as performing an
 addition of a large constant in two insns on a RISC machine, the way to
 split the addition into two insns is machine-dependent.

 @findex define_split
 The @code{define_split} definition tells the compiler how to split a
 complex insn into several simpler insns.  It looks like this:

 @smallexample
 (define_split
   [@var{insn-pattern}]
   "@var{condition}"
   [@var{new-insn-pattern-1}
    @var{new-insn-pattern-2}
    @dots{}]
   "@var{preparation-statements}")
 @end smallexample

 @var{insn-pattern} is a pattern that needs to be split and
 @var{condition} is the final condition to be tested, as in a
 @code{define_insn}.  When an insn matching @var{insn-pattern} and
 satisfying @var{condition} is found, it is replaced in the insn list
 with the insns given by @var{new-insn-pattern-1},
 @var{new-insn-pattern-2}, etc.

 The @var{preparation-statements} are similar to those statements that
 are specified for @code{define_expand} (@pxref{Expander Definitions})
 and are executed before the new RTL is generated to prepare for the
 generated code or emit some insns whose pattern is not fixed.  Unlike
 those in @code{define_expand}, however, these statements must not
 generate any new pseudo-registers.  Once reload has completed, they also
 must not allocate any space in the stack frame.

 There are two special macros defined for use in the preparation statements:
 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
 as a statement.

 @table @code

 @findex DONE
 @item DONE
 Use the @code{DONE} macro to end RTL generation for the splitter.  The
 only RTL insns generated as replacement for the matched input insn will
 be those already emitted by explicit calls to @code{emit_insn} within
 the preparation statements; the replacement pattern is not used.

 @findex FAIL
 @item FAIL
 Make the @code{define_split} fail on this occasion.  When a @code{define_split}
 fails, it means that the splitter was not truly available for the inputs
 it was given, and the input insn will not be split.
 @end table

 If the preparation falls through (invokes neither @code{DONE} nor
 @code{FAIL}), then the @code{define_split} uses the replacement
 template.

 Patterns are matched against @var{insn-pattern} in two different
 circumstances.  If an insn needs to be split for delay slot scheduling
 or insn scheduling, the insn is already known to be valid, which means
 that it must have been matched by some @code{define_insn} and, if
 @code{reload_completed} is nonzero, is known to satisfy the constraints
 of that @code{define_insn}.  In that case, the new insn patterns must
 also be insns that are matched by some @code{define_insn} and, if
 @code{reload_completed} is nonzero, must also satisfy the constraints
 of those definitions.

 As an example of this usage of @code{define_split}, consider the following
 example from @file{a29k.md}, which splits a @code{sign_extend} from
 @code{HImode} to @code{SImode} into a pair of shift insns:

 @smallexample
 (define_split
   [(set (match_operand:SI 0 "gen_reg_operand" "")
         (sign_extend:SI (match_operand:HI 1 "gen_reg_operand" "")))]
   ""
   [(set (match_dup 0)
         (ashift:SI (match_dup 1)
                    (const_int 16)))
    (set (match_dup 0)
         (ashiftrt:SI (match_dup 0)
                      (const_int 16)))]
   "
 @{ operands[1] = gen_lowpart (SImode, operands[1]); @}")
 @end smallexample

 When the combiner phase tries to split an insn pattern, it is always the
 case that the pattern is @emph{not} matched by any @code{define_insn}.
 The combiner pass first tries to split a single @code{set} expression
 and then the same @code{set} expression inside a @code{parallel}, but
 followed by a @code{clobber} of a pseudo-reg to use as a scratch
 register.  In these cases, the combiner expects exactly two new insn
 patterns to be generated.  It will verify that these patterns match some
 @code{define_insn} definitions, so you need not do this test in the
 @code{define_split} (of course, there is no point in writing a
 @code{define_split} that will never produce insns that match).

 Here is an example of this use of @code{define_split}, taken from
 @file{rs6000.md}:

 @smallexample
 (define_split
   [(set (match_operand:SI 0 "gen_reg_operand" "")
         (plus:SI (match_operand:SI 1 "gen_reg_operand" "")
                  (match_operand:SI 2 "non_add_cint_operand" "")))]
   ""
   [(set (match_dup 0) (plus:SI (match_dup 1) (match_dup 3)))
    (set (match_dup 0) (plus:SI (match_dup 0) (match_dup 4)))]
 "
 @{
   int low = INTVAL (operands[2]) & 0xffff;
   int high = (unsigned) INTVAL (operands[2]) >> 16;

   if (low & 0x8000)
     high++, low |= 0xffff0000;

   operands[3] = GEN_INT (high << 16);
   operands[4] = GEN_INT (low);
 @}")
 @end smallexample

 Here the predicate @code{non_add_cint_operand} matches any
 @code{const_int} that is @emph{not} a valid operand of a single add
 insn.  The add with the smaller displacement is written so that it
 can be substituted into the address of a subsequent operation.

 An example that uses a scratch register, from the same file, generates
 an equality comparison of a register and a large constant:

 @smallexample
 (define_split
   [(set (match_operand:CC 0 "cc_reg_operand" "")
         (compare:CC (match_operand:SI 1 "gen_reg_operand" "")
                     (match_operand:SI 2 "non_short_cint_operand" "")))
    (clobber (match_operand:SI 3 "gen_reg_operand" ""))]
   "find_single_use (operands[0], insn, 0)
    && (GET_CODE (*find_single_use (operands[0], insn, 0)) == EQ
        || GET_CODE (*find_single_use (operands[0], insn, 0)) == NE)"
   [(set (match_dup 3) (xor:SI (match_dup 1) (match_dup 4)))
    (set (match_dup 0) (compare:CC (match_dup 3) (match_dup 5)))]
   "
 @{
   /* @r{Get the constant we are comparing against, C, and see what it
      looks like sign-extended to 16 bits.  Then see what constant
      could be XOR'ed with C to get the sign-extended value.}  */

   int c = INTVAL (operands[2]);
   int sextc = (c << 16) >> 16;
   int xorv = c ^ sextc;

   operands[4] = GEN_INT (xorv);
   operands[5] = GEN_INT (sextc);
 @}")
 @end smallexample

 To avoid confusion, don't write a single @code{define_split} that
 accepts some insns that match some @code{define_insn} as well as some
 insns that don't.  Instead, write two separate @code{define_split}
 definitions, one for the insns that are valid and one for the insns that
 are not valid.

 The splitter is allowed to split jump instructions into sequence of
 jumps or create new jumps in while splitting non-jump instructions.  As
 the control flow graph and branch prediction information needs to be updated,
 several restriction apply.

 Splitting of jump instruction into sequence that over by another jump
 instruction is always valid, as compiler expect identical behavior of new
 jump.  When new sequence contains multiple jump instructions or new labels,
 more assistance is needed.  Splitter is required to create only unconditional
 jumps, or simple conditional jump instructions.  Additionally it must attach a
 @code{REG_BR_PROB} note to each conditional jump.  A global variable
 @code{split_branch_probability} holds the probability of the original branch in case
 it was a simple conditional jump, @minus{}1 otherwise.  To simplify
 recomputing of edge frequencies, the new sequence is required to have only
 forward jumps to the newly created labels.

 @findex define_insn_and_split
 For the common case where the pattern of a define_split exactly matches the
 pattern of a define_insn, use @code{define_insn_and_split}.  It looks like
 this:

 @smallexample
 (define_insn_and_split
   [@var{insn-pattern}]
   "@var{condition}"
   "@var{output-template}"
   "@var{split-condition}"
   [@var{new-insn-pattern-1}
    @var{new-insn-pattern-2}
    @dots{}]
   "@var{preparation-statements}"
   [@var{insn-attributes}])

 @end smallexample

 @var{insn-pattern}, @var{condition}, @var{output-template}, and
 @var{insn-attributes} are used as in @code{define_insn}.  The
 @var{new-insn-pattern} vector and the @var{preparation-statements} are used as
 in a @code{define_split}.  The @var{split-condition} is also used as in
 @code{define_split}, with the additional behavior that if the condition starts
 with @samp{&&}, the condition used for the split will be the constructed as a
 logical ``and'' of the split condition with the insn condition.  For example,
 from i386.md:

 @smallexample
 (define_insn_and_split "zero_extendhisi2_and"
   [(set (match_operand:SI 0 "register_operand" "=r")
      (zero_extend:SI (match_operand:HI 1 "register_operand" "0")))
    (clobber (reg:CC 17))]
   "TARGET_ZERO_EXTEND_WITH_AND && !optimize_size"
   "#"
   "&& reload_completed"
   [(parallel [(set (match_dup 0)
                    (and:SI (match_dup 0) (const_int 65535)))
               (clobber (reg:CC 17))])]
   ""
   [(set_attr "type" "alu1")])

 @end smallexample

 In this case, the actual split condition will be
 @samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.

 The @code{define_insn_and_split} construction provides exactly the same
 functionality as two separate @code{define_insn} and @code{define_split}
 patterns.  It exists for compactness, and as a maintenance tool to prevent
 having to ensure the two patterns' templates match.

 @end ifset
 @ifset INTERNALS
 @node Including Patterns
 @section Including Patterns in Machine Descriptions.
 @cindex insn includes

 @findex include
 The @code{include} pattern tells the compiler tools where to
 look for patterns that are in files other than in the file
 @file{.md}.  This is used only at build time and there is no preprocessing allowed.

 It looks like:

 @smallexample

 (include
   @var{pathname})
 @end smallexample

 For example:

 @smallexample

 (include "filestuff")

 @end smallexample

 Where @var{pathname} is a string that specifies the location of the file,
 specifies the include file to be in @file{gcc/config/target/filestuff}.  The
 directory @file{gcc/config/target} is regarded as the default directory.


 Machine descriptions may be split up into smaller more manageable subsections
 and placed into subdirectories.

 By specifying:

 @smallexample

 (include "BOGUS/filestuff")

 @end smallexample

 the include file is specified to be in @file{gcc/config/@var{target}/BOGUS/filestuff}.

 Specifying an absolute path for the include file such as;
 @smallexample

 (include "/u2/BOGUS/filestuff")

 @end smallexample
 is permitted but is not encouraged.

 @subsection RTL Generation Tool Options for Directory Search
 @cindex directory options .md
 @cindex options, directory search
 @cindex search options

 The @option{-I@var{dir}} option specifies directories to search for machine descriptions.
 For example:

 @smallexample

 genrecog -I/p1/abc/proc1 -I/p2/abcd/pro2 target.md

 @end smallexample


 Add the directory @var{dir} to the head of the list of directories to be
 searched for header files.  This can be used to override a system machine definition
 file, substituting your own version, since these directories are
 searched before the default machine description file directories.  If you use more than
 one @option{-I} option, the directories are scanned in left-to-right
 order; the standard default directory come after.


 @end ifset
 @ifset INTERNALS
 @node Peephole Definitions
 @section Machine-Specific Peephole Optimizers
 @cindex peephole optimizer definitions
 @cindex defining peephole optimizers

 In addition to instruction patterns the @file{md} file may contain
 definitions of machine-specific peephole optimizations.

 The combiner does not notice certain peephole optimizations when the data
 flow in the program does not suggest that it should try them.  For example,
 sometimes two consecutive insns related in purpose can be combined even
 though the second one does not appear to use a register computed in the
 first one.  A machine-specific peephole optimizer can detect such
 opportunities.

 There are two forms of peephole definitions that may be used.  The
 original @code{define_peephole} is run at assembly output time to
 match insns and substitute assembly text.  Use of @code{define_peephole}
 is deprecated.

 A newer @code{define_peephole2} matches insns and substitutes new
 insns.  The @code{peephole2} pass is run after register allocation
 but before scheduling, which may result in much better code for
 targets that do scheduling.

 @menu
 * define_peephole::     RTL to Text Peephole Optimizers
 * define_peephole2::    RTL to RTL Peephole Optimizers
 @end menu

 @end ifset
 @ifset INTERNALS
 @node define_peephole
 @subsection RTL to Text Peephole Optimizers
 @findex define_peephole

 @need 1000
 A definition looks like this:

 @smallexample
 (define_peephole
   [@var{insn-pattern-1}
    @var{insn-pattern-2}
    @dots{}]
   "@var{condition}"
   "@var{template}"
   "@var{optional-insn-attributes}")
 @end smallexample

 @noindent
 The last string operand may be omitted if you are not using any
 machine-specific information in this machine description.  If present,
 it must obey the same rules as in a @code{define_insn}.

 In this skeleton, @var{insn-pattern-1} and so on are patterns to match
 consecutive insns.  The optimization applies to a sequence of insns when
 @var{insn-pattern-1} matches the first one, @var{insn-pattern-2} matches
 the next, and so on.

 Each of the insns matched by a peephole must also match a
 @code{define_insn}.  Peepholes are checked only at the last stage just
 before code generation, and only optionally.  Therefore, any insn which
 would match a peephole but no @code{define_insn} will cause a crash in code
 generation in an unoptimized compilation, or at various optimization
 stages.

 The operands of the insns are matched with @code{match_operands},
 @code{match_operator}, and @code{match_dup}, as usual.  What is not
 usual is that the operand numbers apply to all the insn patterns in the
 definition.  So, you can check for identical operands in two insns by
 using @code{match_operand} in one insn and @code{match_dup} in the
 other.

 The operand constraints used in @code{match_operand} patterns do not have
 any direct effect on the applicability of the peephole, but they will
 be validated afterward, so make sure your constraints are general enough
 to apply whenever the peephole matches.  If the peephole matches
 but the constraints are not satisfied, the compiler will crash.

 It is safe to omit constraints in all the operands of the peephole; or
 you can write constraints which serve as a double-check on the criteria
 previously tested.

 Once a sequence of insns matches the patterns, the @var{condition} is
 checked.  This is a C expression which makes the final decision whether to
 perform the optimization (we do so if the expression is nonzero).  If
 @var{condition} is omitted (in other words, the string is empty) then the
 optimization is applied to every sequence of insns that matches the
 patterns.

 The defined peephole optimizations are applied after register allocation
 is complete.  Therefore, the peephole definition can check which
 operands have ended up in which kinds of registers, just by looking at
 the operands.

 @findex prev_active_insn
 The way to refer to the operands in @var{condition} is to write
 @code{operands[@var{i}]} for operand number @var{i} (as matched by
 @code{(match_operand @var{i} @dots{})}).  Use the variable @code{insn}
 to refer to the last of the insns being matched; use
 @code{prev_active_insn} to find the preceding insns.

 @findex dead_or_set_p
 When optimizing computations with intermediate results, you can use
 @var{condition} to match only when the intermediate results are not used
 elsewhere.  Use the C expression @code{dead_or_set_p (@var{insn},
 @var{op})}, where @var{insn} is the insn in which you expect the value
 to be used for the last time (from the value of @code{insn}, together
 with use of @code{prev_nonnote_insn}), and @var{op} is the intermediate
 value (from @code{operands[@var{i}]}).

 Applying the optimization means replacing the sequence of insns with one
 new insn.  The @var{template} controls ultimate output of assembler code
 for this combined insn.  It works exactly like the template of a
 @code{define_insn}.  Operand numbers in this template are the same ones
 used in matching the original sequence of insns.

 The result of a defined peephole optimizer does not need to match any of
 the insn patterns in the machine description; it does not even have an
 opportunity to match them.  The peephole optimizer definition itself serves
 as the insn pattern to control how the insn is output.

 Defined peephole optimizers are run as assembler code is being output,
 so the insns they produce are never combined or rearranged in any way.

 Here is an example, taken from the 68000 machine description:

 @smallexample
 (define_peephole
   [(set (reg:SI 15) (plus:SI (reg:SI 15) (const_int 4)))
    (set (match_operand:DF 0 "register_operand" "=f")
         (match_operand:DF 1 "register_operand" "ad"))]
   "FP_REG_P (operands[0]) && ! FP_REG_P (operands[1])"
 @{
   rtx xoperands[2];
   xoperands[1] = gen_rtx_REG (SImode, REGNO (operands[1]) + 1);
 #ifdef MOTOROLA
   output_asm_insn ("move.l %1,(sp)", xoperands);
   output_asm_insn ("move.l %1,-(sp)", operands);
   return "fmove.d (sp)+,%0";
 #else
   output_asm_insn ("movel %1,sp@@", xoperands);
   output_asm_insn ("movel %1,sp@@-", operands);
   return "fmoved sp@@+,%0";
 #endif
 @})
 @end smallexample

 @need 1000
 The effect of this optimization is to change

 @smallexample
 @group
 jbsr _foobar
 addql #4,sp
 movel d1,sp@@-
 movel d0,sp@@-
 fmoved sp@@+,fp0
 @end group
 @end smallexample

 @noindent
 into

 @smallexample
 @group
 jbsr _foobar
 movel d1,sp@@
 movel d0,sp@@-
 fmoved sp@@+,fp0
 @end group
 @end smallexample

 @ignore
 @findex CC_REVERSED
 If a peephole matches a sequence including one or more jump insns, you must
 take account of the flags such as @code{CC_REVERSED} which specify that the
 condition codes are represented in an unusual manner.  The compiler
 automatically alters any ordinary conditional jumps which occur in such
 situations, but the compiler cannot alter jumps which have been replaced by
 peephole optimizations.  So it is up to you to alter the assembler code
 that the peephole produces.  Supply C code to write the assembler output,
 and in this C code check the condition code status flags and change the
 assembler code as appropriate.
 @end ignore

 @var{insn-pattern-1} and so on look @emph{almost} like the second
 operand of @code{define_insn}.  There is one important difference: the
 second operand of @code{define_insn} consists of one or more RTX's
 enclosed in square brackets.  Usually, there is only one: then the same
 action can be written as an element of a @code{define_peephole}.  But
 when there are multiple actions in a @code{define_insn}, they are
 implicitly enclosed in a @code{parallel}.  Then you must explicitly
 write the @code{parallel}, and the square brackets within it, in the
 @code{define_peephole}.  Thus, if an insn pattern looks like this,

 @smallexample
 (define_insn "divmodsi4"
   [(set (match_operand:SI 0 "general_operand" "=d")
         (div:SI (match_operand:SI 1 "general_operand" "0")
                 (match_operand:SI 2 "general_operand" "dmsK")))
    (set (match_operand:SI 3 "general_operand" "=d")
         (mod:SI (match_dup 1) (match_dup 2)))]
   "TARGET_68020"
   "divsl%.l %2,%3:%0")
 @end smallexample

 @noindent
 then the way to mention this insn in a peephole is as follows:

 @smallexample
 (define_peephole
   [@dots{}
    (parallel
     [(set (match_operand:SI 0 "general_operand" "=d")
           (div:SI (match_operand:SI 1 "general_operand" "0")
                   (match_operand:SI 2 "general_operand" "dmsK")))
      (set (match_operand:SI 3 "general_operand" "=d")
           (mod:SI (match_dup 1) (match_dup 2)))])
    @dots{}]
   @dots{})
 @end smallexample

 @end ifset
 @ifset INTERNALS
 @node define_peephole2
 @subsection RTL to RTL Peephole Optimizers
 @findex define_peephole2

 The @code{define_peephole2} definition tells the compiler how to
 substitute one sequence of instructions for another sequence,
 what additional scratch registers may be needed and what their
 lifetimes must be.

 @smallexample
 (define_peephole2
   [@var{insn-pattern-1}
    @var{insn-pattern-2}
    @dots{}]
   "@var{condition}"
   [@var{new-insn-pattern-1}
    @var{new-insn-pattern-2}
    @dots{}]
   "@var{preparation-statements}")
 @end smallexample

 The definition is almost identical to @code{define_split}
 (@pxref{Insn Splitting}) except that the pattern to match is not a
 single instruction, but a sequence of instructions.

 It is possible to request additional scratch registers for use in the
 output template.  If appropriate registers are not free, the pattern
 will simply not match.

 @findex match_scratch
 @findex match_dup
 Scratch registers are requested with a @code{match_scratch} pattern at
 the top level of the input pattern.  The allocated register (initially) will
 be dead at the point requested within the original sequence.  If the scratch
 is used at more than a single point, a @code{match_dup} pattern at the
 top level of the input pattern marks the last position in the input sequence
 at which the register must be available.

 Here is an example from the IA-32 machine description:

 @smallexample
 (define_peephole2
   [(match_scratch:SI 2 "r")
    (parallel [(set (match_operand:SI 0 "register_operand" "")
                    (match_operator:SI 3 "arith_or_logical_operator"
                      [(match_dup 0)
                       (match_operand:SI 1 "memory_operand" "")]))
               (clobber (reg:CC 17))])]
   "! optimize_size && ! TARGET_READ_MODIFY"
   [(set (match_dup 2) (match_dup 1))
    (parallel [(set (match_dup 0)
                    (match_op_dup 3 [(match_dup 0) (match_dup 2)]))
               (clobber (reg:CC 17))])]
   "")
 @end smallexample

 @noindent
 This pattern tries to split a load from its use in the hopes that we'll be
 able to schedule around the memory load latency.  It allocates a single
 @code{SImode} register of class @code{GENERAL_REGS} (@code{"r"}) that needs
 to be live only at the point just before the arithmetic.

 A real example requiring extended scratch lifetimes is harder to come by,
 so here's a silly made-up example:

 @smallexample
 (define_peephole2
   [(match_scratch:SI 4 "r")
    (set (match_operand:SI 0 "" "") (match_operand:SI 1 "" ""))
    (set (match_operand:SI 2 "" "") (match_dup 1))
    (match_dup 4)
    (set (match_operand:SI 3 "" "") (match_dup 1))]
   "/* @r{determine 1 does not overlap 0 and 2} */"
   [(set (match_dup 4) (match_dup 1))
    (set (match_dup 0) (match_dup 4))
    (set (match_dup 2) (match_dup 4))
    (set (match_dup 3) (match_dup 4))]
   "")
 @end smallexample

 There are two special macros defined for use in the preparation statements:
 @code{DONE} and @code{FAIL}.  Use them with a following semicolon,
 as a statement.

 @table @code

 @findex DONE
 @item DONE
 Use the @code{DONE} macro to end RTL generation for the peephole.  The
 only RTL insns generated as replacement for the matched input insn will
 be those already emitted by explicit calls to @code{emit_insn} within
 the preparation statements; the replacement pattern is not used.

 @findex FAIL
 @item FAIL
 Make the @code{define_peephole2} fail on this occasion.  When a @code{define_peephole2}
 fails, it means that the replacement was not truly available for the
 particular inputs it was given.  In that case, GCC may still apply a
 later @code{define_peephole2} that also matches the given insn pattern.
 (Note that this is different from @code{define_split}, where @code{FAIL}
 prevents the input insn from being split at all.)
 @end table

 If the preparation falls through (invokes neither @code{DONE} nor
 @code{FAIL}), then the @code{define_peephole2} uses the replacement
 template.

 @noindent
 If we had not added the @code{(match_dup 4)} in the middle of the input
 sequence, it might have been the case that the register we chose at the
 beginning of the sequence is killed by the first or second @code{set}.

 @end ifset
 @ifset INTERNALS
 @node Insn Attributes
 @section Instruction Attributes
 @cindex insn attributes
 @cindex instruction attributes

 In addition to describing the instruction supported by the target machine,
 the @file{md} file also defines a group of @dfn{attributes} and a set of
 values for each.  Every generated insn is assigned a value for each attribute.
 One possible attribute would be the effect that the insn has on the machine's
 condition code.  This attribute can then be used by @code{NOTICE_UPDATE_CC}
 to track the condition codes.

 @menu
 * Defining Attributes:: Specifying attributes and their values.
 * Expressions::         Valid expressions for attribute values.
 * Tagging Insns::       Assigning attribute values to insns.
 * Attr Example::        An example of assigning attributes.
 * Insn Lengths::        Computing the length of insns.
 * Constant Attributes:: Defining attributes that are constant.
 * Mnemonic Attribute::  Obtain the instruction mnemonic as attribute value.
 * Delay Slots::         Defining delay slots required for a machine.
 * Processor pipeline description:: Specifying information for insn scheduling.
 @end menu

 @end ifset
 @ifset INTERNALS
 @node Defining Attributes
 @subsection Defining Attributes and their Values
 @cindex defining attributes and their values
 @cindex attributes, defining

 @findex define_attr
 The @code{define_attr} expression is used to define each attribute required
 by the target machine.  It looks like:

 @smallexample
 (define_attr @var{name} @var{list-of-values} @var{default})
 @end smallexample

 @var{name} is a string specifying the name of the attribute being
 defined.  Some attributes are used in a special way by the rest of the
 compiler. The @code{enabled} attribute can be used to conditionally
 enable or disable insn alternatives (@pxref{Disable Insn
 Alternatives}). The @code{predicable} attribute, together with a
 suitable @code{define_cond_exec} (@pxref{Conditional Execution}), can
 be used to automatically generate conditional variants of instruction
 patterns. The @code{mnemonic} attribute can be used to check for the
 instruction mnemonic (@pxref{Mnemonic Attribute}).  The compiler
 internally uses the names @code{ce_enabled} and @code{nonce_enabled},
 so they should not be used elsewhere as alternative names.

 @var{list-of-values} is either a string that specifies a comma-separated
 list of values that can be assigned to the attribute, or a null string to
 indicate that the attribute takes numeric values.

 @var{default} is an attribute expression that gives the value of this
 attribute for insns that match patterns whose definition does not include
 an explicit value for this attribute.  @xref{Attr Example}, for more
 information on the handling of defaults.  @xref{Constant Attributes},
 for information on attributes that do not depend on any particular insn.

 @findex insn-attr.h
 For each defined attribute, a number of definitions are written to the
 @file{insn-attr.h} file.  For cases where an explicit set of values is
 specified for an attribute, the following are defined:

 @itemize @bullet
 @item
 A @samp{#define} is written for the symbol @samp{HAVE_ATTR_@var{name}}.

 @item
 An enumerated class is defined for @samp{attr_@var{name}} with
 elements of the form @samp{@var{upper-name}_@var{upper-value}} where
 the attribute name and value are first converted to uppercase.

 @item
 A function @samp{get_attr_@var{name}} is defined that is passed an insn and
 returns the attribute value for that insn.
 @end itemize

 For example, if the following is present in the @file{md} file:

 @smallexample
 (define_attr "type" "branch,fp,load,store,arith" @dots{})
 @end smallexample

 @noindent
 the following lines will be written to the file @file{insn-attr.h}.

 @smallexample
 #define HAVE_ATTR_type 1
 enum attr_type @{TYPE_BRANCH, TYPE_FP, TYPE_LOAD,
                  TYPE_STORE, TYPE_ARITH@};
 extern enum attr_type get_attr_type ();
 @end smallexample

 If the attribute takes numeric values, no @code{enum} type will be
 defined and the function to obtain the attribute's value will return
 @code{int}.

 There are attributes which are tied to a specific meaning.  These
 attributes are not free to use for other purposes:

 @table @code
 @item length
 The @code{length} attribute is used to calculate the length of emitted
 code chunks.  This is especially important when verifying branch
 distances. @xref{Insn Lengths}.

 @item enabled
 The @code{enabled} attribute can be defined to prevent certain
 alternatives of an insn definition from being used during code
 generation. @xref{Disable Insn Alternatives}.

 @item mnemonic
 The @code{mnemonic} attribute can be defined to implement instruction
 specific checks in e.g.@: the pipeline description.
 @xref{Mnemonic Attribute}.
 @end table

 For each of these special attributes, the corresponding
 @samp{HAVE_ATTR_@var{name}} @samp{#define} is also written when the
 attribute is not defined; in that case, it is defined as @samp{0}.

 @findex define_enum_attr
 @anchor{define_enum_attr}
 Another way of defining an attribute is to use:

 @smallexample
 (define_enum_attr "@var{attr}" "@var{enum}" @var{default})
 @end smallexample

 This works in just the same way as @code{define_attr}, except that
 the list of values is taken from a separate enumeration called
 @var{enum} (@pxref{define_enum}).  This form allows you to use
 the same list of values for several attributes without having to
 repeat the list each time.  For example:

 @smallexample
 (define_enum "processor" [
   model_a
   model_b
   @dots{}
 ])
 (define_enum_attr "arch" "processor"
   (const (symbol_ref "target_arch")))
 (define_enum_attr "tune" "processor"
   (const (symbol_ref "target_tune")))
 @end smallexample

 defines the same attributes as:

 @smallexample
 (define_attr "arch" "model_a,model_b,@dots{}"
   (const (symbol_ref "target_arch")))
 (define_attr "tune" "model_a,model_b,@dots{}"
   (const (symbol_ref "target_tune")))
 @end smallexample

 but without duplicating the processor list.  The second example defines two
 separate C enums (@code{attr_arch} and @code{attr_tune}) whereas the first
 defines a single C enum (@code{processor}).
 @end ifset
 @ifset INTERNALS
 @node Expressions
 @subsection Attribute Expressions
 @cindex attribute expressions

 RTL expressions used to define attributes use the codes described above
 plus a few specific to attribute definitions, to be discussed below.
 Attribute value expressions must have one of the following forms:

 @table @code
 @cindex @code{const_int} and attributes
 @item (const_int @var{i})
 The integer @var{i} specifies the value of a numeric attribute.  @var{i}
 must be non-negative.

 The value of a numeric attribute can be specified either with a
 @code{const_int}, or as an integer represented as a string in
 @code{const_string}, @code{eq_attr} (see below), @code{attr},
 @code{symbol_ref}, simple arithmetic expressions, and @code{set_attr}
 overrides on specific instructions (@pxref{Tagging Insns}).

 @cindex @code{const_string} and attributes
 @item (const_string @var{value})
 The string @var{value} specifies a constant attribute value.
 If @var{value} is specified as @samp{"*"}, it means that the default value of
 the attribute is to be used for the insn containing this expression.
 @samp{"*"} obviously cannot be used in the @var{default} expression
 of a @code{define_attr}.

 If the attribute whose value is being specified is numeric, @var{value}
 must be a string containing a non-negative integer (normally
 @code{const_int} would be used in this case).  Otherwise, it must
 contain one of the valid values for the attribute.

 @cindex @code{if_then_else} and attributes
 @item (if_then_else @var{test} @var{true-value} @var{false-value})
 @var{test} specifies an attribute test, whose format is defined below.
 The value of this expression is @var{true-value} if @var{test} is true,
 otherwise it is @var{false-value}.

 @cindex @code{cond} and attributes
 @item (cond [@var{test1} @var{value1} @dots{}] @var{default})
 The first operand of this expression is a vector containing an even
 number of expressions and consisting of pairs of @var{test} and @var{value}
 expressions.  The value of the @code{cond} expression is that of the
 @var{value} corresponding to the first true @var{test} expression.  If
 none of the @var{test} expressions are true, the value of the @code{cond}
 expression is that of the @var{default} expression.
 @end table

 @var{test} expressions can have one of the following forms:

 @table @code
 @cindex @code{const_int} and attribute tests
 @item (const_int @var{i})
 This test is true if @var{i} is nonzero and false otherwise.

 @cindex @code{not} and attributes
 @cindex @code{ior} and attributes
 @cindex @code{and} and attributes
 @item (not @var{test})
 @itemx (ior @var{test1} @var{test2})
 @itemx (and @var{test1} @var{test2})
 These tests are true if the indicated logical function is true.

 @cindex @code{match_operand} and attributes
 @item (match_operand:@var{m} @var{n} @var{pred} @var{constraints})
 This test is true if operand @var{n} of the insn whose attribute value
 is being determined has mode @var{m} (this part of the test is ignored
 if @var{m} is @code{VOIDmode}) and the function specified by the string
 @var{pred} returns a nonzero value when passed operand @var{n} and mode
 @var{m} (this part of the test is ignored if @var{pred} is the null
 string).

 The @var{constraints} operand is ignored and should be the null string.

 @cindex @code{match_test} and attributes
 @item (match_test @var{c-expr})
 The test is true if C expression @var{c-expr} is true.  In non-constant
 attributes, @var{c-expr} has access to the following variables:

 @table @var
 @item insn
 The rtl instruction under test.
 @item which_alternative
 The @code{define_insn} alternative that @var{insn} matches.
 @xref{Output Statement}.
 @item operands
 An array of @var{insn}'s rtl operands.
 @end table

 @var{c-expr} behaves like the condition in a C @code{if} statement,
 so there is no need to explicitly convert the expression into a boolean
 0 or 1 value.  For example, the following two tests are equivalent:

 @smallexample
 (match_test "x & 2")
 (match_test "(x & 2) != 0")
 @end smallexample

 @cindex @code{le} and attributes
 @cindex @code{leu} and attributes
 @cindex @code{lt} and attributes
 @cindex @code{gt} and attributes
 @cindex @code{gtu} and attributes
 @cindex @code{ge} and attributes
 @cindex @code{geu} and attributes
 @cindex @code{ne} and attributes
 @cindex @code{eq} and attributes
 @cindex @code{plus} and attributes
 @cindex @code{minus} and attributes
 @cindex @code{mult} and attributes
 @cindex @code{div} and attributes
 @cindex @code{mod} and attributes
 @cindex @code{abs} and attributes
 @cindex @code{neg} and attributes
 @cindex @code{ashift} and attributes
 @cindex @code{lshiftrt} and attributes
 @cindex @code{ashiftrt} and attributes
 @item (le @var{arith1} @var{arith2})
 @itemx (leu @var{arith1} @var{arith2})
 @itemx (lt @var{arith1} @var{arith2})
 @itemx (ltu @var{arith1} @var{arith2})
 @itemx (gt @var{arith1} @var{arith2})
 @itemx (gtu @var{arith1} @var{arith2})
 @itemx (ge @var{arith1} @var{arith2})
 @itemx (geu @var{arith1} @var{arith2})
 @itemx (ne @var{arith1} @var{arith2})
 @itemx (eq @var{arith1} @var{arith2})
 These tests are true if the indicated comparison of the two arithmetic
 expressions is true.  Arithmetic expressions are formed with
 @code{plus}, @code{minus}, @code{mult}, @code{div}, @code{mod},
 @code{abs}, @code{neg}, @code{and}, @code{ior}, @code{xor}, @code{not},
 @code{ashift}, @code{lshiftrt}, and @code{ashiftrt} expressions.

 @findex get_attr
 @code{const_int} and @code{symbol_ref} are always valid terms (@pxref{Insn
 Lengths},for additional forms).  @code{symbol_ref} is a string
 denoting a C expression that yields an @code{int} when evaluated by the
 @samp{get_attr_@dots{}} routine.  It should normally be a global
 variable.

 @findex eq_attr
 @item (eq_attr @var{name} @var{value})
 @var{name} is a string specifying the name of an attribute.

 @var{value} is a string that is either a valid value for attribute
 @var{name}, a comma-separated list of values, or @samp{!} followed by a
 value or list.  If @var{value} does not begin with a @samp{!}, this
 test is true if the value of the @var{name} attribute of the current
 insn is in the list specified by @var{value}.  If @var{value} begins
 with a @samp{!}, this test is true if the attribute's value is
 @emph{not} in the specified list.

 For example,

 @smallexample
 (eq_attr "type" "load,store")
 @end smallexample

 @noindent
 is equivalent to

 @smallexample
 (ior (eq_attr "type" "load") (eq_attr "type" "store"))
 @end smallexample

 If @var{name} specifies an attribute of @samp{alternative}, it refers to the
 value of the compiler variable @code{which_alternative}
 (@pxref{Output Statement}) and the values must be small integers.  For
 example,

 @smallexample
 (eq_attr "alternative" "2,3")
 @end smallexample

 @noindent
 is equivalent to

 @smallexample
 (ior (eq (symbol_ref "which_alternative") (const_int 2))
      (eq (symbol_ref "which_alternative") (const_int 3)))
 @end smallexample

 Note that, for most attributes, an @code{eq_attr} test is simplified in cases
 where the value of the attribute being tested is known for all insns matching
 a particular pattern.  This is by far the most common case.

 @findex attr_flag
 @item (attr_flag @var{name})
 The value of an @code{attr_flag} expression is true if the flag
 specified by @var{name} is true for the @code{insn} currently being
 scheduled.

 @var{name} is a string specifying one of a fixed set of flags to test.
 Test the flags @code{forward} and @code{backward} to determine the
 direction of a conditional branch.

 This example describes a conditional branch delay slot which
 can be nullified for forward branches that are taken (annul-true) or
 for backward branches which are not taken (annul-false).

 @smallexample
 (define_delay (eq_attr "type" "cbranch")
   [(eq_attr "in_branch_delay" "true")
    (and (eq_attr "in_branch_delay" "true")
         (attr_flag "forward"))
    (and (eq_attr "in_branch_delay" "true")
         (attr_flag "backward"))])
 @end smallexample

 The @code{forward} and @code{backward} flags are false if the current
 @code{insn} being scheduled is not a conditional branch.

 @code{attr_flag} is only used during delay slot scheduling and has no
 meaning to other passes of the compiler.

 @findex attr
 @item (attr @var{name})
 The value of another attribute is returned.  This is most useful
 for numeric attributes, as @code{eq_attr} and @code{attr_flag}
 produce more efficient code for non-numeric attributes.
 @end table

 @end ifset
 @ifset INTERNALS
 @node Tagging Insns
 @subsection Assigning Attribute Values to Insns
 @cindex tagging insns
 @cindex assigning attribute values to insns

 The value assigned to an attribute of an insn is primarily determined by
 which pattern is matched by that insn (or which @code{define_peephole}
 generated it).  Every @code{define_insn} and @code{define_peephole} can
 have an optional last argument to specify the values of attributes for
 matching insns.  The value of any attribute not specified in a particular
 insn is set to the default value for that attribute, as specified in its
 @code{define_attr}.  Extensive use of default values for attributes
 permits the specification of the values for only one or two attributes
 in the definition of most insn patterns, as seen in the example in the
 next section.

 The optional last argument of @code{define_insn} and
 @code{define_peephole} is a vector of expressions, each of which defines
 the value for a single attribute.  The most general way of assigning an
 attribute's value is to use a @code{set} expression whose first operand is an
 @code{attr} expression giving the name of the attribute being set.  The
 second operand of the @code{set} is an attribute expression
 (@pxref{Expressions}) giving the value of the attribute.

 When the attribute value depends on the @samp{alternative} attribute
 (i.e., which is the applicable alternative in the constraint of the
 insn), the @code{set_attr_alternative} expression can be used.  It
 allows the specification of a vector of attribute expressions, one for
 each alternative.

 @findex set_attr
 When the generality of arbitrary attribute expressions is not required,
 the simpler @code{set_attr} expression can be used, which allows
 specifying a string giving either a single attribute value or a list
 of attribute values, one for each alternative.

 The form of each of the above specifications is shown below.  In each case,
 @var{name} is a string specifying the attribute to be set.

 @table @code
 @item (set_attr @var{name} @var{value-string})
 @var{value-string} is either a string giving the desired attribute value,
 or a string containing a comma-separated list giving the values for
 succeeding alternatives.  The number of elements must match the number
 of alternatives in the constraint of the insn pattern.

 Note that it may be useful to specify @samp{*} for some alternative, in
 which case the attribute will assume its default value for insns matching
 that alternative.

 @findex set_attr_alternative
 @item (set_attr_alternative @var{name} [@var{value1} @var{value2} @dots{}])
 Depending on the alternative of the insn, the value will be one of the
 specified values.  This is a shorthand for using a @code{cond} with
 tests on the @samp{alternative} attribute.

 @findex attr
 @item (set (attr @var{name}) @var{value})
 The first operand of this @code{set} must be the special RTL expression
 @code{attr}, whose sole operand is a string giving the name of the
 attribute being set.  @var{value} is the value of the attribute.
 @end table

 The following shows three different ways of representing the same
 attribute value specification:

 @smallexample
 (set_attr "type" "load,store,arith")

 (set_attr_alternative "type"
                       [(const_string "load") (const_string "store")
                        (const_string "arith")])

 (set (attr "type")
      (cond [(eq_attr "alternative" "1") (const_string "load")
             (eq_attr "alternative" "2") (const_string "store")]
            (const_string "arith")))
 @end smallexample

 @need 1000
 @findex define_asm_attributes
 The @code{define_asm_attributes} expression provides a mechanism to
 specify the attributes assigned to insns produced from an @code{asm}
 statement.  It has the form:

 @smallexample
 (define_asm_attributes [@var{attr-sets}])
 @end smallexample

 @noindent
 where @var{attr-sets} is specified the same as for both the
 @code{define_insn} and the @code{define_peephole} expressions.

 These values will typically be the ``worst case'' attribute values.  For
 example, they might indicate that the condition code will be clobbered.

 A specification for a @code{length} attribute is handled specially.  The
 way to compute the length of an @code{asm} insn is to multiply the
 length specified in the expression @code{define_asm_attributes} by the
 number of machine instructions specified in the @code{asm} statement,
 determined by counting the number of semicolons and newlines in the
 string.  Therefore, the value of the @code{length} attribute specified
 in a @code{define_asm_attributes} should be the maximum possible length
 of a single machine instruction.

 @end ifset
 @ifset INTERNALS
 @node Attr Example
 @subsection Example of Attribute Specifications
 @cindex attribute specifications example
 @cindex attribute specifications

 The judicious use of defaulting is important in the efficient use of
 insn attributes.  Typically, insns are divided into @dfn{types} and an
 attribute, customarily called @code{type}, is used to represent this
 value.  This attribute is normally used only to define the default value
 for other attributes.  An example will clarify this usage.

 Assume we have a RISC machine with a condition code and in which only
 full-word operations are performed in registers.  Let us assume that we
 can divide all insns into loads, stores, (integer) arithmetic
 operations, floating point operations, and branches.

 Here we will concern ourselves with determining the effect of an insn on
 the condition code and will limit ourselves to the following possible
 effects:  The condition code can be set unpredictably (clobbered), not
 be changed, be set to agree with the results of the operation, or only
 changed if the item previously set into the condition code has been
 modified.

 Here is part of a sample @file{md} file for such a machine:

 @smallexample
 (define_attr "type" "load,store,arith,fp,branch" (const_string "arith"))

 (define_attr "cc" "clobber,unchanged,set,change0"
              (cond [(eq_attr "type" "load")
                         (const_string "change0")
                     (eq_attr "type" "store,branch")
                         (const_string "unchanged")
                     (eq_attr "type" "arith")
                         (if_then_else (match_operand:SI 0 "" "")
                                       (const_string "set")
                                       (const_string "clobber"))]
                    (const_string "clobber")))

 (define_insn ""
   [(set (match_operand:SI 0 "general_operand" "=r,r,m")
         (match_operand:SI 1 "general_operand" "r,m,r"))]
   ""
   "@@
    move %0,%1
    load %0,%1
    store %0,%1"
   [(set_attr "type" "arith,load,store")])
 @end smallexample

 Note that we assume in the above example that arithmetic operations
 performed on quantities smaller than a machine word clobber the condition
 code since they will set the condition code to a value corresponding to the
 full-word result.

 @end ifset
 @ifset INTERNALS
 @node Insn Lengths
 @subsection Computing the Length of an Insn
 @cindex insn lengths, computing
 @cindex computing the length of an insn

 For many machines, multiple types of branch instructions are provided, each
 for different length branch displacements.  In most cases, the assembler
 will choose the correct instruction to use.  However, when the assembler
 cannot do so, GCC can when a special attribute, the @code{length}
 attribute, is defined.  This attribute must be defined to have numeric
 values by specifying a null string in its @code{define_attr}.

 In the case of the @code{length} attribute, two additional forms of
 arithmetic terms are allowed in test expressions:

 @table @code
 @cindex @code{match_dup} and attributes
 @item (match_dup @var{n})
 This refers to the address of operand @var{n} of the current insn, which
 must be a @code{label_ref}.

 @cindex @code{pc} and attributes
 @item (pc)
 For non-branch instructions and backward branch instructions, this refers
 to the address of the current insn.  But for forward branch instructions,
 this refers to the address of the next insn, because the length of the
 current insn is to be computed.
 @end table

 @cindex @code{addr_vec}, length of
 @cindex @code{addr_diff_vec}, length of
 For normal insns, the length will be determined by value of the
 @code{length} attribute.  In the case of @code{addr_vec} and
 @code{addr_diff_vec} insn patterns, the length is computed as
 the number of vectors multiplied by the size of each vector.

 Lengths are measured in addressable storage units (bytes).

 Note that it is possible to call functions via the @code{symbol_ref}
 mechanism to compute the length of an insn.  However, if you use this
 mechanism you must provide dummy clauses to express the maximum length
 without using the function call.  You can an example of this in the
 @code{pa} machine description for the @code{call_symref} pattern.

 The following macros can be used to refine the length computation:

 @table @code
 @findex ADJUST_INSN_LENGTH
 @item ADJUST_INSN_LENGTH (@var{insn}, @var{length})
 If defined, modifies the length assigned to instruction @var{insn} as a
 function of the context in which it is used.  @var{length} is an lvalue
 that contains the initially computed length of the insn and should be
 updated with the correct length of the insn.

 This macro will normally not be required.  A case in which it is
 required is the ROMP@.  On this machine, the size of an @code{addr_vec}
 insn must be increased by two to compensate for the fact that alignment
 may be required.
 @end table

 @findex get_attr_length
 The routine that returns @code{get_attr_length} (the value of the
 @code{length} attribute) can be used by the output routine to
 determine the form of the branch instruction to be written, as the
 example below illustrates.

 As an example of the specification of variable-length branches, consider
 the IBM 360.  If we adopt the convention that a register will be set to
 the starting address of a function, we can jump to labels within 4k of
 the start using a four-byte instruction.  Otherwise, we need a six-byte
 sequence to load the address from memory and then branch to it.

 On such a machine, a pattern for a branch instruction might be specified
 as follows:

 @smallexample
 (define_insn "jump"
   [(set (pc)
         (label_ref (match_operand 0 "" "")))]
   ""
 @{
    return (get_attr_length (insn) == 4
            ? "b %l0" : "l r15,=a(%l0); br r15");
 @}
   [(set (attr "length")
         (if_then_else (lt (match_dup 0) (const_int 4096))
                       (const_int 4)
                       (const_int 6)))])
 @end smallexample

 @end ifset
 @ifset INTERNALS
 @node Constant Attributes
 @subsection Constant Attributes
 @cindex constant attributes

 A special form of @code{define_attr}, where the expression for the
 default value is a @code{const} expression, indicates an attribute that
 is constant for a given run of the compiler.  Constant attributes may be
 used to specify which variety of processor is used.  For example,

 @smallexample
 (define_attr "cpu" "m88100,m88110,m88000"
  (const
   (cond [(symbol_ref "TARGET_88100") (const_string "m88100")
          (symbol_ref "TARGET_88110") (const_string "m88110")]
         (const_string "m88000"))))

 (define_attr "memory" "fast,slow"
  (const
   (if_then_else (symbol_ref "TARGET_FAST_MEM")
                 (const_string "fast")
                 (const_string "slow"))))
 @end smallexample

 The routine generated for constant attributes has no parameters as it
 does not depend on any particular insn.  RTL expressions used to define
 the value of a constant attribute may use the @code{symbol_ref} form,
 but may not use either the @code{match_operand} form or @code{eq_attr}
 forms involving insn attributes.

 @end ifset
 @ifset INTERNALS
 @node Mnemonic Attribute
 @subsection Mnemonic Attribute
 @cindex mnemonic attribute

 The @code{mnemonic} attribute is a string type attribute holding the
 instruction mnemonic for an insn alternative.  The attribute values
 will automatically be generated by the machine description parser if
 there is an attribute definition in the md file:

 @smallexample
 (define_attr "mnemonic" "unknown" (const_string "unknown"))
 @end smallexample

 The default value can be freely chosen as long as it does not collide
 with any of the instruction mnemonics.  This value will be used
 whenever the machine description parser is not able to determine the
 mnemonic string.  This might be the case for output templates
 containing more than a single instruction as in
 @code{"mvcle\t%0,%1,0\;jo\t.-4"}.

 The @code{mnemonic} attribute set is not generated automatically if the
 instruction string is generated via C code.

 An existing @code{mnemonic} attribute set in an insn definition will not
 be overriden by the md file parser.  That way it is possible to
 manually set the instruction mnemonics for the cases where the md file
 parser fails to determine it automatically.

 The @code{mnemonic} attribute is useful for dealing with instruction
 specific properties in the pipeline description without defining
 additional insn attributes.

 @smallexample
 (define_attr "ooo_expanded" ""
   (cond [(eq_attr "mnemonic" "dlr,dsgr,d,dsgf,stam,dsgfr,dlgr")
          (const_int 1)]
         (const_int 0)))
 @end smallexample

 @end ifset
 @ifset INTERNALS
 @node Delay Slots
 @subsection Delay Slot Scheduling
 @cindex delay slots, defining

 The insn attribute mechanism can be used to specify the requirements for
 delay slots, if any, on a target machine.  An instruction is said to
 require a @dfn{delay slot} if some instructions that are physically
 after the instruction are executed as if they were located before it.
 Classic examples are branch and call instructions, which often execute
 the following instruction before the branch or call is performed.

 On some machines, conditional branch instructions can optionally
 @dfn{annul} instructions in the delay slot.  This means that the
 instruction will not be executed for certain branch outcomes.  Both
 instructions that annul if the branch is true and instructions that
 annul if the branch is false are supported.

 Delay slot scheduling differs from instruction scheduling in that
 determining whether an instruction needs a delay slot is dependent only
 on the type of instruction being generated, not on data flow between the
 instructions.  See the next section for a discussion of data-dependent
 instruction scheduling.

 @findex define_delay
 The requirement of an insn needing one or more delay slots is indicated
 via the @code{define_delay} expression.  It has the following form:

 @smallexample
 (define_delay @var{test}
               [@var{delay-1} @var{annul-true-1} @var{annul-false-1}
                @var{delay-2} @var{annul-true-2} @var{annul-false-2}
                @dots{}])
 @end smallexample

 @var{test} is an attribute test that indicates whether this
 @code{define_delay} applies to a particular insn.  If so, the number of
 required delay slots is determined by the length of the vector specified
 as the second argument.  An insn placed in delay slot @var{n} must
 satisfy attribute test @var{delay-n}.  @var{annul-true-n} is an
 attribute test that specifies which insns may be annulled if the branch
 is true.  Similarly, @var{annul-false-n} specifies which insns in the
 delay slot may be annulled if the branch is false.  If annulling is not
 supported for that delay slot, @code{(nil)} should be coded.

 For example, in the common case where branch and call insns require
 a single delay slot, which may contain any insn other than a branch or
 call, the following would be placed in the @file{md} file:

 @smallexample
 (define_delay (eq_attr "type" "branch,call")
               [(eq_attr "type" "!branch,call") (nil) (nil)])
 @end smallexample

 Multiple @code{define_delay} expressions may be specified.  In this
 case, each such expression specifies different delay slot requirements
 and there must be no insn for which tests in two @code{define_delay}
 expressions are both true.

 For example, if we have a machine that requires one delay slot for branches
 but two for calls,  no delay slot can contain a branch or call insn,
 and any valid insn in the delay slot for the branch can be annulled if the
 branch is true, we might represent this as follows:

 @smallexample
 (define_delay (eq_attr "type" "branch")
    [(eq_attr "type" "!branch,call")
     (eq_attr "type" "!branch,call")
     (nil)])

 (define_delay (eq_attr "type" "call")
               [(eq_attr "type" "!branch,call") (nil) (nil)
                (eq_attr "type" "!branch,call") (nil) (nil)])
 @end smallexample
 @c the above is *still* too long.  --mew 4feb93

 @end ifset
 @ifset INTERNALS
 @node Processor pipeline description
 @subsection Specifying processor pipeline description
 @cindex processor pipeline description
 @cindex processor functional units
 @cindex instruction latency time
 @cindex interlock delays
 @cindex data dependence delays
 @cindex reservation delays
 @cindex pipeline hazard recognizer
 @cindex automaton based pipeline description
 @cindex regular expressions
 @cindex deterministic finite state automaton
 @cindex automaton based scheduler
 @cindex RISC
 @cindex VLIW

 To achieve better performance, most modern processors
 (super-pipelined, superscalar @acronym{RISC}, and @acronym{VLIW}
 processors) have many @dfn{functional units} on which several
 instructions can be executed simultaneously.  An instruction starts
 execution if its issue conditions are satisfied.  If not, the
 instruction is stalled until its conditions are satisfied.  Such
 @dfn{interlock (pipeline) delay} causes interruption of the fetching
 of successor instructions (or demands nop instructions, e.g.@: for some
 MIPS processors).

 There are two major kinds of interlock delays in modern processors.
 The first one is a data dependence delay determining @dfn{instruction
 latency time}.  The instruction execution is not started until all
 source data have been evaluated by prior instructions (there are more
 complex cases when the instruction execution starts even when the data
 are not available but will be ready in given time after the
 instruction execution start).  Taking the data dependence delays into
 account is simple.  The data dependence (true, output, and
 anti-dependence) delay between two instructions is given by a
 constant.  In most cases this approach is adequate.  The second kind
 of interlock delays is a reservation delay.  The reservation delay
 means that two instructions under execution will be in need of shared
 processors resources, i.e.@: buses, internal registers, and/or
 functional units, which are reserved for some time.  Taking this kind
 of delay into account is complex especially for modern @acronym{RISC}
 processors.

 The task of exploiting more processor parallelism is solved by an
 instruction scheduler.  For a better solution to this problem, the
 instruction scheduler has to have an adequate description of the
 processor parallelism (or @dfn{pipeline description}).  GCC
 machine descriptions describe processor parallelism and functional
 unit reservations for groups of instructions with the aid of
 @dfn{regular expressions}.

 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
 figure out the possibility of the instruction issue by the processor
 on a given simulated processor cycle.  The pipeline hazard recognizer is
 automatically generated from the processor pipeline description.  The
 pipeline hazard recognizer generated from the machine description
 is based on a deterministic finite state automaton (@acronym{DFA}):
 the instruction issue is possible if there is a transition from one
 automaton state to another one.  This algorithm is very fast, and
 furthermore, its speed is not dependent on processor
 complexity@footnote{However, the size of the automaton depends on
 processor complexity.  To limit this effect, machine descriptions
 can split orthogonal parts of the machine description among several
 automata: but then, since each of these must be stepped independently,
 this does cause a small decrease in the algorithm's performance.}.

 @cindex automaton based pipeline description
 The rest of this section describes the directives that constitute
 an automaton-based processor pipeline description.  The order of
 these constructions within the machine description file is not
 important.

 @findex define_automaton
 @cindex pipeline hazard recognizer
 The following optional construction describes names of automata
 generated and used for the pipeline hazards recognition.  Sometimes
 the generated finite state automaton used by the pipeline hazard
 recognizer is large.  If we use more than one automaton and bind functional
 units to the automata, the total size of the automata is usually
 less than the size of the single automaton.  If there is no one such
 construction, only one finite state automaton is generated.

 @smallexample
 (define_automaton @var{automata-names})
 @end smallexample

 @var{automata-names} is a string giving names of the automata.  The
 names are separated by commas.  All the automata should have unique names.
 The automaton name is used in the constructions @code{define_cpu_unit} and
 @code{define_query_cpu_unit}.

 @findex define_cpu_unit
 @cindex processor functional units
 Each processor functional unit used in the description of instruction
 reservations should be described by the following construction.

 @smallexample
 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
 @end smallexample

 @var{unit-names} is a string giving the names of the functional units
 separated by commas.  Don't use name @samp{nothing}, it is reserved
 for other goals.

 @var{automaton-name} is a string giving the name of the automaton with
 which the unit is bound.  The automaton should be described in
 construction @code{define_automaton}.  You should give
 @dfn{automaton-name}, if there is a defined automaton.

 The assignment of units to automata are constrained by the uses of the
 units in insn reservations.  The most important constraint is: if a
 unit reservation is present on a particular cycle of an alternative
 for an insn reservation, then some unit from the same automaton must
 be present on the same cycle for the other alternatives of the insn
 reservation.  The rest of the constraints are mentioned in the
 description of the subsequent constructions.

 @findex define_query_cpu_unit
 @cindex querying function unit reservations
 The following construction describes CPU functional units analogously
 to @code{define_cpu_unit}.  The reservation of such units can be
 queried for an automaton state.  The instruction scheduler never
 queries reservation of functional units for given automaton state.  So
 as a rule, you don't need this construction.  This construction could
 be used for future code generation goals (e.g.@: to generate
 @acronym{VLIW} insn templates).

 @smallexample
 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
 @end smallexample

 @var{unit-names} is a string giving names of the functional units
 separated by commas.

 @var{automaton-name} is a string giving the name of the automaton with
 which the unit is bound.

 @findex define_insn_reservation
 @cindex instruction latency time
 @cindex regular expressions
 @cindex data bypass
 The following construction is the major one to describe pipeline
 characteristics of an instruction.

 @smallexample
 (define_insn_reservation @var{insn-name} @var{default_latency}
                          @var{condition} @var{regexp})
 @end smallexample

 @var{default_latency} is a number giving latency time of the
 instruction.  There is an important difference between the old
 description and the automaton based pipeline description.  The latency
 time is used for all dependencies when we use the old description.  In
 the automaton based pipeline description, the given latency time is only
 used for true dependencies.  The cost of anti-dependencies is always
 zero and the cost of output dependencies is the difference between
 latency times of the producing and consuming insns (if the difference
 is negative, the cost is considered to be zero).  You can always
 change the default costs for any description by using the target hook
 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).

 @var{insn-name} is a string giving the internal name of the insn.  The
 internal names are used in constructions @code{define_bypass} and in
 the automaton description file generated for debugging.  The internal
 name has nothing in common with the names in @code{define_insn}.  It is a
 good practice to use insn classes described in the processor manual.

 @var{condition} defines what RTL insns are described by this
 construction.  You should remember that you will be in trouble if
 @var{condition} for two or more different
 @code{define_insn_reservation} constructions is TRUE for an insn.  In
 this case what reservation will be used for the insn is not defined.
 Such cases are not checked during generation of the pipeline hazards
 recognizer because in general recognizing that two conditions may have
 the same value is quite difficult (especially if the conditions
 contain @code{symbol_ref}).  It is also not checked during the
 pipeline hazard recognizer work because it would slow down the
 recognizer considerably.

 @var{regexp} is a string describing the reservation of the cpu's functional
 units by the instruction.  The reservations are described by a regular
 expression according to the following syntax:

 @smallexample
        regexp = regexp "," oneof
               | oneof

        oneof = oneof "|" allof
              | allof

        allof = allof "+" repeat
              | repeat

        repeat = element "*" number
               | element

        element = cpu_function_unit_name
                | reservation_name
                | result_name
                | "nothing"
                | "(" regexp ")"
 @end smallexample

 @itemize @bullet
 @item
 @samp{,} is used for describing the start of the next cycle in
 the reservation.

 @item
 @samp{|} is used for describing a reservation described by the first
 regular expression @strong{or} a reservation described by the second
 regular expression @strong{or} etc.

 @item
 @samp{+} is used for describing a reservation described by the first
 regular expression @strong{and} a reservation described by the
 second regular expression @strong{and} etc.

 @item
 @samp{*} is used for convenience and simply means a sequence in which
 the regular expression are repeated @var{number} times with cycle
 advancing (see @samp{,}).

 @item
 @samp{cpu_function_unit_name} denotes reservation of the named
 functional unit.

 @item
 @samp{reservation_name} --- see description of construction
 @samp{define_reservation}.

 @item
 @samp{nothing} denotes no unit reservations.
 @end itemize

 @findex define_reservation
 Sometimes unit reservations for different insns contain common parts.
 In such case, you can simplify the pipeline description by describing
 the common part by the following construction

 @smallexample
 (define_reservation @var{reservation-name} @var{regexp})
 @end smallexample

 @var{reservation-name} is a string giving name of @var{regexp}.
 Functional unit names and reservation names are in the same name
 space.  So the reservation names should be different from the
 functional unit names and cannot be the reserved name @samp{nothing}.

 @findex define_bypass
 @cindex instruction latency time
 @cindex data bypass
 The following construction is used to describe exceptions in the
 latency time for given instruction pair.  This is so called bypasses.

 @smallexample
 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
                [@var{guard}])
 @end smallexample

 @var{number} defines when the result generated by the instructions
 given in string @var{out_insn_names} will be ready for the
 instructions given in string @var{in_insn_names}.  Each of these
 strings is a comma-separated list of filename-style globs and
 they refer to the names of @code{define_insn_reservation}s.
 For example:
 @smallexample
 (define_bypass 1 "cpu1_load_*, cpu1_store_*" "cpu1_load_*")
 @end smallexample
 defines a bypass between instructions that start with
 @samp{cpu1_load_} or @samp{cpu1_store_} and those that start with
 @samp{cpu1_load_}.

 @var{guard} is an optional string giving the name of a C function which
 defines an additional guard for the bypass.  The function will get the
 two insns as parameters.  If the function returns zero the bypass will
 be ignored for this case.  The additional guard is necessary to
 recognize complicated bypasses, e.g.@: when the consumer is only an address
 of insn @samp{store} (not a stored value).

 If there are more one bypass with the same output and input insns, the
 chosen bypass is the first bypass with a guard in description whose
 guard function returns nonzero.  If there is no such bypass, then
 bypass without the guard function is chosen.

 @findex exclusion_set
 @findex presence_set
 @findex final_presence_set
 @findex absence_set
 @findex final_absence_set
 @cindex VLIW
 @cindex RISC
 The following five constructions are usually used to describe
 @acronym{VLIW} processors, or more precisely, to describe a placement
 of small instructions into @acronym{VLIW} instruction slots.  They
 can be used for @acronym{RISC} processors, too.

 @smallexample
 (exclusion_set @var{unit-names} @var{unit-names})
 (presence_set @var{unit-names} @var{patterns})
 (final_presence_set @var{unit-names} @var{patterns})
 (absence_set @var{unit-names} @var{patterns})
 (final_absence_set @var{unit-names} @var{patterns})
 @end smallexample

 @var{unit-names} is a string giving names of functional units
 separated by commas.

 @var{patterns} is a string giving patterns of functional units
 separated by comma.  Currently pattern is one unit or units
 separated by white-spaces.

 The first construction (@samp{exclusion_set}) means that each
 functional unit in the first string cannot be reserved simultaneously
 with a unit whose name is in the second string and vice versa.  For
 example, the construction is useful for describing processors
 (e.g.@: some SPARC processors) with a fully pipelined floating point
 functional unit which can execute simultaneously only single floating
 point insns or only double floating point insns.

 The second construction (@samp{presence_set}) means that each
 functional unit in the first string cannot be reserved unless at
 least one of pattern of units whose names are in the second string is
 reserved.  This is an asymmetric relation.  For example, it is useful
 for description that @acronym{VLIW} @samp{slot1} is reserved after
 @samp{slot0} reservation.  We could describe it by the following
 construction

 @smallexample
 (presence_set "slot1" "slot0")
 @end smallexample

 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
 reservation.  In this case we could write

 @smallexample
 (presence_set "slot1" "slot0 b0")
 @end smallexample

 The third construction (@samp{final_presence_set}) is analogous to
 @samp{presence_set}.  The difference between them is when checking is
 done.  When an instruction is issued in given automaton state
 reflecting all current and planned unit reservations, the automaton
 state is changed.  The first state is a source state, the second one
 is a result state.  Checking for @samp{presence_set} is done on the
 source state reservation, checking for @samp{final_presence_set} is
 done on the result reservation.  This construction is useful to
 describe a reservation which is actually two subsequent reservations.
 For example, if we use

 @smallexample
 (presence_set "slot1" "slot0")
 @end smallexample

 the following insn will be never issued (because @samp{slot1} requires
 @samp{slot0} which is absent in the source state).

 @smallexample
 (define_reservation "insn_and_nop" "slot0 + slot1")
 @end smallexample

 but it can be issued if we use analogous @samp{final_presence_set}.

 The forth construction (@samp{absence_set}) means that each functional
 unit in the first string can be reserved only if each pattern of units
 whose names are in the second string is not reserved.  This is an
 asymmetric relation (actually @samp{exclusion_set} is analogous to
 this one but it is symmetric).  For example it might be useful in a
 @acronym{VLIW} description to say that @samp{slot0} cannot be reserved
 after either @samp{slot1} or @samp{slot2} have been reserved.  This
 can be described as:

 @smallexample
 (absence_set "slot0" "slot1, slot2")
 @end smallexample

 Or @samp{slot2} cannot be reserved if @samp{slot0} and unit @samp{b0}
 are reserved or @samp{slot1} and unit @samp{b1} are reserved.  In
 this case we could write

 @smallexample
 (absence_set "slot2" "slot0 b0, slot1 b1")
 @end smallexample

 All functional units mentioned in a set should belong to the same
 automaton.

 The last construction (@samp{final_absence_set}) is analogous to
 @samp{absence_set} but checking is done on the result (state)
 reservation.  See comments for @samp{final_presence_set}.

 @findex automata_option
 @cindex deterministic finite state automaton
 @cindex nondeterministic finite state automaton
 @cindex finite state automaton minimization
 You can control the generator of the pipeline hazard recognizer with
 the following construction.

 @smallexample
 (automata_option @var{options})
 @end smallexample

 @var{options} is a string giving options which affect the generated
 code.  Currently there are the following options:

 @itemize @bullet
 @item
 @dfn{no-minimization} makes no minimization of the automaton.  This is
 only worth to do when we are debugging the description and need to
 look more accurately at reservations of states.

 @item
 @dfn{time} means printing time statistics about the generation of
 automata.

 @item
 @dfn{stats} means printing statistics about the generated automata
 such as the number of DFA states, NDFA states and arcs.

 @item
 @dfn{v} means a generation of the file describing the result automata.
 The file has suffix @samp{.dfa} and can be used for the description
 verification and debugging.

 @item
 @dfn{w} means a generation of warning instead of error for
 non-critical errors.

 @item
 @dfn{no-comb-vect} prevents the automaton generator from generating
 two data structures and comparing them for space efficiency.  Using
 a comb vector to represent transitions may be better, but it can be
 very expensive to construct.  This option is useful if the build
 process spends an unacceptably long time in genautomata.

 @item
 @dfn{ndfa} makes nondeterministic finite state automata.  This affects
 the treatment of operator @samp{|} in the regular expressions.  The
 usual treatment of the operator is to try the first alternative and,
 if the reservation is not possible, the second alternative.  The
 nondeterministic treatment means trying all alternatives, some of them
 may be rejected by reservations in the subsequent insns.

 @item
 @dfn{collapse-ndfa} modifies the behavior of the generator when
 producing an automaton.  An additional state transition to collapse a
 nondeterministic @acronym{NDFA} state to a deterministic @acronym{DFA}
 state is generated.  It can be triggered by passing @code{const0_rtx} to
 state_transition.  In such an automaton, cycle advance transitions are
 available only for these collapsed states.  This option is useful for
 ports that want to use the @code{ndfa} option, but also want to use
 @code{define_query_cpu_unit} to assign units to insns issued in a cycle.

 @item
 @dfn{progress} means output of a progress bar showing how many states
 were generated so far for automaton being processed.  This is useful
 during debugging a @acronym{DFA} description.  If you see too many
 generated states, you could interrupt the generator of the pipeline
 hazard recognizer and try to figure out a reason for generation of the
 huge automaton.
 @end itemize

 As an example, consider a superscalar @acronym{RISC} machine which can
 issue three insns (two integer insns and one floating point insn) on
 the cycle but can finish only two insns.  To describe this, we define
 the following functional units.

 @smallexample
 (define_cpu_unit "i0_pipeline, i1_pipeline, f_pipeline")
 (define_cpu_unit "port0, port1")
 @end smallexample

 All simple integer insns can be executed in any integer pipeline and
 their result is ready in two cycles.  The simple integer insns are
 issued into the first pipeline unless it is reserved, otherwise they
 are issued into the second pipeline.  Integer division and
 multiplication insns can be executed only in the second integer
 pipeline and their results are ready correspondingly in 9 and 4
 cycles.  The integer division is not pipelined, i.e.@: the subsequent
 integer division insn cannot be issued until the current division
 insn finished.  Floating point insns are fully pipelined and their
 results are ready in 3 cycles.  Where the result of a floating point
 insn is used by an integer insn, an additional delay of one cycle is
 incurred.  To describe all of this we could specify

 @smallexample
 (define_cpu_unit "div")

 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
                          "(i0_pipeline | i1_pipeline), (port0 | port1)")

 (define_insn_reservation "mult" 4 (eq_attr "type" "mult")
                          "i1_pipeline, nothing*2, (port0 | port1)")

 (define_insn_reservation "div" 9 (eq_attr "type" "div")
                          "i1_pipeline, div*7, div + (port0 | port1)")

 (define_insn_reservation "float" 3 (eq_attr "type" "float")
                          "f_pipeline, nothing, (port0 | port1))

 (define_bypass 4 "float" "simple,mult,div")
 @end smallexample

 To simplify the description we could describe the following reservation

 @smallexample
 (define_reservation "finish" "port0|port1")
 @end smallexample

 and use it in all @code{define_insn_reservation} as in the following
 construction

 @smallexample
 (define_insn_reservation "simple" 2 (eq_attr "type" "int")
                          "(i0_pipeline | i1_pipeline), finish")
 @end smallexample


 @end ifset
 @ifset INTERNALS
 @node Conditional Execution
 @section Conditional Execution
 @cindex conditional execution
 @cindex predication

 A number of architectures provide for some form of conditional
 execution, or predication.  The hallmark of this feature is the
 ability to nullify most of the instructions in the instruction set.
 When the instruction set is large and not entirely symmetric, it
 can be quite tedious to describe these forms directly in the
 @file{.md} file.  An alternative is the @code{define_cond_exec} template.

 @findex define_cond_exec
 @smallexample
 (define_cond_exec
   [@var{predicate-pattern}]
   "@var{condition}"
   "@var{output-template}"
   "@var{optional-insn-attribues}")
 @end smallexample

 @var{predicate-pattern} is the condition that must be true for the
 insn to be executed at runtime and should match a relational operator.
 One can use @code{match_operator} to match several relational operators
 at once.  Any @code{match_operand} operands must have no more than one
 alternative.

 @var{condition} is a C expression that must be true for the generated
 pattern to match.

 @findex current_insn_predicate
 @var{output-template} is a string similar to the @code{define_insn}
 output template (@pxref{Output Template}), except that the @samp{*}
 and @samp{@@} special cases do not apply.  This is only useful if the
 assembly text for the predicate is a simple prefix to the main insn.
 In order to handle the general case, there is a global variable
 @code{current_insn_predicate} that will contain the entire predicate
 if the current insn is predicated, and will otherwise be @code{NULL}.

 @var{optional-insn-attributes} is an optional vector of attributes that gets
 appended to the insn attributes of the produced cond_exec rtx. It can
 be used to add some distinguishing attribute to cond_exec rtxs produced
 that way. An example usage would be to use this attribute in conjunction
 with attributes on the main pattern to disable particular alternatives under
 certain conditions.

 When @code{define_cond_exec} is used, an implicit reference to
 the @code{predicable} instruction attribute is made.
 @xref{Insn Attributes}.  This attribute must be a boolean (i.e.@: have
 exactly two elements in its @var{list-of-values}), with the possible
 values being @code{no} and @code{yes}.  The default and all uses in
 the insns must be a simple constant, not a complex expressions.  It
 may, however, depend on the alternative, by using a comma-separated
 list of values.  If that is the case, the port should also define an
 @code{enabled} attribute (@pxref{Disable Insn Alternatives}), which
 should also allow only @code{no} and @code{yes} as its values.

 For each @code{define_insn} for which the @code{predicable}
 attribute is true, a new @code{define_insn} pattern will be
 generated that matches a predicated version of the instruction.
 For example,

 @smallexample
 (define_insn "addsi"
   [(set (match_operand:SI 0 "register_operand" "r")
         (plus:SI (match_operand:SI 1 "register_operand" "r")
                  (match_operand:SI 2 "register_operand" "r")))]
   "@var{test1}"
   "add %2,%1,%0")

 (define_cond_exec
   [(ne (match_operand:CC 0 "register_operand" "c")
        (const_int 0))]
   "@var{test2}"
   "(%0)")
 @end smallexample

 @noindent
 generates a new pattern

 @smallexample
 (define_insn ""
   [(cond_exec
      (ne (match_operand:CC 3 "register_operand" "c") (const_int 0))
      (set (match_operand:SI 0 "register_operand" "r")
           (plus:SI (match_operand:SI 1 "register_operand" "r")
                    (match_operand:SI 2 "register_operand" "r"))))]
   "(@var{test2}) && (@var{test1})"
   "(%3) add %2,%1,%0")
 @end smallexample

 @end ifset
 @ifset INTERNALS
 @node Define Subst
 @section RTL Templates Transformations
 @cindex define_subst

 For some hardware architectures there are common cases when the RTL
 templates for the instructions can be derived from the other RTL
 templates using simple transformations.  E.g., @file{i386.md} contains
 an RTL template for the ordinary @code{sub} instruction---
 @code{*subsi_1}, and for the @code{sub} instruction with subsequent
 zero-extension---@code{*subsi_1_zext}.  Such cases can be easily
 implemented by a single meta-template capable of generating a modified
 case based on the initial one:

 @findex define_subst
 @smallexample
 (define_subst "@var{name}"
   [@var{input-template}]
   "@var{condition}"
   [@var{output-template}])
 @end smallexample
 @var{input-template} is a pattern describing the source RTL template,
 which will be transformed.

 @var{condition} is a C expression that is conjunct with the condition
 from the input-template to generate a condition to be used in the
 output-template.

 @var{output-template} is a pattern that will be used in the resulting
 template.

 @code{define_subst} mechanism is tightly coupled with the notion of the
 subst attribute (@pxref{Subst Iterators}).  The use of
 @code{define_subst} is triggered by a reference to a subst attribute in
 the transforming RTL template.  This reference initiates duplication of
 the source RTL template and substitution of the attributes with their
 values.  The source RTL template is left unchanged, while the copy is
 transformed by @code{define_subst}.  This transformation can fail in the
 case when the source RTL template is not matched against the
 input-template of the @code{define_subst}.  In such case the copy is
 deleted.

 @code{define_subst} can be used only in @code{define_insn} and
 @code{define_expand}, it cannot be used in other expressions (e.g.@: in
 @code{define_insn_and_split}).

 @menu
 * Define Subst Example::	    Example of @code{define_subst} work.
 * Define Subst Pattern Matching::   Process of template comparison.
 * Define Subst Output Template::    Generation of output template.
 @end menu

 @node Define Subst Example
 @subsection @code{define_subst} Example
 @cindex define_subst

 To illustrate how @code{define_subst} works, let us examine a simple
 template transformation.

 Suppose there are two kinds of instructions: one that touches flags and
 the other that does not.  The instructions of the second type could be
 generated with the following @code{define_subst}:

 @smallexample
 (define_subst "add_clobber_subst"
   [(set (match_operand:SI 0 "" "")
         (match_operand:SI 1 "" ""))]
   ""
   [(set (match_dup 0)
         (match_dup 1))
    (clobber (reg:CC FLAGS_REG))]
 @end smallexample

 This @code{define_subst} can be applied to any RTL pattern containing
 @code{set} of mode SI and generates a copy with clobber when it is
 applied.

 Assume there is an RTL template for a @code{max} instruction to be used
 in @code{define_subst} mentioned above:

 @smallexample
 (define_insn "maxsi"
   [(set (match_operand:SI 0 "register_operand" "=r")
         (max:SI
           (match_operand:SI 1 "register_operand" "r")
           (match_operand:SI 2 "register_operand" "r")))]
   ""
   "max\t@{%2, %1, %0|%0, %1, %2@}"
  [@dots{}])
 @end smallexample

 To mark the RTL template for @code{define_subst} application,
 subst-attributes are used.  They should be declared in advance:

 @smallexample
 (define_subst_attr "add_clobber_name" "add_clobber_subst" "_noclobber" "_clobber")
 @end smallexample

 Here @samp{add_clobber_name} is the attribute name,
 @samp{add_clobber_subst} is the name of the corresponding
 @code{define_subst}, the third argument (@samp{_noclobber}) is the
 attribute value that would be substituted into the unchanged version of
 the source RTL template, and the last argument (@samp{_clobber}) is the
 value that would be substituted into the second, transformed,
 version of the RTL template.

 Once the subst-attribute has been defined, it should be used in RTL
 templates which need to be processed by the @code{define_subst}.  So,
 the original RTL template should be changed:

 @smallexample
 (define_insn "maxsi<add_clobber_name>"
   [(set (match_operand:SI 0 "register_operand" "=r")
         (max:SI
           (match_operand:SI 1 "register_operand" "r")
           (match_operand:SI 2 "register_operand" "r")))]
   ""
   "max\t@{%2, %1, %0|%0, %1, %2@}"
  [@dots{}])
 @end smallexample

 The result of the @code{define_subst} usage would look like the following:

 @smallexample
 (define_insn "maxsi_noclobber"
   [(set (match_operand:SI 0 "register_operand" "=r")
         (max:SI
           (match_operand:SI 1 "register_operand" "r")
           (match_operand:SI 2 "register_operand" "r")))]
   ""
   "max\t@{%2, %1, %0|%0, %1, %2@}"
  [@dots{}])
 (define_insn "maxsi_clobber"
   [(set (match_operand:SI 0 "register_operand" "=r")
         (max:SI
           (match_operand:SI 1 "register_operand" "r")
           (match_operand:SI 2 "register_operand" "r")))
    (clobber (reg:CC FLAGS_REG))]
   ""
   "max\t@{%2, %1, %0|%0, %1, %2@}"
  [@dots{}])
 @end smallexample

 @node Define Subst Pattern Matching
 @subsection Pattern Matching in @code{define_subst}
 @cindex define_subst

 All expressions, allowed in @code{define_insn} or @code{define_expand},
 are allowed in the input-template of @code{define_subst}, except
 @code{match_par_dup}, @code{match_scratch}, @code{match_parallel}. The
 meanings of expressions in the input-template were changed:

 @code{match_operand} matches any expression (possibly, a subtree in
 RTL-template), if modes of the @code{match_operand} and this expression
 are the same, or mode of the @code{match_operand} is @code{VOIDmode}, or
 this expression is @code{match_dup}, @code{match_op_dup}.  If the
 expression is @code{match_operand} too, and predicate of
 @code{match_operand} from the input pattern is not empty, then the
 predicates are compared.  That can be used for more accurate filtering
 of accepted RTL-templates.

 @code{match_operator} matches common operators (like @code{plus},
 @code{minus}), @code{unspec}, @code{unspec_volatile} operators and
 @code{match_operator}s from the original pattern if the modes match and
 @code{match_operator} from the input pattern has the same number of
 operands as the operator from the original pattern.

 @node Define Subst Output Template
 @subsection Generation of output template in @code{define_subst}
 @cindex define_subst

 If all necessary checks for @code{define_subst} application pass, a new
 RTL-pattern, based on the output-template, is created to replace the old
 template.  Like in input-patterns, meanings of some RTL expressions are
 changed when they are used in output-patterns of a @code{define_subst}.
 Thus, @code{match_dup} is used for copying the whole expression from the
 original pattern, which matched corresponding @code{match_operand} from
 the input pattern.

 @code{match_dup N} is used in the output template to be replaced with
 the expression from the original pattern, which matched
 @code{match_operand N} from the input pattern.  As a consequence,
 @code{match_dup} cannot be used to point to @code{match_operand}s from
 the output pattern, it should always refer to a @code{match_operand}
 from the input pattern.  If a @code{match_dup N} occurs more than once
 in the output template, its first occurrence is replaced with the
 expression from the original pattern, and the subsequent expressions
 are replaced with @code{match_dup N}, i.e., a reference to the first
 expression.

 In the output template one can refer to the expressions from the
 original pattern and create new ones.  For instance, some operands could
 be added by means of standard @code{match_operand}.

 After replacing @code{match_dup} with some RTL-subtree from the original
 pattern, it could happen that several @code{match_operand}s in the
 output pattern have the same indexes.  It is unknown, how many and what
 indexes would be used in the expression which would replace
 @code{match_dup}, so such conflicts in indexes are inevitable.  To
 overcome this issue, @code{match_operands} and @code{match_operators},
 which were introduced into the output pattern, are renumerated when all
 @code{match_dup}s are replaced.

 Number of alternatives in @code{match_operand}s introduced into the
 output template @code{M} could differ from the number of alternatives in
 the original pattern @code{N}, so in the resultant pattern there would
 be @code{N*M} alternatives.  Thus, constraints from the original pattern
 would be duplicated @code{N} times, constraints from the output pattern
 would be duplicated @code{M} times, producing all possible combinations.
 @end ifset

 @ifset INTERNALS
 @node Constant Definitions
 @section Constant Definitions
 @cindex constant definitions
 @findex define_constants

 Using literal constants inside instruction patterns reduces legibility and
 can be a maintenance problem.

 To overcome this problem, you may use the @code{define_constants}
 expression.  It contains a vector of name-value pairs.  From that
 point on, wherever any of the names appears in the MD file, it is as
 if the corresponding value had been written instead.  You may use
 @code{define_constants} multiple times; each appearance adds more
 constants to the table.  It is an error to redefine a constant with
 a different value.

 To come back to the a29k load multiple example, instead of

 @smallexample
 (define_insn ""
   [(match_parallel 0 "load_multiple_operation"
      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
            (match_operand:SI 2 "memory_operand" "m"))
       (use (reg:SI 179))
       (clobber (reg:SI 179))])]
   ""
   "loadm 0,0,%1,%2")
 @end smallexample

 You could write:

 @smallexample
 (define_constants [
     (R_BP 177)
     (R_FC 178)
     (R_CR 179)
     (R_Q  180)
 ])

 (define_insn ""
   [(match_parallel 0 "load_multiple_operation"
      [(set (match_operand:SI 1 "gpc_reg_operand" "=r")
            (match_operand:SI 2 "memory_operand" "m"))
       (use (reg:SI R_CR))
       (clobber (reg:SI R_CR))])]
   ""
   "loadm 0,0,%1,%2")
 @end smallexample

 The constants that are defined with a define_constant are also output
 in the insn-codes.h header file as #defines.

 @cindex enumerations
 @findex define_c_enum
 You can also use the machine description file to define enumerations.
 Like the constants defined by @code{define_constant}, these enumerations
 are visible to both the machine description file and the main C code.

 The syntax is as follows:

 @smallexample
 (define_c_enum "@var{name}" [
   @var{value0}
   @var{value1}
   @dots{}
   @var{valuen}
 ])
 @end smallexample

 This definition causes the equivalent of the following C code to appear
 in @file{insn-constants.h}:

 @smallexample
 enum @var{name} @{
   @var{value0} = 0,
   @var{value1} = 1,
   @dots{}
   @var{valuen} = @var{n}
 @};
 #define NUM_@var{cname}_VALUES (@var{n} + 1)
 @end smallexample

 where @var{cname} is the capitalized form of @var{name}.
 It also makes each @var{valuei} available in the machine description
 file, just as if it had been declared with:

 @smallexample
 (define_constants [(@var{valuei} @var{i})])
 @end smallexample

 Each @var{valuei} is usually an upper-case identifier and usually
 begins with @var{cname}.

 You can split the enumeration definition into as many statements as
 you like.  The above example is directly equivalent to:

 @smallexample
 (define_c_enum "@var{name}" [@var{value0}])
 (define_c_enum "@var{name}" [@var{value1}])
 @dots{}
 (define_c_enum "@var{name}" [@var{valuen}])
 @end smallexample

 Splitting the enumeration helps to improve the modularity of each
 individual @code{.md} file.  For example, if a port defines its
 synchronization instructions in a separate @file{sync.md} file,
 it is convenient to define all synchronization-specific enumeration
 values in @file{sync.md} rather than in the main @file{.md} file.

 Some enumeration names have special significance to GCC:

 @table @code
 @item unspecv
 @findex unspec_volatile
 If an enumeration called @code{unspecv} is defined, GCC will use it
 when printing out @code{unspec_volatile} expressions.  For example:

 @smallexample
 (define_c_enum "unspecv" [
   UNSPECV_BLOCKAGE
 ])
 @end smallexample

 causes GCC to print @samp{(unspec_volatile @dots{} 0)} as:

 @smallexample
 (unspec_volatile ... UNSPECV_BLOCKAGE)
 @end smallexample

 @item unspec
 @findex unspec
 If an enumeration called @code{unspec} is defined, GCC will use
 it when printing out @code{unspec} expressions.  GCC will also use
 it when printing out @code{unspec_volatile} expressions unless an
 @code{unspecv} enumeration is also defined.  You can therefore
 decide whether to keep separate enumerations for volatile and
 non-volatile expressions or whether to use the same enumeration
 for both.
 @end table

 @findex define_enum
 @anchor{define_enum}
 Another way of defining an enumeration is to use @code{define_enum}:

 @smallexample
 (define_enum "@var{name}" [
   @var{value0}
   @var{value1}
   @dots{}
   @var{valuen}
 ])
 @end smallexample

 This directive implies:

 @smallexample
 (define_c_enum "@var{name}" [
   @var{cname}_@var{cvalue0}
   @var{cname}_@var{cvalue1}
   @dots{}
   @var{cname}_@var{cvaluen}
 ])
 @end smallexample

 @findex define_enum_attr
 where @var{cvaluei} is the capitalized form of @var{valuei}.
 However, unlike @code{define_c_enum}, the enumerations defined
 by @code{define_enum} can be used in attribute specifications
 (@pxref{define_enum_attr}).
 @end ifset
 @ifset INTERNALS
 @node Iterators
 @section Iterators
 @cindex iterators in @file{.md} files

 Ports often need to define similar patterns for more than one machine
 mode or for more than one rtx code.  GCC provides some simple iterator
 facilities to make this process easier.

 @menu
 * Mode Iterators::         Generating variations of patterns for different modes.
 * Code Iterators::         Doing the same for codes.
 * Int Iterators::          Doing the same for integers.
 * Subst Iterators::	   Generating variations of patterns for define_subst.
 * Parameterized Names::	   Specifying iterator values in C++ code.
 @end menu

 @node Mode Iterators
 @subsection Mode Iterators
 @cindex mode iterators in @file{.md} files

 Ports often need to define similar patterns for two or more different modes.
 For example:

 @itemize @bullet
 @item
 If a processor has hardware support for both single and double
 floating-point arithmetic, the @code{SFmode} patterns tend to be
 very similar to the @code{DFmode} ones.

 @item
 If a port uses @code{SImode} pointers in one configuration and
 @code{DImode} pointers in another, it will usually have very similar
 @code{SImode} and @code{DImode} patterns for manipulating pointers.
 @end itemize

 Mode iterators allow several patterns to be instantiated from one
 @file{.md} file template.  They can be used with any type of
 rtx-based construct, such as a @code{define_insn},
 @code{define_split}, or @code{define_peephole2}.

 @menu
 * Defining Mode Iterators:: Defining a new mode iterator.
 * Substitutions::           Combining mode iterators with substitutions
 * Examples::                Examples
 @end menu

 @node Defining Mode Iterators
 @subsubsection Defining Mode Iterators
 @findex define_mode_iterator

 The syntax for defining a mode iterator is:

 @smallexample
 (define_mode_iterator @var{name} [(@var{mode1} "@var{cond1}") @dots{} (@var{moden} "@var{condn}")])
 @end smallexample

 This allows subsequent @file{.md} file constructs to use the mode suffix
 @code{:@var{name}}.  Every construct that does so will be expanded
 @var{n} times, once with every use of @code{:@var{name}} replaced by
 @code{:@var{mode1}}, once with every use replaced by @code{:@var{mode2}},
 and so on.  In the expansion for a particular @var{modei}, every
 C condition will also require that @var{condi} be true.

 For example:

 @smallexample
 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
 @end smallexample

 defines a new mode suffix @code{:P}.  Every construct that uses
 @code{:P} will be expanded twice, once with every @code{:P} replaced
 by @code{:SI} and once with every @code{:P} replaced by @code{:DI}.
 The @code{:SI} version will only apply if @code{Pmode == SImode} and
 the @code{:DI} version will only apply if @code{Pmode == DImode}.

 As with other @file{.md} conditions, an empty string is treated
 as ``always true''.  @code{(@var{mode} "")} can also be abbreviated
 to @code{@var{mode}}.  For example:

 @smallexample
 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
 @end smallexample

 means that the @code{:DI} expansion only applies if @code{TARGET_64BIT}
 but that the @code{:SI} expansion has no such constraint.

 Iterators are applied in the order they are defined.  This can be
 significant if two iterators are used in a construct that requires
 substitutions.  @xref{Substitutions}.

 @node Substitutions
 @subsubsection Substitution in Mode Iterators
 @findex define_mode_attr

 If an @file{.md} file construct uses mode iterators, each version of the
 construct will often need slightly different strings or modes.  For
 example:

 @itemize @bullet
 @item
 When a @code{define_expand} defines several @code{add@var{m}3} patterns
 (@pxref{Standard Names}), each expander will need to use the
 appropriate mode name for @var{m}.

 @item
 When a @code{define_insn} defines several instruction patterns,
 each instruction will often use a different assembler mnemonic.

 @item
 When a @code{define_insn} requires operands with different modes,
 using an iterator for one of the operand modes usually requires a specific
 mode for the other operand(s).
 @end itemize

 GCC supports such variations through a system of ``mode attributes''.
 There are two standard attributes: @code{mode}, which is the name of
 the mode in lower case, and @code{MODE}, which is the same thing in
 upper case.  You can define other attributes using:

 @smallexample
 (define_mode_attr @var{name} [(@var{mode1} "@var{value1}") @dots{} (@var{moden} "@var{valuen}")])
 @end smallexample

 where @var{name} is the name of the attribute and @var{valuei}
 is the value associated with @var{modei}.

 When GCC replaces some @var{:iterator} with @var{:mode}, it will scan
 each string and mode in the pattern for sequences of the form
 @code{<@var{iterator}:@var{attr}>}, where @var{attr} is the name of a
 mode attribute.  If the attribute is defined for @var{mode}, the whole
 @code{<@dots{}>} sequence will be replaced by the appropriate attribute
 value.

 For example, suppose an @file{.md} file has:

 @smallexample
 (define_mode_iterator P [(SI "Pmode == SImode") (DI "Pmode == DImode")])
 (define_mode_attr load [(SI "lw") (DI "ld")])
 @end smallexample

 If one of the patterns that uses @code{:P} contains the string
 @code{"<P:load>\t%0,%1"}, the @code{SI} version of that pattern
 will use @code{"lw\t%0,%1"} and the @code{DI} version will use
 @code{"ld\t%0,%1"}.

 Here is an example of using an attribute for a mode:

 @smallexample
 (define_mode_iterator LONG [SI DI])
 (define_mode_attr SHORT [(SI "HI") (DI "SI")])
 (define_insn @dots{}
   (sign_extend:LONG (match_operand:<LONG:SHORT> @dots{})) @dots{})
 @end smallexample

 The @code{@var{iterator}:} prefix may be omitted, in which case the
 substitution will be attempted for every iterator expansion.

 @node Examples
 @subsubsection Mode Iterator Examples

 Here is an example from the MIPS port.  It defines the following
 modes and attributes (among others):

 @smallexample
 (define_mode_iterator GPR [SI (DI "TARGET_64BIT")])
 (define_mode_attr d [(SI "") (DI "d")])
 @end smallexample

 and uses the following template to define both @code{subsi3}
 and @code{subdi3}:

 @smallexample
 (define_insn "sub<mode>3"
   [(set (match_operand:GPR 0 "register_operand" "=d")
         (minus:GPR (match_operand:GPR 1 "register_operand" "d")
                    (match_operand:GPR 2 "register_operand" "d")))]
   ""
   "<d>subu\t%0,%1,%2"
   [(set_attr "type" "arith")
    (set_attr "mode" "<MODE>")])
 @end smallexample

 This is exactly equivalent to:

 @smallexample
 (define_insn "subsi3"
   [(set (match_operand:SI 0 "register_operand" "=d")
         (minus:SI (match_operand:SI 1 "register_operand" "d")
                   (match_operand:SI 2 "register_operand" "d")))]
   ""
   "subu\t%0,%1,%2"
   [(set_attr "type" "arith")
    (set_attr "mode" "SI")])

 (define_insn "subdi3"
   [(set (match_operand:DI 0 "register_operand" "=d")
         (minus:DI (match_operand:DI 1 "register_operand" "d")
                   (match_operand:DI 2 "register_operand" "d")))]
   ""
   "dsubu\t%0,%1,%2"
   [(set_attr "type" "arith")
    (set_attr "mode" "DI")])
 @end smallexample

 @node Code Iterators
 @subsection Code Iterators
 @cindex code iterators in @file{.md} files
 @findex define_code_iterator
 @findex define_code_attr

 Code iterators operate in a similar way to mode iterators.  @xref{Mode Iterators}.

 The construct:

 @smallexample
 (define_code_iterator @var{name} [(@var{code1} "@var{cond1}") @dots{} (@var{coden} "@var{condn}")])
 @end smallexample

 defines a pseudo rtx code @var{name} that can be instantiated as
 @var{codei} if condition @var{condi} is true.  Each @var{codei}
 must have the same rtx format.  @xref{RTL Classes}.

 As with mode iterators, each pattern that uses @var{name} will be
 expanded @var{n} times, once with all uses of @var{name} replaced by
 @var{code1}, once with all uses replaced by @var{code2}, and so on.
 @xref{Defining Mode Iterators}.

 It is possible to define attributes for codes as well as for modes.
 There are two standard code attributes: @code{code}, the name of the
 code in lower case, and @code{CODE}, the name of the code in upper case.
 Other attributes are defined using:

 @smallexample
 (define_code_attr @var{name} [(@var{code1} "@var{value1}") @dots{} (@var{coden} "@var{valuen}")])
 @end smallexample

 Here's an example of code iterators in action, taken from the MIPS port:

 @smallexample
 (define_code_iterator any_cond [unordered ordered unlt unge uneq ltgt unle ungt
                                 eq ne gt ge lt le gtu geu ltu leu])

 (define_expand "b<code>"
   [(set (pc)
         (if_then_else (any_cond:CC (cc0)
                                    (const_int 0))
                       (label_ref (match_operand 0 ""))
                       (pc)))]
   ""
 @{
   gen_conditional_branch (operands, <CODE>);
   DONE;
 @})
 @end smallexample

 This is equivalent to:

 @smallexample
 (define_expand "bunordered"
   [(set (pc)
         (if_then_else (unordered:CC (cc0)
                                     (const_int 0))
                       (label_ref (match_operand 0 ""))
                       (pc)))]
   ""
 @{
   gen_conditional_branch (operands, UNORDERED);
   DONE;
 @})

 (define_expand "bordered"
   [(set (pc)
         (if_then_else (ordered:CC (cc0)
                                   (const_int 0))
                       (label_ref (match_operand 0 ""))
                       (pc)))]
   ""
 @{
   gen_conditional_branch (operands, ORDERED);
   DONE;
 @})

 @dots{}
 @end smallexample

 @node Int Iterators
 @subsection Int Iterators
 @cindex int iterators in @file{.md} files
 @findex define_int_iterator
 @findex define_int_attr

 Int iterators operate in a similar way to code iterators.  @xref{Code Iterators}.

 The construct:

 @smallexample
 (define_int_iterator @var{name} [(@var{int1} "@var{cond1}") @dots{} (@var{intn} "@var{condn}")])
 @end smallexample

 defines a pseudo integer constant @var{name} that can be instantiated as
 @var{inti} if condition @var{condi} is true.  Each @var{int}
 must have the same rtx format.  @xref{RTL Classes}. Int iterators can appear
 in only those rtx fields that have 'i' as the specifier. This means that
 each @var{int} has to be a constant defined using define_constant or
 define_c_enum.

 As with mode and code iterators, each pattern that uses @var{name} will be
 expanded @var{n} times, once with all uses of @var{name} replaced by
 @var{int1}, once with all uses replaced by @var{int2}, and so on.
 @xref{Defining Mode Iterators}.

 It is possible to define attributes for ints as well as for codes and modes.
 Attributes are defined using:

 @smallexample
 (define_int_attr @var{name} [(@var{int1} "@var{value1}") @dots{} (@var{intn} "@var{valuen}")])
 @end smallexample

 Here's an example of int iterators in action, taken from the ARM port:

 @smallexample
 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])

 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])

 (define_insn "neon_vq<absneg><mode>"
   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
 	(unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
 		       (match_operand:SI 2 "immediate_operand" "i")]
 		      QABSNEG))]
   "TARGET_NEON"
   "vq<absneg>.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
   [(set_attr "type" "neon_vqneg_vqabs")]
 )

 @end smallexample

 This is equivalent to:

 @smallexample
 (define_insn "neon_vqabs<mode>"
   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
 	(unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
 		       (match_operand:SI 2 "immediate_operand" "i")]
 		      UNSPEC_VQABS))]
   "TARGET_NEON"
   "vqabs.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
   [(set_attr "type" "neon_vqneg_vqabs")]
 )

 (define_insn "neon_vqneg<mode>"
   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
 	(unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
 		       (match_operand:SI 2 "immediate_operand" "i")]
 		      UNSPEC_VQNEG))]
   "TARGET_NEON"
   "vqneg.<V_s_elem>\t%<V_reg>0, %<V_reg>1"
   [(set_attr "type" "neon_vqneg_vqabs")]
 )

 @end smallexample

 @node Subst Iterators
 @subsection Subst Iterators
 @cindex subst iterators in @file{.md} files
 @findex define_subst
 @findex define_subst_attr

 Subst iterators are special type of iterators with the following
 restrictions: they could not be declared explicitly, they always have
 only two values, and they do not have explicit dedicated name.
 Subst-iterators are triggered only when corresponding subst-attribute is
 used in RTL-pattern.

 Subst iterators transform templates in the following way: the templates
 are duplicated, the subst-attributes in these templates are replaced
 with the corresponding values, and a new attribute is implicitly added
 to the given @code{define_insn}/@code{define_expand}.  The name of the
 added attribute matches the name of @code{define_subst}.  Such
 attributes are declared implicitly, and it is not allowed to have a
 @code{define_attr} named as a @code{define_subst}.

 Each subst iterator is linked to a @code{define_subst}.  It is declared
 implicitly by the first appearance of the corresponding
 @code{define_subst_attr}, and it is not allowed to define it explicitly.

 Declarations of subst-attributes have the following syntax:

 @findex define_subst_attr
 @smallexample
 (define_subst_attr "@var{name}"
   "@var{subst-name}"
   "@var{no-subst-value}"
   "@var{subst-applied-value}")
 @end smallexample

 @var{name} is a string with which the given subst-attribute could be
 referred to.

 @var{subst-name} shows which @code{define_subst} should be applied to an
 RTL-template if the given subst-attribute is present in the
 RTL-template.

 @var{no-subst-value} is a value with which subst-attribute would be
 replaced in the first copy of the original RTL-template.

 @var{subst-applied-value} is a value with which subst-attribute would be
 replaced in the second copy of the original RTL-template.

 @node Parameterized Names
 @subsection Parameterized Names
 @cindex @samp{@@} in instruction pattern names
 Ports sometimes need to apply iterators using C++ code, in order to
 get the code or RTL pattern for a specific instruction.  For example,
 suppose we have the @samp{neon_vq<absneg><mode>} pattern given above:

 @smallexample
 (define_int_iterator QABSNEG [UNSPEC_VQABS UNSPEC_VQNEG])

 (define_int_attr absneg [(UNSPEC_VQABS "abs") (UNSPEC_VQNEG "neg")])

 (define_insn "neon_vq<absneg><mode>"
   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
 	(unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
 		       (match_operand:SI 2 "immediate_operand" "i")]
 		      QABSNEG))]
   @dots{}
 )
 @end smallexample

 A port might need to generate this pattern for a variable
 @samp{QABSNEG} value and a variable @samp{VDQIW} mode.  There are two
 ways of doing this.  The first is to build the rtx for the pattern
 directly from C++ code; this is a valid technique and avoids any risk
 of combinatorial explosion.  The second is to prefix the instruction
 name with the special character @samp{@@}, which tells GCC to generate
 the four additional functions below.  In each case, @var{name} is the
 name of the instruction without the leading @samp{@@} character,
 without the @samp{<@dots{}>} placeholders, and with any underscore
 before a @samp{<@dots{}>} placeholder removed if keeping it would
 lead to a double or trailing underscore.

 @table @samp
 @item insn_code maybe_code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
 See whether replacing the first @samp{<@dots{}>} placeholder with
 iterator value @var{i1}, the second with iterator value @var{i2}, and
 so on, gives a valid instruction.  Return its code if so, otherwise
 return @code{CODE_FOR_nothing}.

 @item insn_code code_for_@var{name} (@var{i1}, @var{i2}, @dots{})
 Same, but abort the compiler if the requested instruction does not exist.

 @item rtx maybe_gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
 Check for a valid instruction in the same way as
 @code{maybe_code_for_@var{name}}.  If the instruction exists,
 generate an instance of it using the operand values given by @var{op0},
 @var{op1}, and so on, otherwise return null.

 @item rtx gen_@var{name} (@var{i1}, @var{i2}, @dots{}, @var{op0}, @var{op1}, @dots{})
 Same, but abort the compiler if the requested instruction does not exist,
 or if the instruction generator invoked the @code{FAIL} macro.
 @end table

 For example, changing the pattern above to:

 @smallexample
 (define_insn "@@neon_vq<absneg><mode>"
   [(set (match_operand:VDQIW 0 "s_register_operand" "=w")
 	(unspec:VDQIW [(match_operand:VDQIW 1 "s_register_operand" "w")
 		       (match_operand:SI 2 "immediate_operand" "i")]
 		      QABSNEG))]
   @dots{}
 )
 @end smallexample

 would define the same patterns as before, but in addition would generate
 the four functions below:

 @smallexample
 insn_code maybe_code_for_neon_vq (int, machine_mode);
 insn_code code_for_neon_vq (int, machine_mode);
 rtx maybe_gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
 rtx gen_neon_vq (int, machine_mode, rtx, rtx, rtx);
 @end smallexample

 Calling @samp{code_for_neon_vq (UNSPEC_VQABS, V8QImode)}
 would then give @code{CODE_FOR_neon_vqabsv8qi}.

 It is possible to have multiple @samp{@@} patterns with the same
 name and same types of iterator.  For example:

 @smallexample
 (define_insn "@@some_arithmetic_op<mode>"
   [(set (match_operand:INTEGER_MODES 0 "register_operand") @dots{})]
   @dots{}
 )

 (define_insn "@@some_arithmetic_op<mode>"
   [(set (match_operand:FLOAT_MODES 0 "register_operand") @dots{})]
   @dots{}
 )
 @end smallexample

 would produce a single set of functions that handles both
 @code{INTEGER_MODES} and @code{FLOAT_MODES}.

 @end ifset