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
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.
+It has C linkage and do not throw exceptions.
+
+@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
+@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.
+
+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.
+
+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.
+
+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.
+@item @emph{See also}:
+@ref{omp_display_env}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.12
