md.texi

理解和实践操作系统的一本好书

@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 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