Hi,
This patch updates the RTL Template section of md.texi.
I was aiming to:
* Remove outdated details of the compiler.
* Remove long or obscure words that, while accurate, only served to
obfuscate a simple idea.
* Refer to similar things in a consistent fashion - in particular
trying to keep consistent use of "insn" and "pattern".
* Remove superflous examples, or waffling.
OK?
Thanks,
James
---
2015-01-06 James Greenhalgh <james.greenha...@arm.com>
* doc/md.texi (RTL Template): Update text.
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index b852981..a589f5b 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -257,25 +257,23 @@ type of CPU for which code is being generated.
@cindex recognizing insns
@cindex insns, recognizing
-The RTL template is used to define which insns match the particular pattern
+The RTL template is used to define which insns match the pattern
and how to find their operands. For named patterns, the RTL template also
-says how to construct an insn from specified operands.
+defines 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.
+Constructing an insn involves substituting specified operands into a
+copy of the template. Matching an insn involves determining the values
+that serve as the operands in the insn being matched. Both of these
+activities are controlled by the special RTL expressions described below.
@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.
+the instruction pattern. When constructing RTL, operand number @var{n}
+will be substituted at this point. When matching an insn, assuming the
+@var{predicate} is satisfied, whatever appears at this position in the
+insn will be taken as operand number @var{n}.
Operand numbers must be chosen consecutively counting from zero in
each instruction pattern. There may be only one @code{match_operand}
@@ -286,15 +284,15 @@ 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,
+accepts two arguments, an expression and a machine mode
+(@pxref{Predicates}). During matching, the function will be called
+with the operand as the expression and @var{m} as the mode
+argument (if @var{m} is not specified, then @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.
+
+@var{predicate} may be an empty string. This represents a predicate for
+which any operand will be considered 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
@@ -302,80 +300,89 @@ not always. For example, the predicate @code{address_operand} uses
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.
+@var{constraint} controls the best register class to use for a value,
+and therefore register allocation and reloading, as explained
+later (@pxref{Constraints}). If the constraint would be an empty
+string, it can be omitted.
+
+In summary, the predicate is used to control whether the instruction
+pattern is a valid match for an insn. The constraint is used to control
+register allocation decisions in the case of an instruction pattern which
+has already been matched to an insn.
+
+It is an error for the contraints of an operand to be impossible to fulfil
+for operands which are valid for the predicate of the operand. Formally;
+for all operands for which the predicate would be true, there must exist
+at least one valid register class for that operand. Note that this
+restriction does not forbid accepting operands which will need additional
+handling to move them to a valid register class. This restriction would,
+however, prevent combining a constraint set requiring the use of an
+immediate value with a predicate allowing any operand, as it is not
+possible to convert all operand types to immediate values.
@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}
+This expression is a placeholder for operand number @var{n}
+and indicates that the operand must be a @code{scratch} or @code{reg}
expression.
-When matching patterns, this is equivalent to
+When matching instruction patterns, this is equivalent to:
@smallexample
-(match_operand:@var{m} @var{n} "scratch_operand" @var{constraint})
+(match_operand:@var{m} @var{n} "scratch_operand" @var{pred})
@end smallexample
-but, when generating RTL, it produces a (@code{scratch}:@var{m})
-expression.
+When constructing 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}.
+If the last expressions in an instruction pattern containing a
+@code{parallel} are @code{clobber} expressions whose operands are either
+a hard register or @code{match_scratch}, the combine pass of the compiler
+will automatically add or delete them where necessary (@xref{Side Effects}).
@findex match_dup
@item (match_dup @var{n})
-This expression is also a placeholder for operand number @var{n}.
+This expression is a placeholder for operand number @var{n}.
It is used when the operand needs to appear more than once in the
-insn.
+instruction pattern.
-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
+When constructing RTL, @code{match_dup} acts just like @code{match_operand}:
+the operand is substituted into the insn being constructed.
+
+When matching an insn, @code{match_dup} 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
+appearing earlier in the instruction pattern, and 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.
+a particular register is being used for two operands. Rather, the
+@code{constraint} field of an @code{match_operand} should be used to tie
+the two operands through a matching constraint (@pxref{Simple Constraints}).
+@code{match_dup} should be used in cases where one operand is used in two
+places in the template, for example in 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
+This expression is a 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 constructing RTL, it stands for an RTL expression whose expression
+code is taken from that of operand @var{n}, and whose operands are
+constructed from the @var{operands} of the instruction pattern.
-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.
+When matching an insn, it matches if @var{predicate} returns nonzero for
+the expression code @emph{and} the @var{operands} of the expression are
+valid for the instruction pattern.
-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}:
+In this example, the function @code{commutative_operator} is defined 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;
- machine_mode mode;
+commutative_integer_operator (rtx x, machine_mode mode)
@{
enum rtx_code code = GET_CODE (x);
if (GET_MODE (x) != mode)
@@ -385,8 +392,9 @@ commutative_integer_operator (x, mode)
@}
@end smallexample
-Then the following pattern will match any RTL expression consisting
-of a commutative operator applied to two general operands:
+Given this @var{predicate}, 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"
@@ -397,18 +405,18 @@ of a commutative operator applied to two general operands:
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
+When this pattern is matched, 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.
+will be the entire commutative expression: @code{GET_CODE (operands[3])}
+will give 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.
+predicate function. The predicate is responsible for deciding whether
+the expression to be matched has the correct mode.
-When constructing an insn, argument 3 of the gen-function will specify
+When constructing RTL, 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
@@ -416,24 +424,29 @@ 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.
+it is usually best if the operand number of the @code{match_operator}
+is higher than that of the actual operands of the insn. This can
+improve register allocation because the register allocator often
+looks at operands 1 and 2 of insns to see if they are suitable
+for register tying.
+
+There is no way to specify constraints in a @code{match_operator}
+expression. 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
+operands.
+
+When constructing RTL, operand number @var{n} will be substituted at
+this point.
+
+When matching an insn, @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.
@@ -442,7 +455,7 @@ expression.
@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.
+expression may 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
