Hello,
The existing documentation for SEQUENCE still states it is used for
DEFINE_EXPAND sequences. I think I wasn't even hacking GCC when that
practice was abandoned, and in the mean time some other uses of
SEQUENCE have appeared in the compiler. So, a long-overdue
documentation update.
OK for trunk?
Ciao!
Steven
* doc/rtl.texi (sequence): Rewrite documentation to match the
current use of SEQUENCE rtl objects.
* rtl.def (SEQUENCE): Likewise.
Index: doc/rtl.texi
===================================================================
--- doc/rtl.texi (revision 197532)
+++ doc/rtl.texi (working copy)
@@ -3099,18 +3099,11 @@ side-effects.
@findex sequence
@item (sequence [@var{insns} @dots{}])
-Represents a sequence of insns. Each of the @var{insns} that appears
-in the vector is suitable for appearing in the chain of insns, so it
-must be an @code{insn}, @code{jump_insn}, @code{call_insn},
-@code{code_label}, @code{barrier} or @code{note}.
+Represents a sequence of insns. If a @code{sequence} appears in the
+chain of insns, then each of the @var{insns} that appears in the sequence
+must be suitable for appearing in the chain of insns, i.e. must satisfy
+the @code{INSN_P} predicate.
-A @code{sequence} RTX is never placed in an actual insn during RTL
-generation. It represents the sequence of insns that result from a
-@code{define_expand} @emph{before} those insns are passed to
-@code{emit_insn} to insert them in the chain of insns. When actually
-inserted, the individual sub-insns are separated out and the
-@code{sequence} is forgotten.
-
After delay-slot scheduling is completed, an insn and all the insns that
reside in its delay slots are grouped together into a @code{sequence}.
The insn requiring the delay slot is the first insn in the vector;
@@ -3123,6 +3116,19 @@ the effect of the insns in the delay slots. In su
the branch and should be executed only if the branch is taken; otherwise
the insn should be executed only if the branch is not taken.
@xref{Delay Slots}.
+
+Some back ends also use @code{sequence} objects for purposes other than
+delay-slot groups. This is not supported in the common parts of the
+compiler, which treat such sequences as delay-slot groups.
+
+DWARF2 Call Frame Address (CFA) adjustments are sometimes also expressed
+using @code{sequence} objects as the value of a @code{RTX_FRAME_RELATED_P}
+note. This only happens if the CFA adjustments cannot be easily derived
+from the pattern of the instruction to which the note is attached. In
+such cases, the value of the note is used instead of best-guesing the
+semantics of the instruction. The back end can attach notes containing
+a @code{sequence} of @code{set} patterns that express the effect of the
+parent instruction.
@end table
These expression codes appear in place of a side effect, as the body of
Index: rtl.def
===================================================================
--- rtl.def (revision 197533)
+++ rtl.def (working copy)
@@ -102,10 +102,24 @@ DEF_RTL_EXPR(EXPR_LIST, "expr_list", "ee", RTX_EXT
The insns are represented in print by their uids. */
DEF_RTL_EXPR(INSN_LIST, "insn_list", "ue", RTX_EXTRA)
-/* SEQUENCE appears in the result of a `gen_...' function
- for a DEFINE_EXPAND that wants to make several insns.
- Its elements are the bodies of the insns that should be made.
- `emit_insn' takes the SEQUENCE apart and makes separate insns. */
+/* SEQUENCE is used in late passes of the compiler to group insns for
+ one reason or another.
+
+ For example, after delay slot filling, branch instructions with filled
+ delay slots are represented as a SEQUENCE of length 1 + n_delay_slots,
+ with the branch instruction in XEXPVEC(seq, 0, 0) and the instructions
+ occupying the delay slots in the remaining XEXPVEC slots.
+
+ Another place where a SEQUENCE may appear, is in REG_FRAME_RELATED_EXPR
+ notes, to express complex operations that are not obvious from the insn
+ to which the REG_FRAME_RELATED_EXPR note is attached. In this usage of
+ SEQUENCE, the sequence vector slots do not hold real instructions but
+ only pseudo-instructions that can be translated to DWARF CFA expressions.
+
+ Some back ends also use SEQUENCE to group insns in bundles.
+
+ Much of the compiler infrastructure is not prepared to handle SEQUENCE
+ objects. Only passes after pass_free_cfg are expected to handle them. */
DEF_RTL_EXPR(SEQUENCE, "sequence", "E", RTX_EXTRA)
/* Represents a non-global base address. This is only used in alias.c. */
