From: Paul Koning <ni1d@arrl.net>
Date: Fri, 6 Jul 2018 16:39:50 +0000 (-0400)
Subject: Update internal documentation to describe that DONE and FAIL
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=582d1f904948c830a711739cc3388bbc71be4947;p=gcc.git

Update internal documentation to describe that DONE and FAIL
	also apply to define_split and define_peephole2.

	* doc/md.texi (define_split): Document DONE and FAIL.
	(define_peephole2): Ditto.

From-SVN: r262479
---

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 61fc28f076e..5c096fa4dc3 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2018-07-06  Paul Koning  <ni1d@arrl.net>
+
+	* doc/md.texi (define_split): Document DONE and FAIL.
+	(define_peephole2): Ditto.
+
 2018-07-05  Jeff Law  <law@redhat.com>
 
 	PR tree-optimization/86010
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 09d6e307c24..6d15d993132 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -8060,6 +8060,30 @@ those in @code{define_expand}, however, these statements must not
 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 the input insn will not be split.
+@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
@@ -8615,6 +8639,33 @@ 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.  In that case, GCC may still apply a
+later @code{define_peephole2} that also matches the given insn pattern.
+(Note that this is different from @code{define_split}, where @code{FAIL}
+prevents the input insn from being split at all.)
+@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