diff mbox series

libgomp.texi: Clarify OMP_TARGET_OFFLOAD=mandatory

Message ID 2111df82-33ad-4165-8516-f9107de0fbf0@codesourcery.com
State New
Headers show
Series libgomp.texi: Clarify OMP_TARGET_OFFLOAD=mandatory | expand

Commit Message

Tobias Burnus Oct. 12, 2023, 4:37 p.m. UTC 
I noticed that while OMP_DEFAULT_DEVICE was updated a ref to
OMP_TARGET_OFFLOAD (→ mandatory case) was missing. And
OMP_TARGET_OFFLOAD wasn't updated at all for those changes.

I hope the new version is clearer.

Current versions:
https://gcc.gnu.org/onlinedocs/libgomp/OMP_005fDEFAULT_005fDEVICE.html
https://gcc.gnu.org/onlinedocs/libgomp/OMP_005fTARGET_005fOFFLOAD.html

I have changed the reference to OpenMP 5.2 (from 4.5 and 5.0) as only
the latter fully describes the current behavior; I first left in the
current specification references and only added the v5.2 one, but I
then did not see an advantage of doing so.

Any comments or suggestions before I commit the attached patch?

Tobias
-----------------
Siemens Electronic Design Automation GmbH; Anschrift: Arnulfstraße 201, 80634 München; Gesellschaft mit beschränkter Haftung; Geschäftsführer: Thomas Heurung, Frank Thürauf; Sitz der Gesellschaft: München; Registergericht München, HRB 106955

Comments

Jakub Jelinek Oct. 12, 2023, 6:42 p.m. UTC | #1 
On Thu, Oct 12, 2023 at 06:37:00PM +0200, Tobias Burnus wrote:
> libgomp.texi: Clarify OMP_TARGET_OFFLOAD=mandatory
> 
> In OpenMP 5.0/5.1, the semantic of OMP_TARGET_OFFLOAD=mandatory was
> insufficiently specified; 5.2 clarified this with extensions/clarifications
> (omp_initial_device, omp_invalid_device, "conforming device number").
> GCC's implementation matches OpenMP 5.2.
> 
> libgomp/ChangeLog:
> 
> 	* libgomp.texi (OMP_DEFAULT_DEVICE): Update spec ref; add @ref to
> 	OMP_TARGET_OFFLOAD.
> 	(OMP_TARGET_OFFLOAD): Update spec ref; add @ref to OMP_DEFAULT_DEVICE;
> 	clarify MANDATORY behavior.

LGTM.

	Jakub
Sandra Loosemore Oct. 14, 2023, 8:08 p.m. UTC | #2 
On 10/12/23 10:37, Tobias Burnus wrote:
> @@ -3133,15 +3134,25 @@ variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
>  or @code{DEFAULT}.
>  
>  If set to @code{MANDATORY}, the program will terminate with an error if
> -the offload device is not present or is not supported.  If set to
> -@code{DISABLED}, then offloading is disabled and all code will run on the
> -host. If set to @code{DEFAULT}, the program will try offloading to the
> +any device construct or device memory routine uses a device that is unavailable
> +or not supported by the implementation, or uses a non-conforming device number.
> +If set to @code{DISABLED}, then offloading is disabled and all code will run on
> +the host. If set to @code{DEFAULT}, the program will try offloading to the
>  device first, then fall back to running code on the host if it cannot.
>  
>  If undefined, then the program will behave as if @code{DEFAULT} was set.
>  
> +Note: Even with @code{MANDATORY}, there will be no run-time termination when
> +the device number in a @code{device} clause or argument to a device memory
> +routine is for host, which includes using the device number in the
> +@var{default-device-var} ICV.  However, the initial value of
> +the @var{default-device-var} ICV is affected by @code{MANDATORY}.

Can we please rewrite this whole section in the present tense?  E.g.

s/will terminate/terminates/
s/will run/runs/
s/will try ... fall back/tries ... falls back/
s/will behave/behaves/
s/will be/is/

-Sandra
diff mbox series

Patch

libgomp.texi: Clarify OMP_TARGET_OFFLOAD=mandatory

In OpenMP 5.0/5.1, the semantic of OMP_TARGET_OFFLOAD=mandatory was
insufficiently specified; 5.2 clarified this with extensions/clarifications
(omp_initial_device, omp_invalid_device, "conforming device number").
GCC's implementation matches OpenMP 5.2.

libgomp/ChangeLog:

	* libgomp.texi (OMP_DEFAULT_DEVICE): Update spec ref; add @ref to
	OMP_TARGET_OFFLOAD.
	(OMP_TARGET_OFFLOAD): Update spec ref; add @ref to OMP_DEFAULT_DEVICE;
	clarify MANDATORY behavior.

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index ba8e9013814..46c4dcf90f1 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -2831,9 +2831,10 @@  device number 0 will be used.
 
 @item @emph{See also}:
 @ref{omp_get_default_device}, @ref{omp_set_default_device},
+@ref{OMP_TARGET_OFFLOAD}
 
 @item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.13
+@uref{https://www.openmp.org, OpenMP specification v5.2}, Section 21.2.7
 @end table
 
 
@@ -3133,15 +3134,25 @@  variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
 or @code{DEFAULT}.
 
 If set to @code{MANDATORY}, the program will terminate with an error if
-the offload device is not present or is not supported.  If set to
-@code{DISABLED}, then offloading is disabled and all code will run on the
-host. If set to @code{DEFAULT}, the program will try offloading to the
+any device construct or device memory routine uses a device that is unavailable
+or not supported by the implementation, or uses a non-conforming device number.
+If set to @code{DISABLED}, then offloading is disabled and all code will run on
+the host. If set to @code{DEFAULT}, the program will try offloading to the
 device first, then fall back to running code on the host if it cannot.
 
 If undefined, then the program will behave as if @code{DEFAULT} was set.
 
+Note: Even with @code{MANDATORY}, there will be no run-time termination when
+the device number in a @code{device} clause or argument to a device memory
+routine is for host, which includes using the device number in the
+@var{default-device-var} ICV.  However, the initial value of
+the @var{default-device-var} ICV is affected by @code{MANDATORY}.
+
+@item @emph{See also}:
+@ref{OMP_DEFAULT_DEVICE}
+
 @item @emph{Reference}:
-@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.17
+@uref{https://www.openmp.org, OpenMP specification v5.2}, Section 21.2.8
 @end table