From patchwork Fri Mar 29 18:42:24 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 232477 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (Client CN "localhost", Issuer "www.qmailtoaster.com" (not verified)) by ozlabs.org (Postfix) with ESMTPS id 30BA72C00B1 for ; Sat, 30 Mar 2013 05:43:18 +1100 (EST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:subject:references :in-reply-to:content-type; q=dns; s=default; b=Jr87XciUr0MYk1QhZ 5dENmiXLqKh+lJoUjtZaKoxvqhRdHr0ExzYRx96o871uG0bTcphr1KdFjFALxfm5 nlcf3wVEc8XC3YZI/eB5aF3bQGqWjxrQTsbPXirpaaxkhW+va0eJ29HrifnzQiQn Ijbzh4v3+TQKkjtnaDNfqCDwMA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=gcc.gnu.org; h=list-id :list-unsubscribe:list-archive:list-post:list-help:sender :message-id:date:from:mime-version:to:subject:references :in-reply-to:content-type; s=default; bh=71kyoaPoDfCY/SKR/Ta2EQ6 +En4=; b=VWf7+Hnz5hmVADvdM98zxeriWDPDnJiE3ZG2YRreoP8TMVh1LSVKP+3 aS7JNuVrGeaN2Yxo8OPpvDaTOvBVW1gj92R1cvV3aaUBJyFFhAvcEEFAmZE1C/B3 aC9GB5ZNHdal0P/+EKJsYV2aWKCc53jOeC4W0IuM5X5EVbfGBZJA= Received: (qmail 18826 invoked by alias); 29 Mar 2013 18:42:43 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Delivered-To: mailing list gcc-patches@gcc.gnu.org Received: (qmail 18592 invoked by uid 89); 29 Mar 2013 18:42:35 -0000 X-Spam-SWARE-Status: No, score=-2.9 required=5.0 tests=AWL, BAYES_00, KHOP_THREADED, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 X-Spam-User: qpsmtpd, 2 recipients Received: from mx01.qsc.de (HELO mx01.qsc.de) (213.148.129.14) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 29 Mar 2013 18:42:28 +0000 Received: from archimedes.net-b.de (port-92-195-88-1.dynamic.qsc.de [92.195.88.1]) by mx01.qsc.de (Postfix) with ESMTP id D91B03CE6E; Fri, 29 Mar 2013 19:42:24 +0100 (CET) Message-ID: <5155E090.8020506@net-b.de> Date: Fri, 29 Mar 2013 19:42:24 +0100 From: Tobias Burnus User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130307 Thunderbird/17.0.4 MIME-Version: 1.0 To: gcc patches , gfortran Subject: Re: [Fortran, RFC patch] Document naming and argument passing convention References: <5155E015.6010600@net-b.de> In-Reply-To: <5155E015.6010600@net-b.de> X-Virus-Found: No 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 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 ---------------------------------------------------------------------