update documentation for SEQUENCE

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.

On Sun, Apr 7, 2013 at 12:04 AM, Steven Bosscher <stevenb.gcc@gmail.com> wrote:
> 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?

Ok.

Thanks,
Richard.

> 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.  */

On Mon, Apr 8, 2013 at 11:30 AM, Richard Biener wrote:
> On Sun, Apr 7, 2013 at 12:04 AM, Steven Bosscher wrote:
>> 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?
>
> Ok.

Thanks, I'm committing this along with something else I noticed:
NOTE_INSN_LOOP notes don't exist anymore, and NOTE_INSN_EH_REGION
notes don't have NOTE_BLOCK_NUMBER anymore but do have
so-far-undocumented NOTE_EH_HANDLER.

@@ -3602,29 +3608,9 @@ of debugging information.
 @item NOTE_INSN_EH_REGION_BEG
 @itemx NOTE_INSN_EH_REGION_END
 These types of notes indicate the position of the beginning and end of a
-level of scoping for exception handling.  @code{NOTE_BLOCK_NUMBER}
-identifies which @code{CODE_LABEL} or @code{note} of type
-@code{NOTE_INSN_DELETED_LABEL} is associated with the given region.
+level of scoping for exception handling.  @code{NOTE_EH_HANDLER}
+identifies which region is associated with these notes.

-@findex NOTE_INSN_LOOP_BEG
-@findex NOTE_INSN_LOOP_END
-@item NOTE_INSN_LOOP_BEG
-@itemx NOTE_INSN_LOOP_END
-These types of notes indicate the position of the beginning and end
-of a @code{while} or @code{for} loop.  They enable the loop optimizer
-to find loops quickly.
-
-@findex NOTE_INSN_LOOP_CONT
-@item NOTE_INSN_LOOP_CONT
-Appears at the place in a loop that @code{continue} statements jump to.
-
-@findex NOTE_INSN_LOOP_VTOP
-@item NOTE_INSN_LOOP_VTOP
-This note indicates the place in a loop where the exit test begins for
-those loops in which the exit test has been duplicated.  This position
-becomes another virtual start of the loop when considering loop
-invariants.
-
 @findex NOTE_INSN_FUNCTION_BEG
 @item NOTE_INSN_FUNCTION_BEG
 Appears at the start of the function body, after the function