md.texi

GCC

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 2000, 2001
@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.
* Constraints::         When not all operands are general operands.
* 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.
* 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.
@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 DONE.  For certain named patterns, it may invoke 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}.

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

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

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 C function that accepts two
arguments, an expression and a machine mode.  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}).

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 general_operand
On CISC machines, the most common @var{predicate} is
@code{"general_operand"}.  This function checks that the putative
operand is either a constant, a register or a memory reference, and that
it is valid for mode @var{m}.

@findex register_operand
For an operand that must be a register, @var{predicate} should be
@code{"register_operand"}.  Using @code{"general_operand"} would be
valid, since the reload pass would copy any non-register operands
through registers, but this would make GNU CC do extra work, it would
prevent invariant operands (such as constant) from being removed from
loops, and it would prevent the register allocator from doing the best
possible job.  On RISC machines, it is usually most efficient to allow
@var{predicate} to accept only objects that the constraints allow.

@findex immediate_operand
For an operand that must be a constant, you must be sure to either use
@code{"immediate_operand"} for @var{predicate}, or make the instruction
pattern's extra condition require a constant, or both.  You cannot
expect the constraints to do this work!  If the constraints allow only
constants, but the predicate allows something else, the compiler will
crash when that case arises.

@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_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) == 'c'
          || 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