Re: [PATCH] doc clarification: DONE and FAIL in define_split and define_peephole2

[Richard Sandiford <richard dot sandiford at arm dot com>]

Paul Koning <paulkoning@comcast.net> writes:
> Currently DONE and FAIL are documented only for define_expand, but
> they also work in essentially the same way for define_split and
> define_peephole2.
>
> If FAIL is used in a define_insn_and_split, the output pattern cannot
> be the usual "#" dummy value.
>
> This patch updates the doc to describe those cases.  Ok for trunk?
>
> 	paul
>
> ChangeLog:
>
> 2018-07-05  Paul Koning  <ni1d@arrl.net>
>
> 	* doc/md.texi (define_split): Document DONE and FAIL.  Describe
> 	interaction with usual "#" output template in
> 	define_insn_and_split.
> 	(define_peephole2): Document DONE and FAIL.
>
> Index: doc/md.texi
> ===================================================================
> --- doc/md.texi	(revision 262455)
> +++ doc/md.texi	(working copy)
> @@ -8060,6 +8060,30 @@ those in @code{define_expand}, however, these stat
>  generate any new pseudo-registers.  Once reload has completed, they also
>  must not allocate any space in the stack frame.
>  
> +There are two special macros defined for use in the preparation statements:
> +@code{DONE} and @code{FAIL}.  Use them with a following semicolon,
> +as a statement.
> +
> +@table @code
> +
> +@findex DONE
> +@item DONE
> +Use the @code{DONE} macro to end RTL generation for the splitter.  The
> +only RTL insns generated as replacement for the matched input insn will
> +be those already emitted by explicit calls to @code{emit_insn} within
> +the preparation statements; the replacement pattern is not used.
> +
> +@findex FAIL
> +@item FAIL
> +Make the @code{define_split} fail on this occasion.  When a @code{define_split}
> +fails, it means that the splitter was not truly available for the inputs
> +it was given, and this split is not done.
> +@end table
> +
> +If the preparation falls through (invokes neither @code{DONE} nor
> +@code{FAIL}), then the @code{define_split} uses the replacement
> +template.
> +
>  Patterns are matched against @var{insn-pattern} in two different
>  circumstances.  If an insn needs to be split for delay slot scheduling
>  or insn scheduling, the insn is already known to be valid, which means

Looks good.

> @@ -8232,6 +8256,15 @@ functionality as two separate @code{define_insn} a
>  patterns.  It exists for compactness, and as a maintenance tool to prevent
>  having to ensure the two patterns' templates match.
>  
> +In @code{define_insn_and_split}, the output template is usually simply
> +@samp{#} since the assembly output is done by @code{define_insn}
> +statements matching the generated insns, not by this
> +@code{define_insn_and_split} statement.  But if @code{FAIL} is used in
> +the preparation statements for certain input insns, those will not be
> +split and during assembly output will again match this
> +@code{define_insn_and_split}.  In that case, the appropriate assembly
> +output statements are needed in the output template.
> +

I agree "#" on its own is relatively common, but it's also not that
unusual to have a define_insn_and_split in which the define_insn part
handles simple alternatives directly and leaves more complex ones to
be split.  Maybe that's more common on RISC-like targets.

Also, the define_split matches the template independently of the
define_insn, so it can sometimes split insns that match an earlier
define_insn rather than the one in the define_insn_and_split.
(That might be bad practice.)  So using "#" and FAIL together is valid
if the FAIL only happens for cases that match earlier define_insns.

Another case is when the define_split condition doesn't start with
"&&" and is less strict than the define_insn condition.  This can
be useful if the define_split is supposed to match patterns created
by combine.

So maybe we should instead expand the FAIL documentation to say that
a define_split must not FAIL when splitting an instruction whose
output template is "#".

> @@ -8615,6 +8648,31 @@ so here's a silly made-up example:
>    "")
>  @end smallexample
>  
> +There are two special macros defined for use in the preparation statements:
> +@code{DONE} and @code{FAIL}.  Use them with a following semicolon,
> +as a statement.
> +
> +@table @code
> +
> +@findex DONE
> +@item DONE
> +Use the @code{DONE} macro to end RTL generation for the peephole.  The
> +only RTL insns generated as replacement for the matched input insn will
> +be those already emitted by explicit calls to @code{emit_insn} within
> +the preparation statements; the replacement pattern is not used.
> +
> +@findex FAIL
> +@item FAIL
> +Make the @code{define_peephole2} fail on this occasion.  When a @code{define_peephole2}
> +fails, it means that the replacement was not truly available for the
> +particular inputs it was given, and the input insns are left unchanged.

If it FAILs, GCC will try to apply later define_peehole2s instead.
(This is in contrast to define_split, so it's a bit inconsistent.
Would be easy to make define_split behave the same way if there was a
motivating case.)

Thanks,
Richard