Clarify define_insn documentation

This patch tries to clarify some of the restrictions on define_insn
conditions, and also on the use of "#".

2017-06-06  Richard Sandiford  <richard.sandiford@linaro.org>

gcc/
	* doc/md.texi: Clarify the restrictions on a define_insn condition.
	Say that # requires an associated define_split to exist, and that
	the define_split must be suitable for use after register allocation.

From-SVN: r248946

2 files changed, 27 insertions, 4 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 3b2c8b9..a5aaf47 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,9 @@
+2017-06-07  Richard Sandiford  <richard.sandiford@linaro.org>
+
+	* doc/md.texi: Clarify the restrictions on a define_insn condition.
+	Say that # requires an associated define_split to exist, and that
+	the define_split must be suitable for use after register allocation.
+
 2017-06-06  Jan Hubicka  <hubicka@ucw.cz>
 
 	* cfgbuild.c (find_bb_boundaries): Initialize profile of split blocks.
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index a334e52..5a00a2c 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -115,7 +115,7 @@ A @code{define_insn} is an RTL expression containing four or five operands:
 
 @enumerate
 @item
-An optional name.  The presence of a name indicate that this instruction
+An optional name.  The presence of a name indicates that this instruction
 pattern can perform a certain standard job for the RTL-generation
 pass of the compiler.  This pass knows certain names and will use
 the instruction patterns with those names, if the names are defined
@@ -166,9 +166,21 @@ individual insn, and only after the insn has matched the pattern's
 recognition template.  The insn's operands may be found in the vector
 @code{operands}.
 
-For an insn where the condition has once matched, it
-cannot later be used to control register allocation by excluding
-certain register or value combinations.
+An instruction condition cannot become more restrictive as compilation
+progresses.  If the condition accepts a particular RTL instruction at
+one stage of compilation, it must continue to accept that instruction
+until the final pass.  For example, @samp{!reload_completed} and
+@samp{can_create_pseudo_p ()} are both invalid instruction conditions,
+because they are true during the earlier RTL passes and false during
+the later ones.  For the same reason, if a condition accepts an
+instruction before register allocation, it cannot later try to control
+register allocation by excluding certain register or value combinations.
+
+Although a condition cannot become more restrictive as compilation
+progresses, the condition for a nameless pattern @emph{can} become
+more permissive.  For example, a nameless instruction can require
+@samp{reload_completed} to be true, in which case it only matches
+after register allocation.
 
 @item
 The @dfn{output template} or @dfn{output statement}: This is either
@@ -561,6 +573,11 @@ already defined, then you can simply use @code{#} as the output template
 instead of writing an output template that emits the multiple assembler
 instructions.
 
+Note that @code{#} only has an effect while generating assembly code;
+it does not affect whether a split occurs earlier.  An associated
+@code{define_split} must exist and it must be suitable for use after
+register allocation.
+
 If the macro @code{ASSEMBLER_DIALECT} is defined, you can use construct
 of the form @samp{@{option0|option1|option2@}} in the templates.  These
 describe multiple variants of assembler language syntax.