[Bug rtl-optimization/33356] New: Incomplete documentation of REG_RETVAL and REG_LIBCALL notes

[steven at gcc dot gnu dot org]

The documentation of REG_RETVAL and REG_LIBCALL notes is incomplete.  The
following additional information should be added to doc/rtl.texi:

1. LIBCALL and RETVAL notes always appear in pairs.
2. Operand 0 the libcall reg note always points to the other note of the pair.
3. Nested pairs of libcall notes are not allowed.

Nested libcalls are not allowed, but there is one pass that is prepared to
handle them anyway, and that is the local const/copy propagation pass in
gcse.c.  A patch for that is attached to Bug 33029
(http://gcc.gnu.org/bugzilla/attachment.cgi?id=14064).

A patch for the documentation is pasted below:

Index: doc/rtl.texi
===================================================================
--- doc/rtl.texi        (revision 128277)
+++ doc/rtl.texi        (working copy)
@@ -3640,13 +3640,16 @@ library call), and @var{op} is the first
 library call, the first insn that was generated to set up the arguments
 for the library call).

-Loop optimization uses this note to treat such a sequence as a single
-operation for code motion purposes and flow analysis uses this note to
-delete such sequences whose results are dead.
+The RTL dead code elimination pass uses this note to delete such
+sequences whose results are dead.

 A @code{REG_EQUAL} note will also usually be attached to this insn to
 provide the expression being computed by the sequence.

+A @code{REG_RETVAL} note always appears in pair with a @code{REG_LIBCALL}
+note.  The first operand of the @code{REG_RETVAL} note is a pointer to
+the @code{REG_LIBCALL} note of the pair.
+
 These notes will be deleted after reload, since they are no longer
 accurate or useful.

@@ -3655,6 +3658,10 @@ accurate or useful.
 This is the inverse of @code{REG_RETVAL}: it is placed on the first
 insn of a multi-insn sequence, and it points to the last one.

+A @code{REG_LIBCALL} note always appears in pair with a @code{REG_LIBCALL}
+note.  The first operand of the @code{REG_LIBCALL} note is a pointer to
+the @code{REG_RETVAL} note of the pair.
+
 These notes are deleted after reload, since they are no longer useful or
 accurate.


-- 
           Summary: Incomplete documentation of REG_RETVAL and REG_LIBCALL
                    notes
           Product: gcc
           Version: 4.3.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: rtl-optimization
        AssignedTo: unassigned at gcc dot gnu dot org
        ReportedBy: steven at gcc dot gnu dot org
 BugsThisDependsOn: 33029


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33356