emit-rtl.c (start_sequence): Expand comments.

	* emit-rtl.c (start_sequence): Expand comments.
	(start_sequence_for_rtl_expr): Likewise.
	(push_to_sequence): Likewise.
	(end_sequence): Likewise.
	* expr.c (inhibit_defer_pop): Likewise.
	* expr.h (inhibit_defer_pop): Likewise.
	(NO_DEFER_POP): Likewise.
	(OK_DEFER_POP): Likewise.

From-SVN: r26704

gcc/ChangeLog

+Thu Apr 29 23:02:22 1999  Mark Mitchell  <mark@codesourcery.com>
+
+	* emit-rtl.c (start_sequence): Expand comments.
+	(start_sequence_for_rtl_expr): Likewise.
+	(push_to_sequence): Likewise.
+	(end_sequence): Likewise.
+	* expr.c (inhibit_defer_pop): Likewise.
+	* expr.h (inhibit_defer_pop): Likewise.
+	(NO_DEFER_POP): Likewise.
+	(OK_DEFER_POP): Likewise.
+
 Thu Apr 29 22:13:46 1999  Robert Lipe  <robertlipe@usa.net>
 
 	* configure.in (i?86-UnixWare7*-sysv): Set thread_file to 'posix'

gcc/emit-rtl.c

@@ -3284,7 +3284,13 @@ emit (x)
     abort ();
 }
 
-/* Begin emitting insns to a sequence which can be packaged in an RTL_EXPR.  */
+/* Begin emitting insns to a sequence which can be packaged in an
+   RTL_EXPR.  If this sequence will contain something that might cause
+   the compiler to pop arguments to function calls (because those
+   pops have previously been deferred; see INHIBIT_DEFER_POP for more
+   details), use do_pending_stack_adjust before calling this function.
+   That will ensure that the deferred pops are not accidentally
+   emitted in the middel of this sequence.  */
 
 void
 start_sequence ()
@@ -3311,8 +3317,9 @@ start_sequence ()
   last_insn = 0;
 }
 
-/* Similarly, but indicate that this sequence will be placed in 
-   T, an RTL_EXPR.  */
+/* Similarly, but indicate that this sequence will be placed in T, an
+   RTL_EXPR.  See the documentation for start_sequence for more
+   information about how to use this function.  */
 
 void
 start_sequence_for_rtl_expr (t)
@@ -3323,8 +3330,9 @@ start_sequence_for_rtl_expr (t)
   sequence_rtl_expr = t;
 }
 
-/* Set up the insn chain starting with FIRST
-   as the current sequence, saving the previously current one.  */
+/* Set up the insn chain starting with FIRST as the current sequence,
+   saving the previously current one.  See the documentation for
+   start_sequence for more information about how to use this function.  */
 
 void
 push_to_sequence (first)
@@ -3378,8 +3386,16 @@ pop_topmost_sequence ()
 
 /* After emitting to a sequence, restore previous saved state.
 
-   To get the contents of the sequence just made,
-   you must call `gen_sequence' *before* calling here.  */
+   To get the contents of the sequence just made, you must call
+   `gen_sequence' *before* calling here.  
+
+   If the compiler might have deferred popping arguments while
+   generating this sequence, and this sequence will not be immediately
+   inserted into the instruction stream, use do_pending_stack_adjust
+   before calling gen_sequence.  That will ensure that the deferred
+   pops are inserted into this sequence, and not into some random
+   location in the instruction stream.  See INHIBIT_DEFER_POP for more
+   information about deferred popping of arguments.  */
 
 void
 end_sequence ()

gcc/expr.c

@@ -87,10 +87,21 @@ int do_preexpand_calls = 1;
    These are the arguments to function calls that have already returned.  */
 int pending_stack_adjust;
 
-/* Nonzero means stack pops must not be deferred, and deferred stack
-   pops must not be output.  It is nonzero inside a function call,
-   inside a conditional expression, inside a statement expression,
-   and in other cases as well.  */
+/* Under some ABIs, it is the caller's responsibility to pop arguments
+   pushed for function calls.  A naive implementation would simply pop
+   the arguments immediately after each call.  However, if several
+   function calls are made in a row, it is typically cheaper to pop
+   all the arguments after all of the calls are complete since a
+   single pop instruction can be used.  Therefore, GCC attempts to
+   defer popping the arguments until absolutely necessary.  (For
+   example, at the end of a conditional, the arguments must be popped,
+   since code outside the conditional won't know whether or not the
+   arguments need to be popped.)
+
+   When INHIBIT_DEFER_POP is non-zero, however, the compiler does not
+   attempt to defer pops.  Instead, the stack is popped immediately
+   after each call.  Rather then setting this variable directly, use
+   NO_DEFER_POP and OK_DEFER_POP.  */
 int inhibit_defer_pop;
 
 /* Nonzero means __builtin_saveregs has already been done in this function.

gcc/expr.h

@@ -95,12 +95,31 @@ extern rtx current_function_internal_arg_pointer;
    function.  */
 extern int current_function_check_memory_usage;
 
-/* Nonzero means stack pops must not be deferred, and deferred stack
-   pops must not be output.  It is nonzero inside a function call,
-   inside a conditional expression, inside a statement expression,
-   and in other cases as well.  */
+/* Under some ABIs, it is the caller's responsibility to pop arguments
+   pushed for function calls.  A naive implementation would simply pop
+   the arguments immediately after each call.  However, if several
+   function calls are made in a row, it is typically cheaper to pop
+   all the arguments after all of the calls are complete since a
+   single pop instruction can be used.  Therefore, GCC attempts to
+   defer popping the arguments until absolutely necessary.  (For
+   example, at the end of a conditional, the arguments must be popped,
+   since code outside the conditional won't know whether or not the
+   arguments need to be popped.)
+
+   When INHIBIT_DEFER_POP is non-zero, however, the compiler does not
+   attempt to defer pops.  Instead, the stack is popped immediately
+   after each call.  Rather then setting this variable directly, use
+   NO_DEFER_POP and OK_DEFER_POP.  */
 extern int inhibit_defer_pop;
 
+/* Prevent the compiler from deferring stack pops.  See
+   inhibit_defer_pop for more information.  */
+#define NO_DEFER_POP (inhibit_defer_pop += 1)
+
+/* Allow the compiler to defer stack pops.  See inhibit_defer_pop for
+   more information.  */
+#define OK_DEFER_POP (inhibit_defer_pop -= 1)
+
 /* Number of function calls seen so far in current function.  */
 
 extern int function_call_count;
@@ -126,9 +145,6 @@ extern rtx nonlocal_goto_stack_level;
 extern tree nonlocal_labels;
 #endif
 
-#define NO_DEFER_POP (inhibit_defer_pop += 1)
-#define OK_DEFER_POP (inhibit_defer_pop -= 1)
-
 /* Number of units that we should eventually pop off the stack.
    These are the arguments to function calls that have already returned.  */
 extern int pending_stack_adjust;