md.texi

gcc库的原代码,对编程有很大帮助.

@c Copyright (C) 1988, 1989, 1992, 1993, 1994 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
* 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.
* Insn Canonicalizations::Canonicalization of Instructions
* Peephole Definitions::Defining machine-specific peephole optimizations.
* Expander Definitions::Generating a sequence of several RTL insns
                         for a standard operation.
* Insn Splitting::    Splitting Instructions into Multiple Instructions
* Insn Attributes::     Specifying the value of attributes for generated insns.
@end menu

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

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

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

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