From patchwork Sun Jul 27 14:03:10 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Tobias Burnus X-Patchwork-Id: 374033 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.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 7EE121400FA for ; Mon, 28 Jul 2014 00:03:31 +1000 (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:content-type; q= dns; s=default; b=IqVLIuWP+sM07guUb9Bk0eZHyfPHvrJpubbElLHCD5/8mk Whlz7BNiEJivTIGxIgXr9psolaHy9g3ZABNE+qASVFvS6PBNa8KIyIwEKsWh8Egj 8ASDYdgPYfem4+8PoUhTRNBkhZzVDI+I4wXGOaaroWci98EgVJLJGFDYcr3m0= 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:content-type; s= default; bh=26VwvhYOiH4Cehi1102IYfOmDeA=; b=jc1A3fQRESF+jcjc0a9L 5JacN4UZ1Retab3RC/ec0E2BawFjt9wL9Y6zgAgnM8Mg4dikiN51UiGU0QGzt7Q/ sASeWC4Yg/nzCqcn0m384VSx4AH4aKWd3i0uHiJFOv2B8MNoQ3I+oky6w5qQnGFQ KUf2rPv0ji+PODM50AFybTM= Received: (qmail 20652 invoked by alias); 27 Jul 2014 14:03:23 -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 20625 invoked by uid 89); 27 Jul 2014 14:03:20 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.0 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.2 X-Spam-User: qpsmtpd, 2 recipients X-HELO: mx02.qsc.de Received: from mx02.qsc.de (HELO mx02.qsc.de) (213.148.130.14) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES256-SHA encrypted) ESMTPS; Sun, 27 Jul 2014 14:03:15 +0000 Received: from tux.net-b.de (port-92-194-213-151.dynamic.qsc.de [92.194.213.151]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mx02.qsc.de (Postfix) with ESMTPSA id 5C5802767B; Sun, 27 Jul 2014 16:03:11 +0200 (CEST) Message-ID: <53D5069E.7090907@net-b.de> Date: Sun, 27 Jul 2014 16:03:10 +0200 From: Tobias Burnus User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 MIME-Version: 1.0 To: gcc-patches , gfortran Subject: [Patch, Fortran] Add first coarray ABI documentation to gfortran.texi Dear all, attached is a first patch to gfortran.texi which add documentation about libcaf*.c. The things are still a bit in a flux and it is incomplete (atomics, locking, error stop and vector subscripts are still missing), but one has to start somewhere … OK for the trunk? Comments on the language, the technical description and on the API itself are welcome. Tobias 2014-07-27 Tobias Burnus * gfortran.texi (Coarray Programming): Add first ABI documentation. diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index 66e78e8..5f6bf5d 100644 --- a/gcc/fortran/gfortran.texi +++ b/gcc/fortran/gfortran.texi @@ -184,6 +184,7 @@ Part II: Language Reference * Compiler Characteristics:: User-visible implementation details. * Extensions:: Language extensions implemented by GNU Fortran. * Mixed-Language Programming:: Interoperability with C +* Coarray Programming:: * Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran. * Intrinsic Modules:: Intrinsic modules supported by GNU Fortran. @@ -3176,6 +3177,380 @@ of such a type @end itemize +@c --------------------------------------------------------------------- +@c Coarray Programming +@c --------------------------------------------------------------------- + +@node Coarray Programming +@chapter Coarray Programming +@cindex Coarrays + +@menu +* Type and enum ABI Documentation:: +* Function ABI Documentation:: +@end menu + + +@node Type and enum ABI Documentation +@section Type and enum ABI Documentation + +@menu +* caf_token_t:: +* caf_register_t:: +@end menu + +@node caf_token_t +@subsection @code{caf_token_t} + +Typedef of type @code{void *} on the compiler side. Can be any data +type on the library side. + +@node caf_register_t +@subsection @code{caf_register_t} + +Indicates which kind of coarray variable should be registered. + +@verbatim +typedef enum caf_register_t { + CAF_REGTYPE_COARRAY_STATIC, + CAF_REGTYPE_COARRAY_ALLOC, + CAF_REGTYPE_LOCK_STATIC, + CAF_REGTYPE_LOCK_ALLOC +} +caf_register_t; +@end verbatim + + +@node Function ABI Documentation +@section Function ABI Documentation + +@menu +* _gfortran_caf_init:: Initialiation function +* _gfortran_caf_finish:: Finalization function +* _gfortran_caf_this_image:: Querying the image number +* _gfortran_caf_num_images:: Querying the maximal number of images +* _gfortran_caf_register:: Registering coarrays +* _gfortran_caf_deregister:: Deregistering coarrays +* _gfortran_caf_send:: Sending data from a local image to a remote image +* _gfortran_caf_get:: Getting data from a remote image +* _gfortran_caf_sendget:: Sending data between remote images +@end menu + + +@node _gfortran_caf_init +@subsection @code{_gfortran_caf_init} --- Initialiation function +@cindex Coarray, _gfortran_caf_init + +@table @asis +@item @emph{Description}: +This function is called at startup of the program before the Fortran main +program, if the latter has been compiled with @option{-fcoarray=lib}. +It takes as arguments the command-line arguments of the program. It is +permitted to pass to @code{NULL} pointers as argument; if non-@code{NULL}, +the library is permitted to modify the arguments. + +@item @emph{Syntax}: +@code{void _gfortran_caf_init (int *argc, char ***argv)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{argc} @tab intent(inout) An integer pointer with the number of +arguments passed to the program or @code{NULL}. +@item @var{argv} @tab intent(inout) A pointer to an array of strings with the +command-line arguments or @code{NULL}. +@end multitable + +@item @emph{NOTES} +The function is modelled after the initialization function of the Message +Passing Interface (MPI) specification. Due to the way coarray registration +works, it might not be the first call to the libaray. If the main program is +not written in Fortran and only a library uses coarrays, it can happen that +this function is never called. Therefore, it is recommended that the library +does not rely on the passed arguments and whether the call has been done. +@end table + + +@node _gfortran_caf_finish +@subsection @code{_gfortran_caf_finish} --- Finalization function +@cindex Coarray, _gfortran_caf_finish + +@table @asis +@item @emph{Description}: +This function is called at the end of the Fortran main program, if it has +been compiled with the @option{-fcoarray=lib} option. + +@item @emph{Syntax}: +@code{void _gfortran_caf_finish (void)} + +@item @emph{NOTES} +For non-Fortran programs, it is recommended to call the function at the end +of the main program. To ensure that the shutdown is also performed for +programs where this function is not explicitly invoked, for instance +non-Fortran programs or calls to the system's exit() function, the library +can use a destructor function. Note that programs can also be terminated +using the STOP and ERROR STOP statements; those use different library calls. +@end table + + +@node _gfortran_caf_this_image +@subsection @code{_gfortran_caf_this_image} --- Querying the image number +@cindex Coarray, _gfortran_caf_this_image + +@table @asis +@item @emph{Description}: +This function returns the current image number, which is a positive number. + +@item @emph{Syntax}: +@code{int _gfortran_caf_this_image (int distance)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{distance} @tab As specified for the @code{this_image} intrinsic +in TS18508. Shall be a nonnegative number. +@end multitable + +@item @emph{NOTES} +If the Fortran intrinsic @code{this_image} is invoked without an argument, which +is the only permitted form in Fortran 2008, GCC passes @code{0} as +first argument. +@end table + + +@node _gfortran_caf_num_images +@subsection @code{_gfortran_caf_num_images} --- Querying the maximal number of images +@cindex Coarray, _gfortran_caf_num_images + +@table @asis +@item @emph{Description}: +This function returns the number of images in the current team, if +@var{distance} is 0 or the number of images in the parent team at the specified +distance. If failed is -1, the function returns the number of all images at +the specified distance; if it is 0, the function returns the number of +nonfailed images, and if it is 1, it returns the number of failed images. + +@item @emph{Syntax}: +@code{int _gfortran_caf_num_images(int distance, int failed)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{distance} @tab the distance from this image to the ancestor. +Shall be positive. +@item @var{failed} @tab shall be -1, 0, or 1 +@end multitable + +@item @emph{NOTES} +This function follows TS18508. If the num_image intrinsic has no arguments, +the the compiler passes @code{distance=0} and @code{failed=-1} to the function. +@end table + + +@node _gfortran_caf_register +@subsection @code{_gfortran_caf_register} --- Registering coarrays +@cindex Coarray, _gfortran_caf_deregister + +@table @asis +@item @emph{Description}: +Allocates memory for a coarray and creates a token to identify the coarray. The +function is called for both coarrays with @code{SAVE} attribute and using an +explicit @code{ALLOCATE} statement. If an error occurs and @var{STAT} is a +@code{NULL} pointer, the function shall abort with printing an error message +and starting the error termination. If no error occurs and @var{STAT} is +present, it shall be set to zero. Otherwise, it shall be set to a positive +value and, if not-@code{NULL}, @var{ERRMSG} shall be set to a string describing +the failure. The function shall return a pointer to the requested memory +for the local image as a call to @code{malloc} would do. + +@item @emph{Syntax}: +@code{void *caf_register (size_t size, caf_register_t type, caf_token_t *token, +int *stat, char *errmsg, int errmsg_len)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{size} @tab byte size of the coarray to be allocated +@item @var{type} @tab one of the caf_register_t types. +@item @var{token} @tab intent(out) An opaque pointer identifying the coarray. +@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be NULL +@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to an error message; may be NULL +@item @var{errmsg_len} @tab the buffer size of errmsg. +@end multitable + +@item @emph{NOTES} +Nonalloatable coarrays have to be registered prior use from remote images. +In order to guarantee this, they have to be registered before the main +program. This can be achieved by creating constructor functions. That is what +GCC does such that also nonallocatable coarrays the memory is allocated and no +static memory is used. The token permits to identify the coarray; to the +processor, the token is a nonaliasing pointer. The library can, for instance, +store the base address of the coarray in the token, some handle or a more +complicated struct. +@end table + + +@node _gfortran_caf_deregister +@subsection @code{_gfortran_caf_deregister} --- Deregistering coarrays +@cindex Coarray, _gfortran_caf_deregister + +@table @asis +@item @emph{Description}: +Called to free the memory of a coarray; the processor calls this function for +automatic and explicit deallocation. In case of an error, this function shall +fail with an error message, unless the @var{STAT} variable is not null. + +@item @emph{Syntax}: +@code{void caf_deregister (const caf_token_t *token, int *stat, char *errmsg, +int errmsg_len)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be NULL +@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to an error message; may be NULL +@item @var{errmsg_len} @tab the buffer size of errmsg. +@end multitable + +@item @emph{NOTES} +For nonalloatable coarrays this function is never called. If a cleanup is +required, it has to be handled via the finish, stop and error stop functions, +and via destructors. +@end table + + +@node _gfortran_caf_send +@subsection @code{_gfortran_caf_send} --- Sending data from a local image to a remote image +@cindex Coarray, _gfortran_caf_send + +@table @asis +@item @emph{Description}: +Called to send a scalar, an array section or whole array from a local +to a remote image identified by the image_index. + +@item @emph{Syntax}: +@code{void _gfortran_caf_send (caf_token_t token, size_t offset, +int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, +gfc_descriptor_t *src, int dst_kind, int src_kind)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. +@item @var{offset} @tab By which amount of bytes the actual data is shifted +compared to the base address of the coarray. +@item @var{image_index} @tab The ID of the remote image; must be a positive +number. +@item @var{dest} @tab intent(in) Array descriptor for the remote image for the +bounds and the size. The base_addr shall not be accessed. +@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector +subscript of the destination array; the values are relative to the dimension +triplet of the dest argument. +@item @var{src} @tab intent(in) Array descriptor of the local array to be +transferred to the remote image +@item @var{dst_kind} @tab Kind of the destination argument +@item @var{src_kind} @tab Kind of the source argument +@end multitable + +@item @emph{NOTES} +It is permitted to have image_id equal the current image; the memory of the +send-to and the send-from might (partially) overlap in that case. The +implementation has to take care that it handles this case. Note that the +assignment of a scalar to an array is permitted. In addition, the library has +to handle numeric-type conversion and for strings, padding and different +character kinds. +@end table + + +@node _gfortran_caf_get +@subsection @code{_gfortran_caf_get} --- Getting data from a remote image +@cindex Coarray, _gfortran_caf_get + +@table @asis +@item @emph{Description}: +Called to get an array section or whole array from a a remote, +image identified by the image_index. + +@item @emph{Syntax}: +@code{void _gfortran_caf_get_desc (caf_token_t token, size_t offset, +int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector, +gfc_descriptor_t *dest, int src_kind, int dst_kind)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{token} @tab intent(in) An opaque pointer identifying the coarray. +@item @var{offset} @tab By which amount of bytes the actual data is shifted +compared to the base address of the coarray. +@item @var{image_index} @tab The ID of the remote image; must be a positive +number. +@item @var{dest} @tab intent(in) Array descriptor of the local array to be +transferred to the remote image +@item @var{src} @tab intent(in) Array descriptor for the remote image for the +bounds and the size. The base_addr shall not be accessed. +@item @var{src_vector} @tab intent(int) If not NULL, it contains the vector +subscript of the destination array; the values are relative to the dimension +triplet of the dest argument. +@item @var{dst_kind} @tab Kind of the destination argument +@item @var{src_kind} @tab Kind of the source argument +@end multitable + +@item @emph{NOTES} +It is permitted to have image_id equal the current image; the memory of the +send-to and the send-from might (partially) overlap in that case. The +implementation has to take care that it handles this case. Note that the +library has to handle numeric-type conversion and for strings, padding +and different character kinds. +@end table + + +@node _gfortran_caf_sendget +@subsection @code{_gfortran_caf_sendget} --- Sending data between remote images +@cindex Coarray, _gfortran_caf_sendget + +@table @asis +@item @emph{Description}: +Called to send a scalar, an array section or whole array from a remote image +identified by the src_image_index to a remote image identified by the +dst_image_index. + +@item @emph{Syntax}: +@code{void _gfortran_caf_sendget (caf_token_t dst_token, size_t dst_offset, +int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, +caf_token_t src_token, size_t src_offset, int src_image_index, +gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind)} + +@item @emph{Arguments}: +@multitable @columnfractions .15 .70 +@item @var{dst_token} @tab intent(in) An opaque pointer identifying the +destination coarray. +@item @var{dst_offset} @tab By which amount of bytes the actual data is +shifted compared to the base address of the destination coarray. +@item @var{dst_image_index} @tab The ID of the destination remote image; must +be a positive number. +@item @var{dst_dest} @tab intent(in) Array descriptor for the destination +remote image for the bounds and the size. The base_addr shall not be accessed. +@item @var{dst_vector} @tab intent(int) If not NULL, it contains the vector +subscript of the destination array; the values are relative to the dimension +triplet of the dest argument. +@item @var{src_token} @tab An opaque pointer identifying the source coarray. +@item @var{src_offset} @tab By which amount of bytes the actual data is shifted +compared to the base address of the source coarray. +@item @var{src_image_index} @tab The ID of the source remote image; must be a +positive number. +@item @var{src_dest} @tab intent(in) Array descriptor of the local array to be +transferred to the remote image. +@item @var{src_vector} @tab intent(in) Array descriptor of the local array to +be transferred to the remote image +@item @var{dst_kind} @tab Kind of the destination argument +@item @var{src_kind} @tab Kind of the source argument +@end multitable + +@item @emph{NOTES} +It is permitted to have image_id equal the current image; the memory of the +send-to and the send-from might (partially) overlap in that case. The +implementation has to take care that it handles this case. Note that the +assignment of a scalar to an array is permitted. In addition, the library has +to handle numeric-type conversion and for strings, padding and different +character kinds. +@end table + + + + @c Intrinsic Procedures @c ---------------------------------------------------------------------