* gcc/doc/extended.texi: Replace the dash character with

[pf3gnuchains/gcc-fork.git] / gcc / doc / md.texi

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
@c 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.
* 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
Each instruction pattern 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 pattern or C code to generate the assembler
output, all wrapped up in a @code{define_insn} expression.

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

@enumerate
@item
An optional name.  The presence of a name indicate that this instruction
pattern can perform a certain standard job for the RTL-generation
pass of the compiler.  This pass knows certain names and will use
the instruction patterns with those names, if the names are defined
in the machine description.

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.

Names that are not thus known and used in RTL-generation have no
effect; they are equivalent to no name at all.

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 entirely equivalent
to having a nameless pattern for all other purposes.

@item
The @dfn{RTL template} (@pxref{RTL Template}) is a vector of incomplete
RTL expressions which show what the instruction should look like.  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 only one element, that element is the template for the
instruction pattern.  If the vector has multiple elements, then the
instruction pattern is a @code{parallel} expression containing the
elements described.

@item
@cindex pattern conditions
@cindex conditions, in patterns
A condition.  This is a string which contains a C expression that is
the final test to decide whether an insn body matches this pattern.

@cindex named patterns and conditions
For a named pattern, 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.

@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}.  For an insn where the condition has once matched, it
can't be used to control register allocation, for example by excluding
certain hard registers or hard register combinations.

@item
The @dfn{output template}: a string that says how to output matching
insns as assembler code.  @samp{%} in this string specifies where
to substitute the value of an operand.  @xref{Output Template}.

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

@item
Optionally, a vector containing the values of attributes for insns matching
this pattern.  @xref{Insn Attributes}.
@end enumerate

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

Here is an actual example of an instruction pattern, 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 is an instruction that sets the condition codes based on the value of
a general operand.  It has no condition, so any insn whose RTL description
has the form shown may be handled according 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{pred})
@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;
     enum 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.

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

@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.

@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.
* Disable Insn Alternatives:: Disable insn alternatives using the @code{enabled} attribute.
* Machine Constraints:: Existing constraints for some particular machines.
* 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.

@cindex @samp{>} in constraint
@item @samp{>}
A memory operand with autoincrement addressing (either preincrement or
postincrement) is allowed.

@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.
@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}).
@end ifset

@c FIXME Is this ? and ! stuff of use in asm()?  If not, hide unless INTERNAL
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.
@end table

@ifset INTERNALS
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

@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 write-only for this instruction: the previous
value is discarded and replaced by output 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 inputs to the instruction and
which are outputs from it.  @samp{=} identifies an output; @samp{+}
identifies an operand that is both input and output; all other operands
are assumed to be input only.

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 modified before the instruction is
finished using the input operands.  Therefore, this operand may not lie
in a register that is used as an input operand 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.

An input operand 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 inputs can be affected by the earlyclobber.
See, for example, the @samp{mulsi3} insn of the ARM@.

@samp{&} does not obviate the need to write @samp{=}.

@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.
@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.  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.

@ifset INTERNALS
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.

@table @emph
@item ARM family---@file{config/arm/arm.h}
@table @code
@item f
Floating-point register

@item w
VFP floating-point register

@item F
One of the floating-point constants 0.0, 0.5, 1.0, 2.0, 3.0, 4.0, 5.0
or 10.0

@item G
Floating-point constant that would satisfy the constraint @samp{F} if it
were negated

@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 R
Integer constant in the range @minus{}6 @dots{} 5.

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

@item CRX Architecture---@file{config/crx/crx.h}
@table @code

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

@item l
Register r16 (64-bit accumulator lo register)

@item h
Register r17 (64-bit accumulator hi register)

@item k
Register pair r16-r17. (64-bit accumulator lo-hi pair)

@item I
Constant that fits in 3 bits

@item J
Constant that fits in 4 bits

@item K
Constant that fits in 5 bits

@item L
Constant that is one of @minus{}1, 4, @minus{}4, 7, 8, 12, 16, 20, 32, 48

@item G
Floating point constant that is legal for store immediate
@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 picoChip family---@file{picochip.h}
@table @code
@item k
Stack register.

@item f
Pointer register.  A register which can be used to access memory without
supplying an offset.  Any other register can be used to access memory,
but will need a constant offset.  In the case of the offset being zero,
it is more efficient to use a pointer register, since this reduces code
size.

@item t
A twin register.  A register which may be paired with an adjacent
register to create a 32-bit register.

@item a
Any absolute memory address (e.g., symbolic constant, symbolic
constant + offset).

@item I
4-bit signed integer.

@item J
4-bit unsigned integer.

@item K
8-bit signed integer.

@item M
Any constant whose absolute value is no greater than 4-bits.

@item N
10-bit signed integer

@item O
16-bit signed integer.

@end table

@item PowerPC and IBM RS6000---@file{config/rs6000/rs6000.h}
@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 wd
VSX vector register to hold vector double data

@item wf
VSX vector register to hold vector float data

@item ws
VSX vector register to hold scalar float data

@item wa
Any VSX register

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

@item q
@samp{MQ} 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{FPMEM} stack memory for FPR-GPR transfers

@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.  Note that on PowerPC targets, @code{m} can include
addresses that update the base register.  It is therefore 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.  Use @code{es} rather than @code{m} if you don't want the
base register to be updated.

@item es
A ``stable'' memory operand; that is, one which does not include any
automodification of the base register.  Unlike @samp{m}, this constraint
can be used in @code{asm} statements that might access the operand
several times, or that might not access it at all.

@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 S
Constant suitable as a 64-bit mask operand

@item T
Constant suitable as a 32-bit mask operand

@item U
System V Release 4 small data area reference

@item t
AND masks that can be performed by two rldic@{l, r@} instructions

@item W
Vector constant that does not require memory

@item j
Vector constant that is all zeros.

@end table

@item Intel 386---@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, as a pair (for instructions that
return half the result in one and half in the other).

@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)}).

@item y
Any MMX register.

@item x
Any SSE register.

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

@ifset INTERNALS
@item Y2
Any SSE register, when SSE2 is enabled.

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

@item Ym
Any MMX register, when inter-unit moves are enabled.
@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
Standard SSE floating point constant.

@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 Z
32-bit unsigned integer constant, or a symbolic reference known
to fit that range (for immediate operands in zero-extending x86-64
instructions).

@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.
Remember that @samp{m} allows postincrement and postdecrement which
require printing with @samp{%Pn} on IA-64.
Use @samp{S} to disallow postincrement and postdecrement.

@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
@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 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 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 MeP---@file{config/mep/constraints.md}
@table @code

@item a
The $sp register.

@item b
The $tp register.

@item c
Any control register.

@item d
Either the $hi or the $lo register.

@item em
Coprocessor registers that can be directly loaded ($c0-$c15).

@item ex
Coprocessor registers that can be moved to each other.

@item er
Coprocessor registers that can be moved to core registers.

@item h
The $hi register.

@item j
The $rpc register.

@item l
The $lo register.

@item t
Registers which can be used in $tp-relative addressing.

@item v
The $gp register.

@item x
The coprocessor registers.

@item y
The coprocessor control registers.

@item z
The $0 register.

@item A
User-defined register set A.

@item B
User-defined register set B.

@item C
User-defined register set C.

@item D
User-defined register set D.

@item I
Offsets for $gp-rel addressing.

@item J
Constants that can be used directly with boolean insns.

@item K
Constants that can be moved directly to registers.

@item L
Small constants that can be added to registers.

@item M
Long shift counts.

@item N
Small constants that can be compared to registers.

@item O
Constants that can be loaded into the top half of registers.

@item S
Signed 8-bit immediates.

@item T
Symbols encoded for $tp-rel or $gp-rel addressing.

@item U
Non-constant addresses for loading/saving coprocessor registers.

@item W
The top half of a symbol's value.

@item Y
A register indirect address without offset.

@item Z
Symbolic references to the control bus.



@end table

@item MIPS---@file{config/mips/constraints.md}
@table @code
@item d
An address register.  This is equivalent to @code{r} unless
generating MIPS16 code.

@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.
@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 Motorola 68HC11 & 68HC12 families---@file{config/m68hc11/m68hc11.h}
@table @code
@item a
Register `a'

@item b
Register `b'

@item d
Register `d'

@item q
An 8-bit register

@item t
Temporary soft register _.tmp

@item u
A soft register _.d1 to _.d31

@item w
Stack pointer register

@item x
Register `x'

@item y
Register `y'

@item z
Pseudo register `z' (replaced by `x' or `y' at the end)

@item A
An address register: x, y or z

@item B
An address register: x or y

@item D
Register pair (x:d) to form a 32-bit value

@item L
Constants in the range @minus{}65536 to 65535

@item M
Constants whose 16-bit low part is zero

@item N
Constant integer 1 or @minus{}1

@item O
Constant integer 16

@item P
Constants in the range @minus{}8 to 2

@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

@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 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

@item M
A constant in the range supported by @code{movrcc} instructions

@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 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 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 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

@item Score family---@file{config/score/score.h}
@table @code
@item d
Registers from r0 to r32.

@item e
Registers from r0 to r16.

@item t
r8---r11 or r22---r27 registers.

@item h
hi register.

@item l
lo register.

@item x
hi + lo register.

@item q
cnt register.

@item y
lcb register.

@item z
scb register.

@item a
cnt + lcb + scb register.

@item c
cr0---cr15 register.

@item b
cp1 registers.

@item f
cp2 registers.

@item i
cp3 registers.

@item j
cp1 + cp2 + cp3 registers.

@item I
High 16-bit constant (32-bit constant with 16 LSBs zero).

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

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

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

@item M
Unsigned 14 bit integer (in the range 0 to 16383).

@item N
Signed 14 bit integer (in the range @minus{}8192 to 8191).

@item Z
Any SYMBOL_REF.
@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

The @code{enabled} insn attribute may be used to disable certain insn
alternatives for machine-specific reasons.  This is useful when adding
new instructions to an existing pattern which are only available for
certain cpu architecture levels as specified with the @code{-march=}
option.

If an insn alternative is disabled, then it will never be used.  The
compiler treats the constraints for the disabled alternative as
unsatisfiable.

In order to make use of the @code{enabled} attribute a back end has to add
in the machine description files:

@enumerate
@item
A definition of the @code{enabled} insn attribute.  The attribute is
defined as usual using the @code{define_attr} command.  This
definition should be based on other insn attributes and/or target flags.
The @code{enabled} attribute is a numeric attribute and should evaluate to
@code{(const_int 1)} for an enabled alternative and to
@code{(const_int 0)} otherwise.
@item
A definition of another insn attribute used to describe for what
reason an insn alternative might be available or
not.  E.g. @code{cpu_facility} as in the example below.
@item
An assignment for the second attribute to each insn definition
combining instructions which are not all available under the same
circumstances.  (Note: It obviously only makes sense for definitions
with more than one alternative.  Otherwise the insn pattern should be
disabled or enabled using the insn condition.)
@end enumerate

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_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 machine-specific constraints.  None of these interfaces work with
the generic constraints described in @ref{Simple Constraints}.  This
may change in the future.

@strong{Warning:} @file{tm_p.h} may declare other functions that
operate on constraints, besides the ones documented here.  Do not use
those functions from machine-dependent code.  They exist to implement
the old constraint interface that machine-independent components of
the compiler still expect.  They will change or disappear in the
future.

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 machine-specific constraint, 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.

Machine-independent constraints do not have associated constants.
This may change in the future.
@end deftp

@deftypefun {inline bool} satisfies_constraint_@var{m} (rtx @var{exp})
For each machine-specific, non-register constraint @var{m}, 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} regclass_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{HARD_REGNO_MODE_OK} permits mode @var{m} in both registers and
@code{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{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_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}} instruction pattern
@item @samp{vec_extract@var{m}}
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.