[PATCH] Clarify the documentation for the ms_abi function attribute

[PATCH] Clarify the documentation for the ms_abi function attribute

[Peter Jones]

Somewhere in the process of writing the documentation for the ms_abi
function attribute, there has been some (justifiable) confusion about
which calling conventions are which, and the documentation currently
states that on non-Windows x86 targets we default to the "x86/AMD ABI".

In the past I've heard "the AMD calling conventions" used to refer to
the Microsoft parameter passing register usage, so I looked it up.  As
far as I can tell, AMD does not specify *any* calling conventions for
the 64-bit x86 instruction set.  The only times the AMD64 documentation
refers to calling conventions or parameter passing are in a general
introduction of PUSHA and ENTER, which do not implement a relevant part
of either convention, and a section about saving SSE state when passing
YMM/XMM register values as arguments.

This patch changes the documentation to explicitly refer to either the
"Microsoft ABI" or the "System V ELF ABI".

Signed-off-by: Peter Jones <pjones@redhat.com>
---
 ChangeLog           | 5 +++++
 gcc/doc/extend.texi | 7 ++++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index b0239316868..691d4cd619c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2020-09-10  Peter Jones  <pjones@redhat.com>
+
+	* gcc/doc/extend.texi: Clarify the documentation for the ms_abi
+	function attribute
+
 2020-08-26  Tobias Burnus  <tobias@codesourcery.com>
 
 	* MAINTAINERS (Various Maintainers): Add myself as OpenACC maintainer.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 3b37aba5795..8ac4dad390f 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -6069,9 +6069,10 @@ and for static member methods.
 On 32-bit and 64-bit x86 targets, you can use an ABI attribute
 to indicate which calling convention should be used for a function.  The
 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI,
-while the @code{sysv_abi} attribute tells the compiler to use the ABI
-used on GNU/Linux and other systems.  The default is to use the Microsoft ABI
-when targeting Windows.  On all other systems, the default is the x86/AMD ABI.
+while the @code{sysv_abi} attribute tells the compiler to use the System V
+ELF ABI, which is used on GNU/Linux and other systems.  The default is to use
+the Microsoft ABI when targeting Windows.  On all other systems, the default
+is the System V ELF ABI.
 
 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently
 requires the @option{-maccumulate-outgoing-args} option.
-- 
2.26.2

Re: [PATCH] Clarify the documentation for the ms_abi function attribute

[Jeff Law]

On 9/10/20 11:04 AM, Peter Jones via Gcc-patches wrote:
> Somewhere in the process of writing the documentation for the ms_abi
> function attribute, there has been some (justifiable) confusion about
> which calling conventions are which, and the documentation currently
> states that on non-Windows x86 targets we default to the "x86/AMD ABI".
>
> In the past I've heard "the AMD calling conventions" used to refer to
> the Microsoft parameter passing register usage, so I looked it up.  As
> far as I can tell, AMD does not specify *any* calling conventions for
> the 64-bit x86 instruction set.  The only times the AMD64 documentation
> refers to calling conventions or parameter passing are in a general
> introduction of PUSHA and ENTER, which do not implement a relevant part
> of either convention, and a section about saving SSE state when passing
> YMM/XMM register values as arguments.
>
> This patch changes the documentation to explicitly refer to either the
> "Microsoft ABI" or the "System V ELF ABI".
>
> Signed-off-by: Peter Jones <pjones@redhat.com>
> ---
>  ChangeLog           | 5 +++++
>  gcc/doc/extend.texi | 7 ++++---
>  2 files changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/ChangeLog b/ChangeLog
> index b0239316868..691d4cd619c 100644
> --- a/ChangeLog
> +++ b/ChangeLog
> @@ -1,3 +1,8 @@
> +2020-09-10  Peter Jones  <pjones@redhat.com>
> +
> +	* gcc/doc/extend.texi: Clarify the documentation for the ms_abi
> +	function attribute

Thanks.  I've pushed this to the trunk.  Sorry for the delays.


jeff