md.texi

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

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}