[PATCH 5/6]: Ping: Merge from Stack Branch - Document changes

["Ye, Joey" <joey dot ye at intel dot com>]

Jan, 

Can you please review for mainline?

2008-04-28  H.J. Lu  <hongjiu.lu@intel.com>

	* doc/extend.texi: Update force_align_arg_pointer.
	* doc/invoke.texi: Document -mincoming-stack-boundary.  Update
	-mstackrealign.

Index: doc/extend.texi
===================================================================
--- doc/extend.texi	(revision 134716)
+++ doc/extend.texi	(working copy)
@@ -2727,17 +2727,13 @@ floating point arguments on the stack.
 
 @item force_align_arg_pointer
 @cindex @code{force_align_arg_pointer} attribute
-On the Intel x86, the @code{force_align_arg_pointer} attribute may be
-applied to individual function definitions, generating an alternate
-prologue and epilogue that realigns the runtime stack.  This supports
-mixing legacy codes that run with a 4-byte aligned stack with modern
-codes that keep a 16-byte stack for SSE compatibility.  The alternate
-prologue and epilogue are slower and bigger than the regular ones, and
-the alternate prologue requires a scratch register; this lowers the
-number of registers available if used in conjunction with the
-@code{regparm} attribute.  The @code{force_align_arg_pointer}
-attribute is incompatible with nested functions; this is considered a
-hard error.
+The @code{force_align_arg_pointer} attribute may be applied to
+individual function definitions, assuming that the runtime stack is
+aligned according to the psABI and generating an alternate
+prologue/epilogue that realigns the runtime stack if necessary. 
+On the Intel x86, this supports mixing codes that keep a 4-byte aligned
+stack, as specified by i386 psABI, with codes that need a 16-byte
+aligned stack, as required by SSE instructions. 
 
 @item resbank
 @cindex @code{resbank} attribute
Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi	(revision 134716)
+++ doc/invoke.texi	(working copy)
@@ -553,7 +553,9 @@ Objective-C and Objective-C++ Dialects}.
 -masm=@var{dialect}  -mno-fancy-math-387 @gol
 -mno-fp-ret-in-387  -msoft-float @gol
 -mno-wide-multiply  -mrtd  -malign-double @gol
--mpreferred-stack-boundary=@var{num} -mcx16 -msahf -mrecip @gol
+-mpreferred-stack-boundary=@var{num}
+-mincoming-stack-boundary=@var{num}
+-mcx16 -msahf -mrecip @gol
 -mmmx  -msse  -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 @gol
 -maes -mpclmul @gol
 -msse4a -m3dnow -mpopcnt -mabm -msse5 @gol
@@ -10682,18 +10684,14 @@ when this option is used to set the prec
 
 @item -mstackrealign
 @opindex mstackrealign
-Realign the stack at entry.  On the Intel x86, the
-@option{-mstackrealign} option will generate an alternate prologue and
-epilogue that realigns the runtime stack.  This supports mixing legacy
-codes that keep a 4-byte aligned stack with modern codes that keep a
-16-byte stack for SSE compatibility.  The alternate prologue and
-epilogue are slower and bigger than the regular ones, and the
-alternate prologue requires an extra scratch register; this lowers the
-number of registers available if used in conjunction with the
-@code{regparm} attribute.  The @option{-mstackrealign} option is
-incompatible with the nested function prologue; this is considered a
-hard error.  See also the attribute @code{force_align_arg_pointer},
-applicable to individual functions.
+Realign the stack at entry.  The @option{-mstackrealign} option will
+assume that the runtime stack is aligned according to the psABI and
+generate an alternate prologue/epilogue that realigns the runtime stack
+if necessary.  On the Intel x86, this supports mixing codes that keep a
+4-byte aligned stack, as specified by i386 psABI, with codes that need
+a 16-byte aligned stack, as required by SSE instructions.  See also the
+attribute @code{force_align_arg_pointer}, applicable to individual
+functions.
 
 @item -mpreferred-stack-boundary=@var{num}
 @opindex mpreferred-stack-boundary
@@ -10701,6 +10699,12 @@ Attempt to keep the stack boundary align
 byte boundary.  If @option{-mpreferred-stack-boundary} is not
specified,
 the default is 4 (16 bytes or 128 bits).
 
+@item -mincoming-stack-boundary=@var{num}
+@opindex mincoming-stack-boundary
+Assume the incoming stack is aligned to a 2 raised to @var{num} byte
+boundary.  If @option{-mincoming-stack-boundary} is not specified,
+the one specified by @option{-mpreferred-stack-boundary} will be used.
+
 On Pentium and PentiumPro, @code{double} and @code{long double} values
 should be aligned to an 8 byte boundary (see @option{-malign-double})
or
 suffer significant run time performance penalties.  On Pentium III, the