Patchwork [Fortran,RFC] Document naming and argument passing convention

login
register
mail settings
Submitter Tobias Burnus
Date March 29, 2013, 6:42 p.m.
Message ID <5155E090.8020506@net-b.de>
Download mbox | patch
Permalink /patch/232477/
State New
Headers show

Comments

Tobias Burnus - March 29, 2013, 6:42 p.m.
Ups - I attached the wrong patch (same file name, wrong directory). 
Hopefully, this one is the correct one.

Tobias

Am 29.03.2013 19:40, schrieb Tobias Burnus:
> Dear all,
>
> the attached patch attempts to document gfortran's naming and argument 
> passing convention when Bind(C) is not used.
>
> While Bind(C) is the recommended way for interoperation with other 
> Fortran compilers and other languages, there are situations where this 
> is not possible; for instance, legacy code. Or in case of the MPI 
> standard, the MPI implementation might need this information and MPI 
> performance tool developers (PMPI) have to know how the different 
> Fortran compilers pass the arguments.
>
> The attached patch does not (yet) state how array descriptors are 
> handled internally. (I was thinking of deferring this until the new 
> array descriptor becomes available.) I also believe there are other 
> omissions as well and the wording could be improved. Suggestions are 
> welcome.
>
> The patch was motivated by Walter's comment** to my VALUE+OPTIONAL 
> patch.* It takes his comments into account and, that part, only 
> reflects gfortran's implementation after the VALUE+OPTIONAL patch has 
> been committed with his suggested change.
>
> What do you think?
>
> Tobias
>
> * http://gcc.gnu.org/ml/fortran/2013-03/msg00102.html
> ** http://gcc.gnu.org/ml/fortran/2013-03/msg00173.html
Janne Blomqvist - March 30, 2013, 7:14 p.m.
On Fri, Mar 29, 2013 at 8:42 PM, Tobias Burnus <burnus@net-b.de> wrote:
> Ups - I attached the wrong patch (same file name, wrong directory).
> Hopefully, this one is the correct one.
>
> Tobias
>
> Am 29.03.2013 19:40, schrieb Tobias Burnus:
>
>> Dear all,
>>
>> the attached patch attempts to document gfortran's naming and argument
>> passing convention when Bind(C) is not used.
>>
>> While Bind(C) is the recommended way for interoperation with other Fortran
>> compilers and other languages, there are situations where this is not
>> possible; for instance, legacy code. Or in case of the MPI standard, the MPI
>> implementation might need this information and MPI performance tool
>> developers (PMPI) have to know how the different Fortran compilers pass the
>> arguments.
>>
>> The attached patch does not (yet) state how array descriptors are handled
>> internally. (I was thinking of deferring this until the new array descriptor
>> becomes available.) I also believe there are other omissions as well and the
>> wording could be improved. Suggestions are welcome.
>>
>> The patch was motivated by Walter's comment** to my VALUE+OPTIONAL patch.*
>> It takes his comments into account and, that part, only reflects gfortran's
>> implementation after the VALUE+OPTIONAL patch has been committed with his
>> suggested change.
>>
>> What do you think?
>>
>> Tobias
>>
>> * http://gcc.gnu.org/ml/fortran/2013-03/msg00102.html
>> ** http://gcc.gnu.org/ml/fortran/2013-03/msg00173.html

Thanks for the patch! Comments below:

+For logical types, please note that the Fortran standard only guarantees
+interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
+logicals and C99 defines that @code{true} has the value 1 and @code{false}
+the value 0.  In GCC, Boolean variables (Fortran @code{logicals} with and
+without C binding [and for all @code{kind} values], C99's @code{_Bool},
+C++'s @code{bool}, Ada's @code{Boolean}, etc.) all expect that only the
+value 0 and 1 are used; using other values might lead to wrong results.
+Therefore, using @code{logical(kind=c_int)} to interoperate with C99's
+@code{int} is discouraged and should be replaced either by
+@code{integer(kind=c_int)} on the Fortran side (which can then be
+converted to @code{logical}) -- or to use @code{_Bool} and
+@code{logical(kind=c_bool)}. Note that some other (Fortran) compilers
+use a different value for @code{.true.} (e.g. @math{-1}), even with C binding.

This seems to partly repeat what is already said at

http://gcc.gnu.org/onlinedocs/gfortran/Internal-representation-of-LOGICAL-variables.html

IMHO we shouldn't repeat stuff like that; that part might be better
suited as part of the mixed-language programming chapter, if you think
so, please delete the above existing chapter. Or just replace the text
with a short reference to the (updated?) description in the other
chapter, or something like that.

+For procedures and variables declared in the specification space of a
+module, the name is formed by @code{__}, followed by the lower-cased
+module name, @code{_MOD_}, and the lower-cased Fortran name.  Note that
+no underscore is appended.

Would it be worth shortly mentioning the various compiler-generated
symbols (e.g. vtables)? BTW, did the patch that changes all those to
use the "_F" prefix go in, or are we still doing something else?

+Arguments are passed according to the platform ABI. In particular,
+complex arguments may not be compatible to a struct with two real
+components for the real and imaginary part; and complex values are
+returned as result and not by reference.

Here it might be worth mentioning that Fortran complex arguments are
ABI-wise handled like C99 _Complex types.

+For @code{OPTIONAL} dummy arguments, an absent argument is denoted
+by a NUL pointer, except for scalar dummy arguments of type

s/NUL/NULL/
Tobias Burnus - March 30, 2013, 7:50 p.m.
Janne Blomqvist wrote:
> Thanks for the patch! Comments below:
>
> +For logical types, please note that the Fortran standard only guarantees
> +interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
> +logicals and C99 defines that @code{true} has the value 1 and @code{false}
> +the value 0.  In GCC, Boolean variables (Fortran @code{logicals} with and
> +without C binding [and for all @code{kind} values], C99's @code{_Bool},
> +C++'s @code{bool}, Ada's @code{Boolean}, etc.) all expect that only the
> +value 0 and 1 are used; using other values might lead to wrong results.
> +Therefore, using @code{logical(kind=c_int)} to interoperate with C99's
> +@code{int} is discouraged and should be replaced either by
> +@code{integer(kind=c_int)} on the Fortran side (which can then be
> +converted to @code{logical}) -- or to use @code{_Bool} and
> +@code{logical(kind=c_bool)}. Note that some other (Fortran) compilers
> +use a different value for @code{.true.} (e.g. @math{-1}), even with C binding.
>
> This seems to partly repeat what is already said at
> http://gcc.gnu.org/onlinedocs/gfortran/Internal-representation-of-LOGICAL-variables.html
>
> IMHO we shouldn't repeat stuff like that; that part might be better
> suited as part of the mixed-language programming chapter, if you think
> so, please delete the above existing chapter. Or just replace the text
> with a short reference to the (updated?) description in the other
> chapter, or something like that.

I will try to improve this.

> +For procedures and variables declared in the specification space of a
> +module, the name is formed by @code{__}, followed by the lower-cased
> +module name, @code{_MOD_}, and the lower-cased Fortran name.  Note that
> +no underscore is appended.
>
> Would it be worth shortly mentioning the various compiler-generated
> symbols (e.g. vtables)? BTW, did the patch that changes all those to
> use the "_F" prefix go in, or are we still doing something else?

I was thinking of not mentioning the handling of special things like 
ENTRY, alt-returns, compiler-generated virtual tables etc. However, if 
you think that it fits into this chapter, I can add it.

Regarding the _F prefix: Yes, the patch for GFC_PREFIX (_F. or _F$ or 
_F_) went in, but it is (currently) only used to mangle the 
hidden-length variable for the length of deferred-length characters. 
Actually, we should document that one as well.

> +Arguments are passed according to the platform ABI. In particular,
> +complex arguments may not be compatible to a struct with two real
> +components for the real and imaginary part; and complex values are
> +returned as result and not by reference.
>
> Here it might be worth mentioning that Fortran complex arguments are
> ABI-wise handled like C99 _Complex types.

That was what I tried to imply by the platform ABI: The Fortran complex 
is handled like Ada's Complex and C's _Complex, which (at least on 
Alpha) is different to the struct version. However, if it helps, I can 
mention C (and/or Ada and/or Java and/or C++).

> +For @code{OPTIONAL} dummy arguments, an absent argument is denoted
> +by a NUL pointer, except for scalar dummy arguments of type
>
> s/NUL/NULL/

I never now how to write that value. Fortran has null(), C and C++ 
define NULL, C++11 has nullptr, ObjC has nil, ASCII has NUL. And 
internally, the value (void*) 0 is used, i.e. zero.

Tobias
Janne Blomqvist - March 30, 2013, 9:13 p.m.
On Sat, Mar 30, 2013 at 9:50 PM, Tobias Burnus <burnus@net-b.de> wrote:
> Janne Blomqvist wrote:
>> +For procedures and variables declared in the specification space of a
>> +module, the name is formed by @code{__}, followed by the lower-cased
>> +module name, @code{_MOD_}, and the lower-cased Fortran name.  Note that
>> +no underscore is appended.
>>
>> Would it be worth shortly mentioning the various compiler-generated
>> symbols (e.g. vtables)? BTW, did the patch that changes all those to
>> use the "_F" prefix go in, or are we still doing something else?
>
>
> I was thinking of not mentioning the handling of special things like ENTRY,
> alt-returns, compiler-generated virtual tables etc. However, if you think
> that it fits into this chapter, I can add it.
>
> Regarding the _F prefix: Yes, the patch for GFC_PREFIX (_F. or _F$ or _F_)
> went in, but it is (currently) only used to mangle the hidden-length
> variable for the length of deferred-length characters. Actually, we should
> document that one as well.

Hmm, if it's a long laundry list of special cases (ugh.. :( ), then
maybe it's not worth doing..?

>> +Arguments are passed according to the platform ABI. In particular,
>> +complex arguments may not be compatible to a struct with two real
>> +components for the real and imaginary part; and complex values are
>> +returned as result and not by reference.
>>
>> Here it might be worth mentioning that Fortran complex arguments are
>> ABI-wise handled like C99 _Complex types.
>
>
> That was what I tried to imply by the platform ABI: The Fortran complex is
> handled like Ada's Complex and C's _Complex, which (at least on Alpha) is
> different to the struct version. However, if it helps, I can mention C
> (and/or Ada and/or Java and/or C++).

Ah, well, I at least didn't understand that implication, so it might
be useful to clarify it by explicitly mentioning _Complex.

Thanks,

Patch

diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index 4f9008d..b998c8d 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -2204,6 +2204,7 @@  common, but not the former.
 * Interoperability with C::
 * GNU Fortran Compiler Directives::
 * Non-Fortran Main Program::
+* Naming and argument-passing conventions::
 @end menu
 
 This chapter is about mixed-language interoperability, but also applies
@@ -2250,6 +2251,21 @@  in C and Fortran, the named constants shall be used which are defined in the
 for kind parameters and character named constants for the escape sequences
 in C.  For a list of the constants, see @ref{ISO_C_BINDING}.
 
+For logical types, please note that the Fortran standard only guarantees
+interoperability between C99's @code{_Bool} and Fortran's @code{C_Bool}-kind
+logicals and C99 defines that @code{true} has the value 1 and @code{false}
+the value 0.  In GCC, Boolean variables (Fortran @code{logicals} with and
+without C binding [and for all @code{kind} values], C99's @code{_Bool},
+C++'s @code{bool}, Ada's @code{Boolean}, etc.) all expect that only the
+value 0 and 1 are used; using other values might lead to wrong results.
+Therefore, using @code{logical(kind=c_int)} to interoperate with C99's
+@code{int} is discouraged and should be replaced either by
+@code{integer(kind=c_int)} on the Fortran side (which can then be
+converted to @code{logical}) -- or to use @code{_Bool} and
+@code{logical(kind=c_bool)}. Note that some other (Fortran) compilers
+use a different value for @code{.true.} (e.g. @math{-1}), even with C binding.
+
+
 @node Derived Types and struct
 @subsection Derived Types and struct
 
@@ -2975,6 +2991,115 @@  int main (int argc, char *argv[])
 @end table
 
 
+@node Naming and argument-passing conventions
+@section Naming and argument-passing conventions
+
+This section gives an overview about the naming convention of procedures
+and global variables and about the argument passing conventions used by
+GNU Fortran if no C binding has been specified.  If possible, mixed-language
+and mixed-compiled projects should use the better C binding for
+interoperability.  See @pxref{Interoperability with C}.
+
+@menu
+* Naming conventions::
+* Argument passing conventions::
+@end menu
+
+
+@node Naming conventions
+@subsection Naming conventions
+
+According the Fortran standard, valid Fortran names consist of a letter
+between @code{A} to @code{Z}, @code{a} to @code{z}, digits @code{0},
+@code{1} to @code{9} and underscores (@code{_}) with the restriction
+that names may only start with a letter.  As vendor extension, the
+dollar sign (@code{$}) is additionally permitted with the option
+@option{-fdollar-ok}, but not as first character and only if the
+target system supports it.
+
+By default, the procedure name is the lower-cased Fortran name with an
+appended underscore (@code{_}); using @option{-fno-underscoring} no
+underscore is appended while @code{-fsecond-underscore} appends two
+underscores.  Depending on the target system and the calling convention,
+the procedure might be additionally dressed; for instance, on 32bit
+Windows with @code{stdcall}, a at-sign @code{@@} followed by an integer
+number is appended.  For the changing the calling convention, see
+@pxref{GNU Fortran Compiler Directives}.
+
+For common blocks, the same convention is used, i.e. by default an
+underscore is appended to the lower-cased Fortran name.  Blank commons
+have the name @code{__BLNK__}.
+
+For procedures and variables declared in the specification space of a
+module, the name is formed by @code{__}, followed by the lower-cased
+module name, @code{_MOD_}, and the lower-cased Fortran name.  Note that
+no underscore is appended.
+
+
+@node Argument passing conventions
+@subsection Argument passing conventions
+
+GNU Fortran passes most arguments by reference, i.e. by passing a
+pointer to the data.  Note that the compiler might use a temporary
+variable into which the actual argument has been copied, if required
+semantically (copy-in/copy-out).  Using the @code{VALUE} attribute
+for the argument in the procedure interface or, as vendor extension
+and not recommended, using @code{%VAL()} in the call to a procedure,
+the argument is passed by value.
+
+Subroutines do not return a value (matching C99's @code{void}) while
+functions either return a value as specified in the platform ABI or
+the result variable is passed as hidden argument to the function and
+no result is returned.  A hidden result variable is used when the
+result variable is an array or of type @code{CHARACTER}.
+
+Arguments are passed according to the platform ABI. In particular,
+complex arguments may not be compatible to a struct with two real
+components for the real and imaginary part; and complex values are
+returned as result and not by reference.  Note that with the
+@option{-ff2c} option, the argument passing is modified and no
+longer completely matches the platform ABI.  Some other Fortran
+compilers use @code{f2c} semantic by default; this might cause
+problems with interoperablility.  Additionally, GCC expects for
+Boolean variables that only the value 0 and 1 are used.  Passing
+other values to GNU Fortran's @code{LOGICAL} variable might lead
+to wrong results.
+
+For arguments with @code{ALLOCATABLE} and @code{POINTER}
+attribute (including procedure pointers), a pointer to the pointer
+is passed such that the pointer address can be modified in the
+procedure.
+
+For @code{OPTIONAL} dummy arguments, an absent argument is denoted
+by a NUL pointer, except for scalar dummy arguments of type
+@code{INTEGER}, @code{LOGICAL}, @code{REAL} and @code{COMPLEX}
+which have a value attribute.  For the latter, a hidden Boolean
+argument (@code{logical(kind=C_bool),value}) is used to indicate
+whether the argument is present.
+
+For arguments of @code{CHARACTER} type, the character length is passed
+as hidden argument.  For deferred-length strings, the value is passed
+by reference, otherwise by value.  The character length has the type
+@code{INTEGER(kind=4)}.
+
+Arguments which are assumed-shape, assumed-rank or deferred-rank
+arrays or, with @option{-coarray=lib}, allocatable scalar coarrays use
+an array descriptor.  All other arrays are pass the address of the
+first element of the array.
+
+The arguments are passed in the following order
+@itemize @bullet
+@item Result variable, when the function result is passed by reference
+@item Character length of the function result, if it is a of type
+@code{CHARACTER}
+@item The arguments in the order in which they appear in the Fortran
+declaration
+@item The the present status for optional arguments passed internally
+by value
+@item The character lengths
+@end itemize
+
+
 
 @c Intrinsic Procedures
 @c ---------------------------------------------------------------------