[Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Tobias Burnus]

[-- Attachment #1: Type: text/plain, Size: 246 bytes --]

This patch completes the description of the coarray library functions, 
invoked for -fcoarray=lib.

OK for the trunk?

(The currently documented functions can be seen at 
https://gcc.gnu.org/onlinedocs/gfortran/Coarray-Programming.html )

Tobias

[-- Attachment #2: cafabi.diff --]
[-- Type: text/x-patch, Size: 14751 bytes --]


	* gfortran.texi (_gfortran_caf_sync_all, _gfortran_caf_sync_images,
	_gfortran_caf_sync_memory, _gfortran_caf_error_stop,
	_gfortran_caf_error_stop_str, _gfortran_caf_atomic_define,
	_gfortran_caf_atomic_ref, _gfortran_caf_atomic_cas,
	_gfortran_caf_atomic_op): New sections.

diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index 300b8b8..9819f51 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -3297,6 +3297,15 @@ caf_register_t;
 * _gfortran_caf_sendget:: Sending data between remote images
 * _gfortran_caf_lock:: Locking a lock variable
 * _gfortran_caf_unlock:: Unlocking a lock variable
+* _gfortran_caf_sync_all:: All-image barrier
+* _gfortran_caf_sync_images:: Barrier for selected images
+* _gfortran_caf_sync_memory:: Wait for completion of segment-memory operations
+* _gfortran_caf_error_stop:: Error termination with exit code
+* _gfortran_caf_error_stop_str:: Error termination with string
+* _gfortran_caf_atomic_define:: Atomic variable assignment
+* _gfortran_caf_atomic_ref:: Atomic variable reference
+* _gfortran_caf_atomic_cas:: Atomic compare and swap
+* _gfortran_caf_atomic_op:: Atomic operation
 * _gfortran_caf_co_broadcast:: Sending data to all images
 * _gfortran_caf_co_max:: Collective maximum reduction
 * _gfortran_caf_co_min:: Collective minimum reduction
@@ -3743,6 +3752,270 @@ images for critical-block locking variables.
 @end table
 
 
+@node _gfortran_caf_sync_all
+@subsection @code{_gfortran_caf_sync_all} --- All-image barrier
+@cindex Coarray, _gfortran_caf_sync_all
+
+@table @asis
+@item @emph{Description}:
+Synchronization of all images in the current team; the program only continues
+on a given image after this function has been called on all images of the
+current team.  Additionally, it ensures that all pending data transfers of
+previous segment have completed.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_sync_all (int *stat, char *errmsg, int errmsg_len)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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
+@end table
+
+
+
+@node _gfortran_caf_sync_images
+@subsection @code{_gfortran_caf_sync_images} --- Barrier for selected images
+@cindex Coarray, _gfortran_caf_sync_images
+
+@table @asis
+@item @emph{Description}:
+Synchronization between the specified images; the program only continues on a
+given image after this function has been called on all images specified for
+that image. Note that one image can wait for all other images in the current
+team (e.g. via @code{sync images(*)}) while those only wait for that specific
+image.  Additionally, @code{sync images} it ensures that all pending data
+transfers of previous segment have completed.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_sync_images (int count, int images[], int *stat,
+char *errmsg, int errmsg_len)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{count} @tab the number of images which are provided in the next
+argument.  For a zero-sized array, the value is zero.  For @code{sync
+images (*)}, the value is @math{-1}.
+@item @var{images} @tab intent(in) an array with the images provided by the
+user. If @var{count} is zero, a NULL pointer is passed.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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
+@end table
+
+
+
+@node _gfortran_caf_sync_memory
+@subsection @code{_gfortran_caf_sync_memory} --- Wait for completion of segment-memory operations
+@cindex Coarray, _gfortran_caf_sync_memory
+
+@table @asis
+@item @emph{Description}:
+Acts as optimization barrier between different segments. It also ensures that
+all pending memory operations of this image have been completed.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_sync_memory (int *stat, char *errmsg, int errmsg_len)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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{NOTE} A simple implementation could be a simple @code{__asm__
+__volatile__ ("":::"memory)} to prevent code movements.
+@end table
+
+
+
+@node _gfortran_caf_error_stop
+@subsection @code{_gfortran_caf_error_stop} --- Error termination with exit code
+@cindex Coarray, _gfortran_caf_error_stop
+
+@table @asis
+@item @emph{Description}:
+Invoked for an @code{ERROR STOP} statement which has an integer argument.  The
+function should terminate the program with the specified exit code.
+
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_error_stop (int32_t error)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{error} @tab the exit status to be used.
+@end multitable
+@end table
+
+
+
+@node _gfortran_caf_error_stop_str
+@subsection @code{_gfortran_caf_error_stop_str} --- Error termination with string
+@cindex Coarray, _gfortran_caf_error_stop_str
+
+@table @asis
+@item @emph{Description}:
+Invoked for an @code{ERROR STOP} statement which has a string as argument.  The
+function should terminate the program with a nonzero-exit code.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_error_stop (const char *string, int32_t len)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{string} @tab the error message (not zero terminated)
+@item @var{len} @tab the length of the string
+@end multitable
+@end table
+
+
+
+@node _gfortran_caf_atomic_define
+@subsection @code{_gfortran_caf_atomic_define} --- Atomic variable assignment
+@cindex Coarray, _gfortran_caf_atomic_define
+
+@table @asis
+@item @emph{Description}:
+Assign atomically a value to an integer or logical variable.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_atomic_define (caf_token_t token, size_t offset,
+int image_index, void *value, int *stat, int type, int 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{value} @tab intent(in) the value to be assigned, passed by reference.
+@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
+@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
+@code{BT_LOGICAL} (2).
+@item @var{kind} @tab The kind value (only 4; always @code{int})
+@end multitable
+@end table
+
+
+
+@node _gfortran_caf_atomic_ref
+@subsection @code{_gfortran_caf_atomic_ref} --- Atomic variable reference
+@cindex Coarray, _gfortran_caf_atomic_ref
+
+@table @asis
+@item @emph{Description}:
+Reference atomically a value of a kind-4 integer or logical variable.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_atomic_ref (caf_token_t token, size_t offset,
+int image_index, void *value, int *stat, int type, int kind)}
+
+@item @emph{Arguments}:
+@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{value} @tab intent(out) The variable assigned the atomically
+referenced variable.
+@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
+@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
+@code{BT_LOGICAL} (2).
+@item @var{kind} @tab The kind value (only 4; always @code{int})
+@end multitable
+@end table
+
+
+
+@node _gfortran_caf_atomic_cas
+@subsection @code{_gfortran_caf_atomic_cas} --- Atomic compare and swap
+@cindex Coarray, _gfortran_caf_atomic_cas
+
+@table @asis
+@item @emph{Description}:
+Atomic compare and swap of a kind-4 integer or logical variable. Assigns
+atomically the specified value to the atomic variable, if the latter has
+the value specified by the passed condition value.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_atomic_cas (caf_token_t token, size_t offset,
+int image_index, void *old, void *compare, void *new_val, int *stat,
+int type, int 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{old} @tab intent(out) the value which the atomic variable had
+just before the cas operation.
+@item @var{compare} @tab intent(in) The value used for comparision.
+@item @var{new_val} @tab intent(in) The new value for the atomic variable,
+assigned to the atomic variable, if @code{compare} equals the value of the
+atomic variable.
+@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
+@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
+@code{BT_LOGICAL} (2).
+@item @var{kind} @tab The kind value (only 4; always @code{int})
+@end multitable
+@end table
+
+
+
+@node _gfortran_caf_atomic_op
+@subsection @code{_gfortran_caf_atomic_op} --- Atomic operation
+@cindex Coarray, _gfortran_caf_atomic_op
+
+@table @asis
+@item @emph{Description}:
+Apply an operation atomically to an atomic integer or logical variable.
+After the operation, @var{old} contains the value just before the operation,
+which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the @code{value} to
+the atomic integer variable or does a bitwise AND, OR or exclusive OR of the
+between the atomic variable and @var{value}; the result is then stored in the
+atomic variable.
+
+@item @emph{Syntax}:
+@code{void _gfortran_caf_atomic_op (int op, caf_token_t token, size_t offset,
+int image_index, void *value, void *old, int *stat, int type, int kind)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{op} @tab the operation to be performed; possible values
+@code{GFC_CAF_ATOMIC_ADD} (1), @code{GFC_CAF_ATOMIC_AND} (2),
+@code{GFC_CAF_ATOMIC_OR} (3), @code{GFC_CAF_ATOMIC_XOR} (4).
+@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{old} @tab intent(out) the value which the atomic variable had
+just before the atomic operation.
+@item @var{val} @tab intent(in) The new value for the atomic variable,
+assigned to the atomic variable, if @code{compare} equals the value of the
+atomic variable.
+@item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL.
+@item @var{type} @tab the data type, i.e. @code{BT_INTEGER} (1) or
+@code{BT_LOGICAL} (2).
+@item @var{kind} @tab The kind value (only 4; always @code{int})
+@end multitable
+@end table
+
+
+
 
 @node _gfortran_caf_co_broadcast
 @subsection @code{_gfortran_caf_co_broadcast} --- Sending data to all images
@@ -3763,7 +4036,7 @@ int source_image, int *stat, char *errmsg, int errmsg_len)}
 breoadcasted (on @var{source_image}) or to be received (other images).
 @item @var{source_image} @tab The ID of the image from which the data should
 be taken.
-@item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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.
@@ -3794,7 +4067,7 @@ int *stat, char *errmsg, int a_len, int errmsg_len)}
 breoadcasted (on @var{source_image}) or to be received (other images).
 @item @var{result_image} @tab The ID of the image to which the reduced
 value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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{a_len} @tab The string length of argument @var{a}.
@@ -3830,7 +4103,7 @@ int *stat, char *errmsg, int a_len, int errmsg_len)}
 breoadcasted (on @var{source_image}) or to be received (other images).
 @item @var{result_image} @tab The ID of the image to which the reduced
 value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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{a_len} @tab The string length of argument @var{a}.
@@ -3865,7 +4138,7 @@ int *stat, char *errmsg, int errmsg_len)}
 breoadcasted (on @var{source_image}) or to be received (other images).
 @item @var{result_image} @tab The ID of the image to which the reduced
 value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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.
@@ -3911,7 +4184,7 @@ int *stat, char *errmsg, int a_len, int errmsg_len)}
 breoadcasted (on @var{source_image}) or to be received (other images).
 @item @var{result_image} @tab The ID of the image to which the reduced
 value should be copied to; if zero, it has to be copied to all images.
-@item @var{stat} @tab intent(out) Stores the status STAT= and my may be NULL.
+@item @var{stat} @tab intent(out) Stores the status STAT= and 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{a_len} @tab The string length of argument @var{a}.

Re: [Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Jerry DeLisle]

On 03/10/2015 02:59 PM, Tobias Burnus wrote:
> This patch completes the description of the coarray library functions, invoked
> for -fcoarray=lib.
>
> OK for the trunk?
>
> (The currently documented functions can be seen at
> https://gcc.gnu.org/onlinedocs/gfortran/Coarray-Programming.html )
>
> Tobias

OK, thanks.

Jerry

Re: [Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Tobias Burnus]

[-- Attachment #1: Type: text/plain, Size: 183 bytes --]

Dear Iain,

Iain Sandoe wrote:
> a couple of minor nits that Dominique and I spotted while discussing 
> this :

Thanks for the suggestion. I've committed it as Rev. 221615.

Tobias


[-- Attachment #2: committed.diff --]
[-- Type: text/x-patch, Size: 1007 bytes --]

Index: gcc/fortran/ChangeLog
===================================================================
--- gcc/fortran/ChangeLog	(Revision 221614)
+++ gcc/fortran/ChangeLog	(Arbeitskopie)
@@ -1,3 +1,8 @@
+2015-03-24  Iain Sandoe  <iain@codesourcery.com>
+	    Tobias Burnus  <burnus@net-b.de>
+
+	* gfortran.texi (_gfortran_caf_sync_memory): Improve wording.
+
 2015-03-23  Paul Thomas  <pault@gcc.gnu.org>
 	    Mikael Morin  <mikael@gcc.gnu.org>
 
Index: gcc/fortran/gfortran.texi
===================================================================
--- gcc/fortran/gfortran.texi	(Revision 221614)
+++ gcc/fortran/gfortran.texi	(Arbeitskopie)
@@ -3860,8 +3860,8 @@
 @item @var{errmsg_len} @tab the buffer size of errmsg.
 @end multitable
 
-@item @emph{NOTE} A simple implementation could be a simple
-@code{__asm__ __volatile__ ("":::"memory)} to prevent code movements.
+@item @emph{NOTE} A simple implementation could be
+@code{__asm__ __volatile__ ("":::"memory")} to prevent code movements.
 @end table
 
 

Re: [Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Iain Sandoe]

Dear Tobias,

On 21 Mar 2015, at 14:28, H.J. Lu wrote:

> On Sat, Mar 21, 2015 at 6:19 AM, Dominique Dhumieres <dominiq@lps.ens.fr> wrote:

a couple of minor nits that Dominique and I spotted while discussing this : 

> -@item @emph{NOTE} A simple implementation could be a simple @code{__asm__

maybe  
"A simple implementation could be "
... would read more smoothly?

> -__volatile__ ("":::"memory)} to prevent code movements.
> +@item @emph{NOTE} A simple implementation could be a simple
> +@code{__asm__ __volatile__ ("":::"memory)} to prevent code movements.
> @end table

also:
@code{__asm__ __volatile__ ("":::"memory)} <= seems to be missing a quotation mark.
i.e. __asm__ __volatile__ ("" ::: "memory")

I wonder if the latter was somehow confusing the newer edition of texinfo?
cheers,
Iain

Re: [Patch, Fortran] Extend (lib)coarray API/ABI documentation

[H.J. Lu]

On Sat, Mar 21, 2015 at 6:19 AM, Dominique Dhumieres <dominiq@lps.ens.fr> wrote:
> Dear Tobias,
>
> Revision r221550 break bootstrap on platforms with recent makeinfo (mine is 5.2):
> see https://gcc.gnu.org/ml/gcc-regression/2015-03/. The error is
>
> ../../work/gcc/fortran/gfortran.texi:3850: @code missing close brace
> ../../work/gcc/fortran/gfortran.texi:3851: misplaced }
> ../../work/gcc/fortran/Make-lang.in:185: recipe for target 'doc/gfortran.info' failed
>
> and is fixed with the following patch
>
> --- ../_clean/gcc/fortran/gfortran.texi 2015-03-21 10:40:46.000000000 +0100
> +++ gcc/fortran/gfortran.texi   2015-03-21 11:27:20.000000000 +0100
> @@ -3847,8 +3847,8 @@ an error message; may be NULL
>  @item @var{errmsg_len} @tab the buffer size of errmsg.
>  @end multitable
>
> -@item @emph{NOTE} A simple implementation could be a simple @code{__asm__
> -__volatile__ ("":::"memory)} to prevent code movements.
> +@item @emph{NOTE} A simple implementation could be a simple
> +@code{__asm__ __volatile__ ("":::"memory)} to prevent code movements.
>  @end table
>

I checked in this to restore gcc build.


-- 
H.J.
---
Index: ChangeLog
===================================================================
--- ChangeLog (revision 221551)
+++ ChangeLog (working copy)
@@ -1,3 +1,8 @@
+2015-03-21  H.J. Lu  <hongjiu.lu@intel.com>
+
+ * gfortran.texi (_gfortran_caf_sync_memory): Put @{xxx} in one
+ line.
+
 2015-03-21  Tobias Burnus  <burnus@net-b.de>

  * gfortran.texi (_gfortran_caf_sync_all, _gfortran_caf_sync_images,
Index: gfortran.texi
===================================================================
--- gfortran.texi (revision 221551)
+++ gfortran.texi (working copy)
@@ -3847,8 +3847,8 @@
 @item @var{errmsg_len} @tab the buffer size of errmsg.
 @end multitable

-@item @emph{NOTE} A simple implementation could be a simple @code{__asm__
-__volatile__ ("":::"memory)} to prevent code movements.
+@item @emph{NOTE} A simple implementation could be a simple
+@code{__asm__ __volatile__ ("":::"memory)} to prevent code movements.
 @end table

Re: [Patch, Fortran] Extend (lib)coarray API/ABI documentation

[Dominique Dhumieres]

Dear Tobias,

Revision r221550 break bootstrap on platforms with recent makeinfo (mine is 5.2):
see https://gcc.gnu.org/ml/gcc-regression/2015-03/. The error is

../../work/gcc/fortran/gfortran.texi:3850: @code missing close brace
../../work/gcc/fortran/gfortran.texi:3851: misplaced }
../../work/gcc/fortran/Make-lang.in:185: recipe for target 'doc/gfortran.info' failed

and is fixed with the following patch

--- ../_clean/gcc/fortran/gfortran.texi	2015-03-21 10:40:46.000000000 +0100
+++ gcc/fortran/gfortran.texi	2015-03-21 11:27:20.000000000 +0100
@@ -3847,8 +3847,8 @@ an error message; may be NULL
 @item @var{errmsg_len} @tab the buffer size of errmsg.
 @end multitable
 
-@item @emph{NOTE} A simple implementation could be a simple @code{__asm__
-__volatile__ ("":::"memory)} to prevent code movements.
+@item @emph{NOTE} A simple implementation could be a simple 
+@code{__asm__ __volatile__ ("":::"memory)} to prevent code movements.
 @end table
 
 
TIA

Dominiq