libgomp.texi: Improve "OpenACC Environment Variables"

Message ID f10a9a67-1e27-4c1e-a8c9-052685a02103@codesourcery.com
State Accepted
Headers
Series libgomp.texi: Improve "OpenACC Environment Variables" |

Checks

Context Check Description
snail/gcc-patch-check success Github commit url

Commit Message

Tobias Burnus Oct. 14, 2023, 7:51 p.m. UTC
  I was recently suggesting someone to use ACC_DEVICE_TYPE; I did not point to the
documentation it only contains the title:
   https://gcc.gnu.org/onlinedocs/libgomp/ACC_005fDEVICE_005fTYPE.html

Admittedly, there is also "Reference:" pointing to the OpenACC specification,
but the latter just states:

"The allowed values of this environment variable are implementation-defined. See the
release notes for currently-supported values of this environment variable."

Thus, I now added documentation for the three ACC_ env vars.
I removed GCC_ACC_NOTIFY as it does not seem to exist - and it looks as if it
never did ... (The Nvidia compiler seems to support ACC_NOTIFY with a similar
usage as GOMP_DEBUG and GCN_DEBUG). It was added in GCC 6, which implies that
it also won't be added again. (I also checked OG9 and OG13 and neither contained
it; I don't know whether some older OG did.)

Comments?

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

Sandra Loosemore Oct. 14, 2023, 10:46 p.m. UTC | #1
On 10/14/23 13:51, Tobias Burnus wrote:

> @@ -5003,6 +5001,17 @@ The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
>  @node ACC_DEVICE_TYPE
>  @section @code{ACC_DEVICE_TYPE}
>  @table @asis
> +@item @emph{Description}:
> +Control the default device type to use when executing compute regions.
> +If unset, the code can be run on any device type, favoring a non-host
> +device type.
> +
> +Supported value in GCC (if compiled in) are

s/value/values/

> +@itemize
> +@item @code{host}
> +@item @code{nvidia}
> +@item @code{radeon}
> +@end itemize
>  @item @emph{Reference}:
>  @uref{https://www.openacc.org, OpenACC specification v2.6}, section
>  4.1.
> @@ -5013,6 +5022,10 @@ The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
>  @node ACC_DEVICE_NUM
>  @section @code{ACC_DEVICE_NUM}
>  @table @asis
> +@item @emph{Description}:
> +Control which device, identified by device number, is the default device.
> +The number must be a nonnegative integer number less that the number of

Ummm, too many "number"s!

How about rephrasing that as
The value must be a nonnegative integer less than the number of....

> +devices.  If unset, device number zero is used.
>  @item @emph{Reference}:
>  @uref{https://www.openacc.org, OpenACC specification v2.6}, section
>  4.2.
> @@ -5023,6 +5036,11 @@ The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
>  @node ACC_PROFLIB
>  @section @code{ACC_PROFLIB}
>  @table @asis
> +@item @emph{Description}:
> +Semicolon separated list of dynamic libraries to be loaded as profiling library.

s/Semicolon separated/Semicolon-separated/

There's also a semantic issue with "list of dynamic libraries" (plural) and 
"profiling library" (singular).  Are they all separately profiling libraries, 
or does the entire list constitute a single logical profiling library and its 
dependencies?

> +The library file is found as described by the documentation of @code{dlopen} of

Probably s/The/Each/?

> +your operating system.  Each library must implement at least the routine
> +@code{acc_register_library} routine.

Again, I'm not sure if this applies to every library in the list, or just that 
some library in the list must provide this routine.

-Sandra
  
Tobias Burnus Oct. 15, 2023, 10:40 a.m. UTC | #2
Hi Sandra,

thanks for the comments.

On 15.10.23 00:46, Sandra Loosemore wrote:
>> +Semicolon separated list of dynamic libraries to be loaded as
>> profiling library.
>
> s/Semicolon separated/Semicolon-separated/
>
> There's also a semantic issue with "list of dynamic libraries"
> (plural) and "profiling library" (singular).  Are they all separately
> profiling libraries, or does the entire list constitute a single
> logical profiling library and its dependencies?

No, each library works as separate "profiling library", everything else
does not make much sense.

Updated patch attached - I hope it is now clearer.

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
  
Sandra Loosemore Oct. 15, 2023, 8:30 p.m. UTC | #3
On 10/15/23 04:40, Tobias Burnus wrote:
> Hi Sandra,
> 
> thanks for the comments.
> 
> On 15.10.23 00:46, Sandra Loosemore wrote:
>>> +Semicolon separated list of dynamic libraries to be loaded as
>>> profiling library.
>>
>> s/Semicolon separated/Semicolon-separated/
>>
>> There's also a semantic issue with "list of dynamic libraries"
>> (plural) and "profiling library" (singular).  Are they all separately
>> profiling libraries, or does the entire list constitute a single
>> logical profiling library and its dependencies?
> 
> No, each library works as separate "profiling library", everything else
> does not make much sense.
> 
> Updated patch attached - I hope it is now clearer.

Yup, this version is fine to commit.

-Sandra
  

Patch

libgomp.texi: Improve "OpenACC Environment Variables"

None of the ACC_* env vars was documented; in particular, the valid valids
for ACC_DEVICE_TYPE found to be lacking as those are not document in the
OpenACC spec.
GCC_ACC_NOTIFY was removed as I find any traces of it but the addition
to the documentation in commit r6-6185-gcdf6119dad04dd ("libgomp.texi:
Updates for OpenACC.").  It seems to be planned as GCC version of
the ACC_NOTIFY env var used by another compiler for offloading debugging.

libgomp/
	* libgomp.tex (ACC_DEVICE_TYPE, ACC_DEVICE_NUM, ACC_PROFLIB):
	Actually document what the function does.
	(GCC_ACC_NOTIFY): Remove unused env var.

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 526d1be2955..941525d013d 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -4989,13 +4989,11 @@  The variables @env{ACC_DEVICE_TYPE} and @env{ACC_DEVICE_NUM}
 are defined by section 4 of the OpenACC specification in version 2.0.
 The variable @env{ACC_PROFLIB}
 is defined by section 4 of the OpenACC specification in version 2.6.
-The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
 
 @menu
 * ACC_DEVICE_TYPE::
 * ACC_DEVICE_NUM::
 * ACC_PROFLIB::
-* GCC_ACC_NOTIFY::
 @end menu
 
 
@@ -5003,6 +5001,17 @@  The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
 @node ACC_DEVICE_TYPE
 @section @code{ACC_DEVICE_TYPE}
 @table @asis
+@item @emph{Description}:
+Control the default device type to use when executing compute regions.
+If unset, the code can be run on any device type, favoring a non-host
+device type.
+
+Supported value in GCC (if compiled in) are
+@itemize
+@item @code{host}
+@item @code{nvidia}
+@item @code{radeon}
+@end itemize
 @item @emph{Reference}:
 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
 4.1.
@@ -5013,6 +5022,10 @@  The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
 @node ACC_DEVICE_NUM
 @section @code{ACC_DEVICE_NUM}
 @table @asis
+@item @emph{Description}:
+Control which device, identified by device number, is the default device.
+The number must be a nonnegative integer number less that the number of
+devices.  If unset, device number zero is used.
 @item @emph{Reference}:
 @uref{https://www.openacc.org, OpenACC specification v2.6}, section
 4.2.
@@ -5023,6 +5036,11 @@  The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
 @node ACC_PROFLIB
 @section @code{ACC_PROFLIB}
 @table @asis
+@item @emph{Description}:
+Semicolon separated list of dynamic libraries to be loaded as profiling library.
+The library file is found as described by the documentation of @code{dlopen} of
+your operating system.  Each library must implement at least the routine
+@code{acc_register_library} routine.
 @item @emph{See also}:
 @ref{acc_register_library}, @ref{OpenACC Profiling Interface}
 
@@ -5033,15 +5051,6 @@  The variable @env{GCC_ACC_NOTIFY} is used for diagnostic purposes.
 
 
 
-@node GCC_ACC_NOTIFY
-@section @code{GCC_ACC_NOTIFY}
-@table @asis
-@item @emph{Description}:
-Print debug information pertaining to the accelerator.
-@end table
-
-
-
 @c ---------------------------------------------------------------------
 @c CUDA Streams Usage
 @c ---------------------------------------------------------------------