libgomp.texi: Document omp_display_env

  Another small step in my side project of documenting all OpenMP routines in libgomp.texi
Here, only 'omp_display_env' is added. (New since OpenMP 5.1 but since a long time in GCC,
some fineprint in both the implementation and in the documentation is based on TR11.)

* * *

RFC - regarding printing the values (env.c not the documentation):

I am wondering whether to change "OMP_VAR = 'val'" to "OMP_VAR='val'", i.e. to remove
the spaces around the equal sign.

Pro: The latter is friendlier when using the env var with POSIX shells / Bash as those do not
permit spaces. (While 'setenv' in the cshell requires a space instead of an equal size.)
Since OpenMP has the '[device] ' prevfix which is used by many implementations, including GCC,
copy'n'paste is now harder and the benefit of removing the space is lower.

Additionally, the OpenMP document has "format NAME ’=’ VALUE" which also implies no spaces
and LLVM's runtime library also prints it without spaces.

Thoughts?  (The attached patch documents the current implementation.)

* * *

Comments or suggestions to the .texi patch itself?

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
  

On 1/3/24 11:31, Tobias Burnus wrote:
> Another small step in my side project of documenting all OpenMP routines in 
> libgomp.texi
> Here, only 'omp_display_env' is added. (New since OpenMP 5.1 but since a long 
> time in GCC,
> some fineprint in both the implementation and in the documentation is based on 
> TR11.)
> 
> * * *
> 
> RFC - regarding printing the values (env.c not the documentation):
> 
> I am wondering whether to change "OMP_VAR = 'val'" to "OMP_VAR='val'", i.e. to 
> remove
> the spaces around the equal sign.
> 
> Pro: The latter is friendlier when using the env var with POSIX shells / Bash 
> as those do not
> permit spaces. (While 'setenv' in the cshell requires a space instead of an 
> equal size.)
> Since OpenMP has the '[device] ' prevfix which is used by many implementations, 
> including GCC,
> copy'n'paste is now harder and the benefit of removing the space is lower.
> 
> Additionally, the OpenMP document has "format NAME ’=’ VALUE" which also 
> implies no spaces
> and LLVM's runtime library also prints it without spaces.
> 
> Thoughts?  (The attached patch documents the current implementation.)

I'm not sure about the usability issues, except I think it's generally easier 
to change an undocumented interface.  :-)

> Comments or suggestions to the .texi patch itself?


> libgomp.texi: Document omp_display_env
> 
> libgomp/ChangeLog:
> 
> 	* libgomp.texi (Environment Display Routine): Uncomment and
> 	add omp_display_env description.
> 	(OMP_DISPLAY_ENV): Update wording, add 'see also'.
> 
>  libgomp/libgomp.texi | 109 ++++++++++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 94 insertions(+), 15 deletions(-)
> 
> diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
> index c727850397d..9999686f712 100644
> --- a/libgomp/libgomp.texi
> +++ b/libgomp/libgomp.texi
> @@ -570,7 +570,7 @@ specification in version 5.2.
>  @c * Interoperability Routines::
>  * Memory Management Routines::
>  @c * Tool Control Routine::
> -@c * Environment Display Routine::
> +* Environment Display Routine::
>  @end menu
>  
>  
> @@ -2919,18 +2919,93 @@ was already deallocated or when the used allocator has already been destroyed.
>  
>  
>  @c @node Tool Control Routine
> +@c @section Tool Control Routine
>  @c
>  @c FIXME
>  
> -@c @node Environment Display Routine
> -@c @section Environment Display Routine
> -@c
> -@c Routine to display the OpenMP number and the initial value of ICVs.
> -@c It has C linkage and do not throw exceptions.
> -@c
> -@c menu
> -@c * omp_display_env:: <fixme>
> -@c end menu
> +@node Environment Display Routine
> +@section Environment Display Routine
> +
> +Routine to display the OpenMP number and the initial value of ICVs.

I'm not sure what an "OpenMP number is".  Below it says "GCC version number" 
and "OpenMP version" in different places; does it print both, or is one of 
those incorrect?  IIUC GCC does not implement specific OpenMP versions or have 
any way to control which OpenMP version you get; it's just whatever we've 
gotten around to implementing so far.

> +It has C linkage and do not throw exceptions.

s/do/does/

> +
> +@menu
> +* omp_display_env:: print the initial ICV values
> +@end menu
> +
> +@node omp_display_env
> +@subsection @code{omp_display_env} -- print the initial ICV values

The right markup for an em dash in Texinfo would be
s/ -- /---/

> +@table @asis
> +@item @emph{Description}:
> +Each time this routine is invoked, the GCC version number and initial value of
> +internal control variables (ICVs) is shown on @code{stderr}.  Initial value
> +denotes the value at startup after evaluating the environment variables, such
> +that later calls to API routines or clauses used in enclosing constructs do not
> +affect the @emph{displayed} values.

I'd rephrase this a bit:

...is printed on @code{stderr}.  The displayed values are those at startup
after evaluating the environment variables; later calls to API routines
or clauses used in enclosing constructs do not affect the output.

> +
> +If the @var{verbose} argument is @code{false}, only the OpenMP version and
> +standard OpenMP ICVs are shown; if it is @code{true}, additionally, the
> +GCC-specific ICVs are shown.
> +
> +The output consists of multiple lines and starts with
> +@samp{OPENMP DISPLAY ENVIRONMENT BEGIN} followed by the name-value lines and
> +ends with @samp{OPENMP DISPLAY ENVIRONMENT END}. The name-value lines are
> +(usually and in GCC) indented by two spaces; the @var{name} is followed by an
> +equal sign and the @var{value} is enclosed in single quotes; in GCC, the equal
> +sign is preceded and followed by a single space.

This is the documentation for the GCC implementation, so it's not necessary to 
say "in GCC" or
"usually" to imply that other implementations may do something different.  Just 
document what GCC does, unless you think the format is likely to change.

> +
> +The first line has as @var{name} either (usually and in GCC) @samp{_OPENMP} or
> +@samp{openmp_version} and shows as value the OpenMP version number
> +(4-digit year, 2-digit month) of the implementation, matching the value of
> +the @code{_OPENMP} macro and, in Fortran, the named constant
> +@code{openmp_version}.
> +
> +In each of the succeeding lines, the @var{name} matches the environment-variable
> +name of an ICV and shows its value.  Those line are optionally (and in GCC
> +always) prefixed by pair of brackets and a space, where the brackets enclose a
> +comma-separated list of devices to which the ICV-value combination
> +applies to; the value can either be a numeric device number or an abstract name
> +denoting all devices (@code{all}), the initial host device (@code{host}) or all
> +devices but the host (@code{device}). Note that the same ICV might be printed
> +multiple times for multiple devices, even if all have the same value.

More of the unnecessary "usually", "optionally", etc waffling that should just 
be removed in those two paragraphs.

> +
> +The effect when invoked from within a @code{target} region is unspecified.
> +
> +@item @emph{C/C++}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Prototype}: @tab @code{void omp_display_env(int verbose)}
> +@end multitable
> +
> +@item @emph{Fortran}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Interface}: @tab @code{subroutine omp_display_env(vebose)}
> +@item                   @tab @code{logical, intent(in) :: verbose}
> +@end multitable
> +
> +@item @emph{Example}:
> +Note that the GCC-specific ICVs, such as the shown @code{GOMP_SPINCOUNT},
> +are only printed when @var{varbose} set to @code{true}.
> +
> +@smallexample
> +OPENMP DISPLAY ENVIRONMENT BEGIN
> +  _OPENMP = '201511'
> +  [host] OMP_DYNAMIC = 'FALSE'
> +  [host] OMP_NESTED = 'FALSE'
> +  [all] OMP_CANCELLATION = 'FALSE'
> +  ...
> +  [host] GOMP_SPINCOUNT = '300000'
> +OPENMP DISPLAY ENVIRONMENT END
> +@end smallexample
> +
> +
> +@item @emph{See also}:
> +@ref{OMP_DISPLAY_ENV}, @ref{Environment Variables},
> +@ref{Implementation-defined ICV Initialization}
> +
> +@item @emph{Reference}:
> +@uref{https://www.openmp.org, OpenMP specification v5.1}, Section 3.15
> +@end table
> +
>  
>  @c ---------------------------------------------------------------------
>  @c OpenMP Environment Variables
> @@ -3182,12 +3257,16 @@ any change occurs.
>  @item @emph{ICV:} none
>  @item @emph{Scope:} not applicable
>  @item @emph{Description}:
> -If set to @code{TRUE}, the OpenMP version number and the values
> -associated with the OpenMP environment variables are printed to @code{stderr}.
> -If set to @code{VERBOSE}, it additionally shows the value of the environment
> -variables which are GNU extensions.  If undefined or set to @code{FALSE},
> -this information is not shown.
> +If set to @code{TRUE}, the runtime displays the same information to
> +@code{stderr} as shown by the @code{omp_display_env} routine invoked with
> +@var{verbose} argument set to @code{false}.  If set to @code{VERBOSE}, the same
> +information is shown as invoking the routine with @var{verbose} set to
> +@code{true}. If unset or set to @code{FALSE}, this information is not shown.
> +The result for any other value is unspecified; GCC shows an error and continues
> +the execution.

It's not GCC that is executing here, but user programs built with GCC, I think? 
  Is this information printed by the runtime on program start-up?  I think it 
needs to say that, or if something else triggers the output.

> +@item @emph{See also}:
> +@ref{omp_display_env}
>  
>  @item @emph{Reference}:
>  @uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12

-Sandra