On Fri, Jun 22, 2012 at 10:11 AM, Jan Hubicka <hubi...@ucw.cz> wrote:
>> >>> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> >>> index 4c5c79f..daa1f3a 100644
>> >>> --- a/gcc/doc/invoke.texi
>> >>> +++ b/gcc/doc/invoke.texi
>> >>> @@ -13521,6 +13521,12 @@ Attempt to keep the stack boundary aligned to a
>> >>> 2 raised to @var{num}
>> >>> byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
>> >>> the default is 4 (16 bytes or 128 bits).
>> >>>
>> >>> +@strong{Warning:} When generating code for the x86-64 architecture with
>> >>> +SSE extensions disabled, @option{-mpreferred-stack-boundary=3} can be
>> >>> +used to keep the stack boundary aligned to 8 byte boundary. You must
>> >>> +build all modules with @option{-mpreferred-stack-boundary=3}, including
>> >>> +any libraries. This includes the system libraries and startup modules.
>
> I would suggest to re-word this paragraph.
> Perhaps something along lines
>
> x86-64 ABI require 16 byte stack alignment. It is possible to compile code
> with
> -mpreferred-stack-boundary=3 where stack alignment is 8 bytes only. This is
> ABI incompatible and intended to be used in controlled environment where stack
> space is important limitation. It may lead to wrong code when functions
> compiled with 16 byte stack alignment (such as functions from a standard
> library) are called with misaligned stack. In this case the of SSE registers
> may lead to misaligned memory access traps. In addition, va-arg will
> incorrectly handle 16 byte aligned objects (including x87 long double and
> __int128) leading to wrong results rather than traps.
>
> Fell free to fix my english and extend it. I just want to make it sure
> that the paragraph explains how things break (i.e. by calling something
> with default stack alignment from function with 8byte alignment.) and that
> it can break for non-SSE code, too, when using va-args on 16 byte aligned
> objects.
>
> The patch is fine with this change. Please also add change to news.html with
> similar explanation.
>
Here is the patch for invoke.texi. OK to install?
I will prepare a similar one for news.html.
Thanks.
--
H.J.
---
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 029a7ab..87e0d1c 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -13579,9 +13579,18 @@ the default is 4 (16 bytes or 128 bits).
@strong{Warning:} When generating code for the x86-64 architecture with
SSE extensions disabled, @option{-mpreferred-stack-boundary=3} can be
-used to keep the stack boundary aligned to 8 byte boundary. You must
-build all modules with @option{-mpreferred-stack-boundary=3}, including
-any libraries. This includes the system libraries and startup modules.
+used to keep the stack boundary aligned to 8 byte boundary. Since
+x86-64 ABI require 16 byte stack alignment, this is ABI incompatible and
+intended to be used in controlled environment where stack space is
+important limitation. This option will lead to wrong code when functions
+compiled with 16 byte stack alignment (such as functions from a standard
+library) are called with misaligned stack. In this case, SSE
+instructions may lead to misaligned memory access traps. In addition,
+variable arguments will be handled incorrectly for 16 byte aligned
+objects (including x87 long double and __int128), leading to wrong
+results. You must build all modules with
+@option{-mpreferred-stack-boundary=3}, including any libraries. This
+includes the system libraries and startup modules.
@item -mincoming-stack-boundary=@var{num}
@opindex mincoming-stack-boundary
