Clarify define_insn documentation
Richard Sandiford
rdsandiford@googlemail.com
Tue Jun 6 18:55:00 GMT 2017
This patch tries to clarify some of the restrictions on define_insn
conditions, and also on the use of "#".
OK to install?
Richard
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.
Index: gcc/doc/md.texi
===================================================================
--- gcc/doc/md.texi 2017-05-31 10:02:28.617662269 +0100
+++ gcc/doc/md.texi 2017-06-06 19:49:40.453694308 +0100
@@ -115,7 +115,7 @@ A @code{define_insn} is an RTL expressio
@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
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
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.
More information about the Gcc-patches
mailing list