libgomp.texi: Minor update to omp_get_num_devices/omp_get_initial_device

Message ID 61e7105c-b285-4ef2-9aa6-bb8b8d0a9a38@baylibre.com
State New
Headers
Series libgomp.texi: Minor update to omp_get_num_devices/omp_get_initial_device |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_gcc_build--master-arm fail Patch failed to apply
linaro-tcwg-bot/tcwg_gcc_build--master-aarch64 fail Patch failed to apply

Commit Message

Tobias Burnus Jan. 7, 2025, 2:44 p.m. UTC
  OpenMP 6 changed that omp_get_initial_device may not only return the
dynamic value of omp_get_num_devices() but also the constant value
omp_get_num_devices (== -1).

For now, GCC returns omp_get_num_devices() but we may want to change
this in the future as '-1' can be solved at compile time; in particular,
omp_get_device_num is also permitted to return -1 (= the value returned
by omp_get_initial_device), which might be more useful.
(I wouldn't be surprised if code will break if we start to return -1.)

Additionally, I tweaked the wording for omp_get_num_devices to be
a bit clearer and updatedomp_get_default_device as it is no longer the same as omp_get_num_devices.

Comments/suggestions before I commit it?

Tobias
  

Comments

Tobias Burnus Jan. 7, 2025, 3:46 p.m. UTC | #1
Now committed as r15-6659-gd3ccd89fa0d34d – with an additional typo fix:

stipe → stripe (OpenMP 6.0 loop transformation directive).

Tobias
  

Patch

libgomp.texi: Minor update to omp_get_num_devices/omp_get_initial_device

libgomp/ChangeLog:

	* libgomp.texi (omp_get_default_device): Update the wording as the
	value returned by omp_get_initial_device is now ambiguous.
	(omp_get_num_devices): Minor wording tweak.
	(omp_get_initial_device): Note that the function may also
	return omp_initial_device since OpenMP 6.
	
diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 9a42355ff5d..2113abf5c1a 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -1758,14 +1758,13 @@  The effect of running this routine in a @code{target} region is unspecified.
 @table @asis
 @item @emph{Description}:
 Get the value of the @emph{default-device-var} ICV, which is used
 for target regions without a 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.
+@code{omp_invalid_device}. Note that for the host, the ICV can have two values:
+either the value of the named constant @code{omp_initial_device} or the value
+returned by the @code{omp_get_num_devices} routine.
 
 The effect of running this routine in a @code{target} region is unspecified.
 
 @item @emph{C/C++}:
 @multitable @columnfractions .20 .80
@@ -1789,11 +1788,11 @@  The effect of running this routine in a @code{target} region is unspecified.
 
 @node omp_get_num_devices
 @subsection @code{omp_get_num_devices} -- Number of target devices
 @table @asis
 @item @emph{Description}:
-Returns the number of target devices.
+Returns the number of available non-host devices.
 
 The effect of running this routine in a @code{target} region is unspecified.
 
 @item @emph{C/C++}:
 @multitable @columnfractions .20 .80
@@ -1936,11 +1935,12 @@  run-time function is desired.
 @subsection @code{omp_get_initial_device} -- Return device number of initial device
 @table @asis
 @item @emph{Description}:
 This function returns a device number that represents the host device.
 Since OpenMP 5.1, this is equal to the value returned by the
-@code{omp_get_num_devices} function.
+@code{omp_get_num_devices} function; since OpenMP 6.0 it may also return
+the value of @code{omp_initial_device}.
 
 The effect of running this routine in a @code{target} region is unspecified.
 
 @item @emph{C/C++}
 @multitable @columnfractions .20 .80