Subversion Repositories scarts

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,

@c 2002, 2003, 2004, 2005 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.

* Macros::              Using macros 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 an 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 is one generic operator predicate.

@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

@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 has one operand, a string constant containing a

comma-separated list of RTX code names (in lower case).  It evaluates

to true if @var{op} has any of the listed codes.

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

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