[Patch docs 5/5] Update "Predicates" from md.texi

[James Greenhalgh <james dot greenhalgh at arm dot com>]

Hi,

This patch updates the predicates section from 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 (Predicates): Update text.

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 3b853c8..e1fd8c6 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -737,9 +737,8 @@ predicates used with @code{match_operand} have names that end in
 @samp{_operand}, and those used with @code{match_operator} have names
 that end in @samp{_operator}.
 
-All predicates are Boolean functions (in the mathematical sense) of
-two arguments: the RTL expression that is being considered at that
-position in the instruction pattern, and the machine mode that the
+Predicates take two arguments: the RTL expression that is being considered
+at that position in the instruction pattern, and the machine mode that the
 @code{match_operand} or @code{match_operator} specifies.  In this
 section, the first argument is called @var{op} and the second argument
 @var{mode}.  Predicates can be called from C as ordinary two-argument
@@ -747,39 +746,51 @@ functions; this can be useful in output templates or other
 machine-specific code.
 
 Operand predicates can allow operands that are not actually acceptable
-to the hardware, as long as the constraints give reload the ability to
-fix them up (@pxref{Constraints}).  However, GCC will usually generate
-better code if the predicates specify the requirements of the machine
-instructions as closely as possible.  Reload cannot fix up operands
-that must be constants (``immediate operands''); you must use a
-predicate that allows only constants, or else enforce the requirement
-in the extra condition.
+to the hardware, as long as the constraints can be fulfilled, perhaps by
+moving the operand between register classes, during register allocation
+(@pxref{Constraints}).  However, GCC will usually generate better code
+if the predicates specify the requirements of the machine instructions
+as closely as possible.
+
+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.  One such
+example would be the combination of a predicate allowing any operand,
+with a constraint requiring only immediate operands.  Here, the predicate
+may permit a register operand containing a non-constant value, which it would
+not be possible to convert to an immediate operand.
 
 @cindex predicates and machine modes
 @cindex normal predicates
 @cindex special predicates
-Most predicates handle their @var{mode} argument in a uniform manner.
-If @var{mode} is @code{VOIDmode} (unspecified), then @var{op} can have
-any mode.  If @var{mode} is anything else, then @var{op} must have the
-same mode, unless @var{op} is a @code{CONST_INT} or integer
-@code{CONST_DOUBLE}.  These RTL expressions always have
-@code{VOIDmode}, so it would be counterproductive to check that their
-mode matches.  Instead, predicates that accept @code{CONST_INT} and/or
-integer @code{CONST_DOUBLE} check that the value stored in the
-constant will fit in the requested mode.
-
-Predicates with this behavior are called @dfn{normal}.
-@command{genrecog} can optimize the instruction recognizer based on
-knowledge of how normal predicates treat modes.  It can also diagnose
-certain kinds of common errors in the use of normal predicates; for
-instance, it is almost always an error to use a normal predicate
-without specifying a mode.
-
-Predicates that do something different with their @var{mode} argument
-are called @dfn{special}.  The generic predicates
-@code{address_operand} and @code{pmode_register_operand} are special
-predicates.  @command{genrecog} does not do any optimizations or
-diagnosis when special predicates are used.
+@dfn{Normal} predicates are those for which the relationship between
+@var{mode} and @var{op} can be described in one of the following ways.
+
+@enumerate
+@item
+If @var{mode} is @code{VOIDmode} or is unspecified, then @var{op} can have
+any mode.
+
+@item
+If @var{mode} is a defined mode, then @var{op} must be of the same mode.
+
+@item
+If @var{op} is a @code{CONST_INT} or an integer @code{CONST_DOUBLE} RTL
+expression, @var{mode} can be any mode.  The predicate must itself
+check that the range of @var{mode} is sufficient to contain the value in
+@var{op}.
+@end enumerate
+
+Using normal predicates allows for additional optimization to be
+performed in the @command{genrecog} program.  This can result in a
+more efficient instruction recognizer.  @command{genrecog} is also able
+to diagnose common errors in the use of normal predicates, such as a
+missing @var{mode}.
+
+Predicates that do not have the relationship described above between their
+@var{mode} and @var{op} arguments are called @dfn{special} predicates.
+The generic predicates @code{address_operand} and
+@code{pmode_register_operand} are special predicates. @command{genrecog}
+does not do any optimizations or diagnosis when special predicates are used.
 
 @menu
 * Machine-Independent Predicates::  Predicates available to all back ends.
@@ -794,25 +805,25 @@ diagnosis when special predicates are used.
 
 These are the generic predicates available to all back ends.  They are
 defined in @file{recog.c}.  The first category of predicates allow
-only constant, or @dfn{immediate}, operands.
+only constant, or @dfn{immediate}, operands and are normal predicates.
 
 @defun immediate_operand
 This predicate allows any sort of constant that fits in @var{mode}.
-It is an appropriate choice for instructions that take operands that
-must be constant.
+It is an appropriate choice for operands to an instruction which requires
+a constant.
 @end defun
 
 @defun const_int_operand
 This predicate allows any @code{CONST_INT} expression that fits in
-@var{mode}.  It is an appropriate choice for an immediate operand that
-does not allow a symbol or label.
+@var{mode}.  It is an appropriate choice for operands to an instruction
+which requires an integer constant that may not be a symbol or a label.
 @end defun
 
 @defun const_double_operand
-This predicate accepts any @code{CONST_DOUBLE} expression that has
+This predicate allows any @code{CONST_DOUBLE} expression that has
 exactly @var{mode}.  If @var{mode} is @code{VOIDmode}, it will also
-accept @code{CONST_INT}.  It is intended for immediate floating point
-constants.
+accept any @code{CONST_INT} expression.  It is an appropriate choice for
+operands to an instruction which requires a floating point constant.
 @end defun
 
 @noindent
@@ -821,30 +832,33 @@ register.
 
 @defun register_operand
 This predicate allows any @code{REG} or @code{SUBREG} expression that
-is valid for @var{mode}.  It is often suitable for arithmetic
-instruction operands on a RISC machine.
+is valid for @var{mode}.  It is an appropriate choice for operands to an
+instruction which requires a machine register.
 @end defun
 
 @defun pmode_register_operand
-This is a slight variant on @code{register_operand} which works around
-a limitation in the machine-description reader.
+This predicate is a slight variant on @code{register_operand} which works
+around a limitation in the machine-description reader.  As @code{Pmode}
+can be an alias for some other mode, and might vary with machine-specific
+options, the machine-description reader is unable to accept @code{P} mode
+suffixes (@pxref{Misc}).
+
+Consequently, the construct:
 
 @smallexample
 (match_operand @var{n} "pmode_register_operand" @var{constraint})
 @end smallexample
 
 @noindent
-means exactly what
+expresses what would have otherwise have been written as:
 
 @smallexample
 (match_operand:P @var{n} "register_operand" @var{constraint})
 @end smallexample
 
 @noindent
-would mean, if the machine-description reader accepted @samp{:P}
-mode suffixes.  Unfortunately, it cannot, because @code{Pmode} is an
-alias for some other mode, and might vary with machine-specific
-options.  @xref{Misc}.
+were it not for the deficiencies in the machine-description reader.
+
 @end defun
 
 @defun scratch_operand
@@ -857,15 +871,15 @@ it should not be used directly.
 The third category of predicates allow only some kind of memory reference.
 
 @defun memory_operand
-This predicate allows any valid reference to a quantity of mode
+This predicate allows any valid reference to an objects of mode
 @var{mode} in memory, as determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS} (@pxref{Addressing Modes}).
 @end defun
 
 @defun address_operand
-This predicate is a little unusual; it allows any operand that is a
-valid expression for the @emph{address} of a quantity of mode
-@var{mode}, again determined by the weak form of
+This is a special predicate which allows any operand that is a
+valid expression for the @emph{address} of an object of mode
+@var{mode}, as determined by the weak form of
 @code{GO_IF_LEGITIMATE_ADDRESS}.  To first order, if
 @samp{@w{(mem:@var{mode} (@var{exp}))}} is acceptable to
 @code{memory_operand}, then @var{exp} is acceptable to
@@ -874,29 +888,31 @@ the mode @var{mode}.
 @end defun
 
 @defun indirect_operand
-This is a stricter form of @code{memory_operand} which allows only
-memory references with a @code{general_operand} as the address
-expression.  New uses of this predicate are discouraged, because
-@code{general_operand} is very permissive, so it's hard to tell what
-an @code{indirect_operand} does or does not allow.  If a target has
-different requirements for memory operands for different instructions,
-it is better to define target-specific predicates which enforce the
-hardware's requirements explicitly.
+This predicate is a stricter form of @code{memory_operand} which allows
+only memory references with a @code{general_operand} as the address
+expression.  New uses of this predicate are discouraged.
+
+The @code{general_operand} predicate is very permissive, consequently,
+an @code{indirect_operand} may permit more address expressions than would
+be expected.  A target with different requirements for memory operands
+for different instructions should instead define target-specific predicates
+which enforce the hardware's requirements explicitly.
 @end defun
 
 @defun push_operand
 This predicate allows a memory reference suitable for pushing a value
 onto the stack.  This will be a @code{MEM} which refers to
 @code{stack_pointer_rtx}, with a side-effect in its address expression
-(@pxref{Incdec}); which one is determined by the
+(@pxref{Incdec}). The type of side-effect is defined by the
 @code{STACK_PUSH_CODE} macro (@pxref{Frame Layout}).
 @end defun
 
 @defun pop_operand
 This predicate allows a memory reference suitable for popping a value
-off the stack.  Again, this will be a @code{MEM} referring to
+off the stack.  This will be a @code{MEM} referring to
 @code{stack_pointer_rtx}, with a side-effect in its address
-expression.  However, this time @code{STACK_POP_CODE} is expected.
+expression.  The type of side-effect is defined by the @code{STACK_POP_CODE}
+macro.
 @end defun
 
 @noindent
@@ -969,27 +985,38 @@ subexpression of @var{op} has one of a given list of RTX codes.
 
 The first operand of this expression is a string constant containing a
 comma-separated list of RTX code names (in lower case).  These are the
-codes for which the @code{MATCH_CODE} will be true.
-
-The second operand is a string constant which indicates what
-subexpression of @var{op} to examine.  If it is absent or the empty
-string, @var{op} itself is examined.  Otherwise, the string constant
-must be a sequence of digits and/or lowercase letters.  Each character
-indicates a subexpression to extract from the current expression; for
-the first character this is @var{op}, for the second and subsequent
-characters it is the result of the previous character.  A digit
-@var{n} extracts @samp{@w{XEXP (@var{e}, @var{n})}}; a letter @var{l}
-extracts @samp{@w{XVECEXP (@var{e}, 0, @var{n})}} where @var{n} is the
-alphabetic ordinal of @var{l} (0 for `a', 1 for 'b', and so on).  The
-@code{MATCH_CODE} then examines the RTX code of the subexpression
-extracted by the complete string.  It is not possible to extract
-components of an @code{rtvec} that is not at position 0 within its RTX
-object.
+expected codes for which the @code{MATCH_CODE} will be true.
+
+The second, optional, operand is a string constant which indicates which
+subexpression of @var{op} to examine.  If it is absent or is the empty
+string, @var{op} itself is examined.
+
+Otherwise, the string constant must be a sequence of digits and/or
+lowercase letters.  Each character indicates a subexpression to extract
+from the current expression, @var{e}.  For the first character this is
+@var{op}, for the second and subsequent characters it is the result of
+the subexpression indicated by the previous character.
+
+A digit @var{n} extracts the @var{n}'th subexpression of the current
+expression, as if by @samp{@w{XEXP (@var{e}, @var{n})}}.
+
+A letter @var{l} extracts an element from the vector subexpression which
+is found at operand 0 of the current expression.  First @var{l} is
+converted to an integer @var{n} by taking the alphabetic ordinal of
+@var{l} (0 for `a', 1 for 'b', and so on).  @var{n} is then used to extract
+the @var{n}'th element of the vector subexpression at operand 0 of the current
+expression, as if by @samp{@w{XVECEXP (@var{e}, 0, @var{n})}}. It is not
+possible to extract components of an @code{rtvec} that is not at position
+0 within its RTX object.
+
+@code{MATCH_CODE} evaluates to true if the RTX code of the current
+expression, @var{e}, having parsed the full string, matches any of
+those listed in the expected codes.
 
 @item MATCH_TEST
 This expression has one operand, a string constant containing a C
-expression.  The predicate's arguments, @var{op} and @var{mode}, are
-available with those names in the C expression.  The @code{MATCH_TEST}
+expression.  The arguments to the predicate, @var{op} and @var{mode},
+are available with those names in the C expression.  @code{MATCH_TEST}
 evaluates to true if the C expression evaluates to a nonzero value.
 @code{MATCH_TEST} expressions must not have side effects.
 
@@ -1001,8 +1028,8 @@ The basic @samp{MATCH_} expressions can be combined using these
 logical operators, which have the semantics of the C operators
 @samp{&&}, @samp{||}, @samp{!}, and @samp{@w{? :}} respectively.  As
 in Common Lisp, you may give an @code{AND} or @code{IOR} expression an
-arbitrary number of arguments; this has exactly the same effect as
-writing a chain of two-argument @code{AND} or @code{IOR} expressions.
+arbitrary number of arguments; this has the same effect as writing a
+chain of two-argument @code{AND} or @code{IOR} expressions.
 @end table
 
 @item
@@ -1015,8 +1042,8 @@ available with those names.
 If a code block is present in a predicate definition, then the RTL
 expression must evaluate to true @emph{and} the code block must
 execute @samp{@w{return true}} for the predicate to allow the operand.
-The RTL expression is evaluated first; do not re-check anything in the
-code block that was checked in the RTL expression.
+The RTL expression is evaluated first.  There is no reason to re-check
+anything in the code block that was checked in the RTL expression.
 @end itemize
 
 The program @command{genrecog} scans @code{define_predicate} and
@@ -1062,10 +1089,10 @@ mode as @var{mode}, or @var{op} is a @code{CONST_INT} or
 @code{CONST_DOUBLE}.  They do @emph{not} check specifically for
 integer @code{CONST_DOUBLE}, nor do they test that the value of either
 kind of constant fits in the requested mode.  This is because
-target-specific predicates that take constants usually have to do more
-stringent value checks anyway.  If you need the exact same treatment
-of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic predicates
-provide, use a @code{MATCH_OPERAND} subexpression to call
+target-specific predicates that take constants usually have a more restricted
+range than that of the full machine mode.  If you need the exact same
+treatment of @code{CONST_INT} or @code{CONST_DOUBLE} that the generic
+predicates provide, use a @code{MATCH_OPERAND} subexpression to call
 @code{const_int_operand}, @code{const_double_operand}, or
 @code{immediate_operand}.