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

[Richard Sandiford <rdsandiford@googlemail.com>]

Thanks for tackling this.

[Sorry, just realised Jeff is going through this ATM too, so sorry for
any dups]

I think Sandra and probably others prefer to avoid an explicit future
tense, e.g. "X is substituted" rather than "X will be substituted".

James Greenhalgh <james.greenhalgh@arm.com> writes:
> @@ -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.

In some ways I think the original version is more accurate.
Something like (match_operand:BLK 1 "") doesn't test anything;
the :BLK is ignored.

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

This could be a bit misleading.  For memories it's sufficient to provide
a suitably general memory constraint (i.e. one that accepts at least
(mem (reg))).  The constraints don't also need to specify a register class
for the 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.

The other way is also important, and in some ways easier to describe:
it is invalid for a constraint to accept something that the predicate
doesn't.  I think it might be worth saying that first.

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

The original was correct here.  The string is a constraint rather
than a predicate.

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

"expression" rather than "expression code" was correct here.
The predicate gets passed the rtx corresponding to operand n
and is allowed to examine its operands as well as its code.

> -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)

Sorry for the mission creep, but while you're there, it'd be good
to make the example use define_predicate instead.

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

I think we can drop this bit.  It doesn't apply to either IRA or LRA
as far as I know.

Thanks,
Richard