This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[Patch docs 3/5] Update "RTL Template" in md.texi


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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]