| Message ID | 5155E090.8020506@net-b.de |
|---|---|
| State | New |
| Headers | show |
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/
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
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,
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 ---------------------------------------------------------------------