I recently stumbled over omp_get_default_device returning -1 (=
omp_initial_device)
vs. returning omp_get_num_devices(). Thus, it makes sense to document this
properly.
I also updated some wording and made a tiny step to documenting the missing
functions
by adding a title to the commented @menu items.
→ https://gcc.gnu.org/onlinedocs/libgomp/#toc-OpenMP-Runtime-Library-Routines
for the current wording.
Comments or suggestions before I commit it?
Tobias
libgomp.texi: Update 'Device Information Routines' section
Update 'OpenMP Runtime Library Routines' by adding a note that invoking
inside a target region might invoke unspecified behavior. Additionally,
update omp_{get,set}_default_device for omp_{initial,invalid}_device
named constants.
libgomp/ChangeLog:
* libgomp.texi (OpenMP Runtime Library Routines): Add missing
title to some commented still undocumented items.
(Device Information Routines): Update.
libgomp/libgomp.texi | 48 +++++++++++++++++++++++++++++++++---------------
1 file changed, 33 insertions(+), 15 deletions(-)
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 50da248b74d..8fe74d58562 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -1208,11 +1208,11 @@ They have C linkage and do not throw exceptions.
@menu
* omp_get_proc_bind:: Whether threads may be moved between CPUs
-@c * omp_get_num_places:: <fixme>
-@c * omp_get_place_num_procs:: <fixme>
-@c * omp_get_place_proc_ids:: <fixme>
-@c * omp_get_place_num:: <fixme>
-@c * omp_get_partition_num_places:: <fixme>
+@c * omp_get_num_places:: Get the number of places available
+@c * omp_get_place_num_procs:: Get the number of processes associated with a place
+@c * omp_get_place_proc_ids:: Get number of processes associated with a place
+@c * omp_get_place_num:: Get place number of the associated task
+@c * omp_get_partition_num_places:: Get number of places of innermost task
@c * omp_get_partition_place_nums:: <fixme>
@c * omp_set_affinity_format:: <fixme>
@c * omp_get_affinity_format:: <fixme>
@@ -1627,8 +1627,12 @@ Returns the number of processors online on that device.
@subsection @code{omp_set_default_device} -- Set the default device for target regions
@table @asis
@item @emph{Description}:
-Set the default device for target regions without device clause. The argument
-shall be a nonnegative device number.
+Get the value of the @emph{default-device-var} ICV, which is used
+for target regions without device clause. The argument
+shall be a nonnegative device number, @code{omp_initial_device},
+or @code{omp_invalid_device}.
+
+The effect of running this routine in a @code{target} region is unspecified.
@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@@ -1654,7 +1658,15 @@ shall be a nonnegative device number.
@subsection @code{omp_get_default_device} -- Get the default device for target regions
@table @asis
@item @emph{Description}:
-Get the default device for target regions without device clause.
+Get the value of the @emph{default-device-var} ICV, which is used
+for target regions without device clause. The value is either a
+nonnegative device number, @code{omp_initial_device} or
+@code{omp_invalid_device}. Note that for the host, the ICV can have two values
+and, hence, this routine might return either the value of the named constant
+@code{omp_initial_device} or the value returned by the
+@code{omp_get_initial_device} routine.
+
+The effect of running this routine in a @code{target} region is unspecified.
@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@@ -1667,7 +1679,8 @@ Get the default device for target regions without device clause.
@end multitable
@item @emph{See also}:
-@ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device}
+@ref{OMP_DEFAULT_DEVICE}, @ref{omp_set_default_device},
+@ref{omp_get_initial_device}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 3.2.30.
@@ -1681,6 +1694,8 @@ Get the default device for target regions without device clause.
@item @emph{Description}:
Returns the number of target devices.
+The effect of running this routine in a @code{target} region is unspecified.
+
@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_num_devices(void);}
@@ -1702,9 +1717,9 @@ Returns the number of target devices.
@table @asis
@item @emph{Description}:
This function returns a device number that represents the device that the
-current thread is executing on. For OpenMP 5.0, this must be equal to the
-value returned by the @code{omp_get_initial_device} function when called
-from the host.
+current thread is executing on. When called on the host, it returns
+the same value as returned by the @code{omp_get_initial_device} function
+as required since OpenMP 5.0.
@item @emph{C/C++}
@multitable @columnfractions .20 .80
@@ -1754,9 +1769,11 @@ their language-specific counterparts.
@table @asis
@item @emph{Description}:
This function returns a device number that represents the host device.
-For OpenMP 5.1, this must be equal to the value returned by the
+Since OpenMP 5.1, this is equal to the value returned by the
@code{omp_get_num_devices} function.
+The effect of running this routine in a @code{target} region is unspecified.
+
@item @emph{C/C++}
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_initial_device(void);}
@@ -2362,8 +2379,9 @@ The routines have C linkage and do not throw exceptions.
@menu
* omp_init_lock:: Initialize simple lock
* omp_init_nest_lock:: Initialize nested lock
-@c * omp_init_lock_with_hint:: <fixme>
-@c * omp_init_nest_lock_with_hint:: <fixme>
+@c PR libgomp/109452
+@c * omp_init_lock_with_hint:: Initialize simple lock with sync hint
+@c * omp_init_nest_lock_with_hint:: Initialize nested lock with sync hint
* omp_destroy_lock:: Destroy simple lock
* omp_destroy_nest_lock:: Destroy nested lock
* omp_set_lock:: Wait for and set simple lock
