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