[Patch, Fortran] Add first coarray ABI documentation to gfortran.texi

[Tobias Burnus <burnus at net-b dot de>]

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  <burnus@net-b.de>

	* 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 ---------------------------------------------------------------------