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 <n...@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 @@ -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. + @end ifset @ifset INTERNALS @node Including Patterns @@ -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. +@end table + +If the preparation falls through (invokes neither @code{DONE} nor +@code{FAIL}), then the @code{define_peephole2} uses the replacement +template. + + @noindent If we had not added the @code{(match_dup 4)} in the middle of the input sequence, it might have been the case that the register we chose at the