From c194537c63180722ea6977000451174f5da1b40b Mon Sep 17 00:00:00 2001 From: Tobias Burnus Date: Thu, 14 Aug 2014 20:35:01 +0200 Subject: [PATCH] gfortran.texi (Coarray Programming): Add first ABI documentation. 2014-08-14 Tobias Burnus * gfortran.texi (Coarray Programming): Add first ABI documentation. From-SVN: r213978 --- gcc/fortran/ChangeLog | 5 + gcc/fortran/gfortran.texi | 375 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 380 insertions(+) diff --git a/gcc/fortran/ChangeLog b/gcc/fortran/ChangeLog index 2c4df3af06d..50fda78f0c4 100644 --- a/gcc/fortran/ChangeLog +++ b/gcc/fortran/ChangeLog @@ -1,3 +1,8 @@ +2014-08-14 Tobias Burnus + + * gfortran.texi (Coarray Programming): Add first ABI + documentation. + 2014-08-14 Jakub Jelinek PR fortran/62076 diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index 66e78e8eef5..5f6bf5d4b6a 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 --------------------------------------------------------------------- -- 2.30.2