Re: [Patch] libgomp.texi: Document omp_pause_resource{,_all} and omp_target_memcpy* (was: [Patch] libgomp.texi: Document omp_pause_resource{,_all})

[Sandra Loosemore <sandra.loosemore@siemens.com>]

On 1/14/24 16:15, Tobias Burnus wrote:

> +@node omp_target_memcpy
> +@subsection @code{omp_target_memcpy} -- Copy data between devices
> +@table @asis
> +@item @emph{Description}:
> +This routine tests copies @var{length} of bytes of data from the device
> +identified by device number @var{src_device_num} to device @var{dst_device_num}.

Hmmm, I'm sure it's the train's fault :-) but "tests copies" makes no sense, 
and that's cut-and-pasted multiple times.  I think you just mean "copies" in 
all cases.

> +@node omp_target_memcpy_rect
> +@subsection @code{omp_target_memcpy_rect} -- Copy a subvolume of data between devices
> +@table @asis
> +@item @emph{Description}:
> +This routine tests copies a subvolume of data from the device identified by
> +device number @var{src_device_num} to device @var{dst_device_num}.  The
> +subvolume of a multi-dimensional array of array dimension @var{num_dims} and
> +each array element has a size of @var{element_size} bytes.  The @var{volume}

This is kind of garbled.  How about rephrasing that second sentence as

The array has @var{num_dims} and each array element has a size of 
@var{element_size} bytes.


> +array specifies how many elements per dimension will be copied.  The full

s/will be/are/

> +array in number of elements is given by the @var{dst_dimensions} and
> +@var{src_dimensions} arguments for the array on the destination and source
> +device, respectively.  The offset per dimension to the first element to

I think we can simplify that sentence, too, like

The full sizes of the destination and source arrays are given by the 
@var{dst_dimensions} and @var{src_dimensions} arguments, respectively.

> +be copied is given by the @var{dst_offset} and @var{src_offset} arguments.
> +The routine returns zero on success and non-zero otherwise.
> +
> +The OpenMP only requires that @var{num_dims} up to three is supported. In order

s/OpenMP/OpenMP specification/ ?

> +to find implementation-specific maximally supported number of dimensions, the
> +routine will return this value when invoked with a NULL pointer to both the

s/will return/returns/

either "null pointer" or "@code{NULL}" is preferable to "NULL pointer".

> +@var{dst} and @var{src} arguments.  As GCC supports arbitrary dimensions, it
> +will return INTMAX.

s/will return INTMAX/returns @code{INT_MAX}/

> +
> +The device-number arguments must be conforming device number, the @var{src} and

s/number,/numbers,/


> +@var{dst} must be either both NULL or any of the following must be fulfilled:

same issue with "NULL" here, either "@code{NULL}" or "null pointers".

"any" seems unlikely to be useful.  Do you mean "all" of the following conditions?

> +@var{element_size} and @var{num_dims} must be positive, the @var{volume}, offset
> +and dimension arrays must have at least @var{num_dims} dimensions.
> +Running this routine in a @code{target} region except on the initial device
> +is not supported.

The part of the patch for omp_target_memcpy_rect_async has very similar 
problems and needs the same fixes.

-Sandra