Re: [Fortran] RFC: Patch to support STDCALL etc. (PR 34112)

[Steve Kargl <sgk at troutmask dot apl dot washington dot edu>]

On Sat, Jun 20, 2009 at 12:17:15AM +0200, Tobias Burnus wrote:
> Attached is the first version of a patch which allows to use
> 
> !GCC$ ATTRIBUTES attribute :: symbol-list
> 
> where attribute is one of:
> - CDECL
> - STDCALL
> - FASTCALL
> - DLLEXPORT
> - DLLIMPORT
> 

Tobias,

Here's some further comments on the manual page.

-- 
steve


Index: gcc/fortran/gfortran.texi
===================================================================
--- gcc/fortran/gfortran.texi	(Revision 148690)
+++ gcc/fortran/gfortran.texi	(Arbeitskopie)
@@ -1851,6 +1851,7 @@ c
 
 @menu
 * Interoperability with C::
+* Attributes such as STDCALL::

Intel's 'Programmer's Manual' refers to the '!DEC$' as a compiler
directive.  How about changing the title of this section to 

'GNU Fortran Compiler Directives'

This would avoid possible confusion with the Fortran meaning of
an attribute.  To connect with the GCC manual's use of attribute,
we can add something along the lines:  "The GCC manual refers
to compiler directives as attributes.  To distinguish between
the usual Fortran use of attribute, the GNU Fortran manual uses
the term directive."

 * Non-Fortran Main Program::
 @end menu
 
@@ -2097,6 +2098,56 @@ C-interoperable @code{OPTIONAL} and for
 dummy arguments. However, the TR has neither been approved nor implemented
 in GNU Fortran; therefore, these features are not yet available.
 
+
+@node Attributes such as STDCALL
+@section Attributes such as STDCALL

See above for a suggested change.

+The Fortran standard -- as the C standard -- describe how a conforming

Delete '-- as the C standard --'

+program shall behave; however, the exact implementation is not
+standarized. In order to allow the user to choose the implementation
+choices, attributes were invented which can be used for functions
+and variables. However, not only the suported attributes but also the

s/suported/supported

+syntax is compiler-dependent. GNU Fortran currently supports for
+procedures and procedure pointers the following calling-conventions
+attributes

I find the above paragraph very confusing.  Perhaps, the confusion
stems from my familiarity with Fortran attributes such as ALLOCATABLE,
POINTER, PARAMETER, etc.  If I guess at your intent with this paragraph,
you're trying to convey that the Fortran Standard does not specify
how a Fortran processor converts source code into something that
can be executed (i.e., does not specify the calling convention).   

+
+@itemize
+@item @code{CDECL} -- standard C calling convention
+@item @code{STDCALL} -- convention where the called procedure pops the stack
+@item @code{FASTCALL} -- part of the arguments are passed via registers
+instead using the stack
+@end itemize
+
+Besides changing the calling convention, the attributes also ensure that
+the symbols are properly decorated, e.g. by a leading underscore or by

s/e.g./e.g.,

+a trailing at-sign followed by the number of bytes on the stack. It is
+recommended to use the default calling convention of the system. When
+assigning a procedure to a procedure pointer, both should have the same
+calling convention. Note: The effect of the option is target dependent
+(processor and operating system). For details,
+@ref{Top,,gcc,C Extensions,Function Attributes}).

The last ')' seems to be mismatched.  I'd suggest simply

For details see
@ref{Top,,gcc,C Extensions,Function Attributes}.

+
+Additionally, for procedures and for global variables (module variables
+and @code{COMMON} blocks), the following attributes are supported
+
+@itemize
+@item @code{DLLEXPORT}
+@item @code{DLLIMPORT}
+@end itemize
+
+For details, @ref{Top,,gcc,C Extensions,Variable Attributes}.

s/,/ see/

+
+The attributes are specified using the syntax
+
+@code{!GNU$ ATTRIBUTES} @var{attribute} @code{::} @var{variable-list}
+
+where in free-form Fortran only whitespace is allowed before @code{!GNU$}

s/Fortran/source code/

The use of the word 'only' seems out of place.

+and in fixed-form Fortran @code{!GNU$}, @code{cGNU$} or @code{*GNU$} shall

s/Fortran/source code/

+start in the first column. The procedure attributes have to be specified
+in the associated procedure body, the variable attributes in the same
+declaration part
+

Missing a period.