[Patch] libgomp.texi: Document allocator + affininity env vars

[Tobias Burnus <tobias@codesourcery.com>]

[-- Attachment #1: Type: text/plain, Size: 676 bytes --]

Comments on the wording and/or the content?

I did notice that we missed to document three OMP_* environment
variables, hence, I added them.

(For OMP_ALLOCATOR, I expect an update once the 5.1 extensions have been
implemented.)

(Some cross references could be added if we had/once we have documented
the respective omp_(get,set)_... I think we lack about half of the API
functions.)

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

[-- Attachment #2: texi-envvars.diff --]
[-- Type: text/x-patch, Size: 5109 bytes --]

libgomp.texi: Document allocator + affininity env vars

libgomp/ChangeLog:

	* libgomp.texi (OMP_ALLOCATOR, OMP_AFFINITY_FORMAT,
	OMP_DISPLAY_AFFINITY): New.

diff --git a/libgomp/libgomp.texi b/libgomp/libgomp.texi
index 21d3582a665..70b090824bb 100644
--- a/libgomp/libgomp.texi
+++ b/libgomp/libgomp.texi
@@ -1937,7 +1937,10 @@ section 4 of the OpenMP specification in version 4.5, while those
 beginning with @env{GOMP_} are GNU extensions.
 
 @menu
+* OMP_ALLOCATOR::           Set the default allocator
+* OMP_AFFINITY_FORMAT::     Set the format string used for affinity display
 * OMP_CANCELLATION::        Set whether cancellation is activated
+* OMP_DISPLAY_AFFINITY::    Display thread affinity information
 * OMP_DISPLAY_ENV::         Show OpenMP version and environment variables
 * OMP_DEFAULT_DEVICE::      Set the device used in target regions
 * OMP_DYNAMIC::             Dynamic adjustment of threads
@@ -1962,6 +1965,87 @@ beginning with @env{GOMP_} are GNU extensions.
 @end menu
 
 
+@node OMP_ALLOCATOR
+@section @env{OMP_ALLOCATOR} -- Set the default allocator
+@cindex Environment Variable
+@table @asis
+@item @emph{Description}:
+Sets the default allocator that is used when no allocator has been specified
+in the @code{allocate} or @code{allocator} clause or when
+@code{omp_null_allocator} is used as allocator when invoking an OpenMP memory
+routine. The value should be one of the predefined allocators.
+If unset, @code{omp_default_mem_alloc} is used.
+
+@c @item @emph{See also}:
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.21
+@end table
+
+
+
+@node OMP_AFFINITY_FORMAT
+@section @env{OMP_AFFINITY_FORMAT} -- Set the format string used for affinity display
+@cindex Environment Variable
+@table @asis
+@item @emph{Description}:
+Sets the format string used when displaying OpenMP thread affinity information.
+Special values are output using @code{%} followed by an optional size
+specification and then either the single-character field type or its long
+name enclosed in curly braces; using @code{%%} will display a literal percent.
+The size specification consists of an optional @code{0.} or @code{.} followed
+by a positive integer, specifing the minimal width of the output.  With
+@code{0.} and numerical values, the output is padded with zeros on the left;
+with @code{.}, the output is padded by spaces on the left; otherwise, the
+output is padded by spaces on the right.  If unset, the value is
+``@code{level %L thread %i affinity %A}''.
+
+Supported field types are:
+
+@multitable @columnfractions .10 .25 .60
+@item t @tab team_num @tab value returned by @code{omp_get_team_num}
+@item T @tab num_teams @tab value returned by @code{omp_get_num_teams}
+@item L @tab nesting_level @tab value returned by @code{omp_get_level}
+@item n @tab thread_num @tab value returned by @code{omp_get_thread_num}
+@item N @tab num_threads @tab value returned by @code{omp_get_num_threads}
+@item a @tab ancestor_tnum
+      @tab value returned by
+           @code{omp_get_ancestor_thread_num(omp_get_level()-1)}
+@item H @tab host @tab name of the host that executes the thread
+@item P @tab process_id @tab process identifier
+@item i @tab native_thread_id @tab native thread identifier
+@item A @tab thread_affinity
+      @tab comma separated list of integer values or ranges, representing the
+           processors on which a process might execute, subject to affinity
+           mechanisms
+@end multitable
+
+For instance, after setting
+
+@smallexample
+OMP_AFFINITY_FORMAT="%0.2a!%n!%.4L!%N;%.2t;%0.2T;%@{team_num@};%@{num_teams@};%A"
+@end smallexample
+
+with either @code{OMP_DISPLAY_AFFINITY} being set or when calling
+@code{omp_display_affinity} with @code{NULL} or an empty string, the program
+might display the following:
+
+@smallexample
+00!0!   1!4; 0;01;0;1;0-11
+00!3!   1!4; 0;01;0;1;0-11
+00!2!   1!4; 0;01;0;1;0-11
+00!1!   1!4; 0;01;0;1;0-11
+@end smallexample
+
+@item @emph{See also}:
+@ref{OMP_DISPLAY_AFFINITY}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.14
+@end table
+
+
+
 @node OMP_CANCELLATION
 @section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
 @cindex Environment Variable
@@ -1979,6 +2063,26 @@ if unset, cancellation is disabled and the @code{cancel} construct is ignored.
 
 
 
+@node OMP_DISPLAY_AFFINITY
+@section @env{OMP_DISPLAY_AFFINITY} -- Display thread affinity information
+@cindex Environment Variable
+@table @asis
+@item @emph{Description}:
+If set to @code{FALSE} or if unset, affinity displaying is disabled.
+If set to @code{TRUE}, the runtime will display affinity information about
+OpenMP threads in a parallel region upon entering the region and every time
+any change occurs.
+
+@item @emph{See also}:
+@ref{OMP_AFFINITY_FORMAT}
+
+@item @emph{Reference}:
+@uref{https://www.openmp.org, OpenMP specification v5.0}, Section 6.13
+@end table
+
+
+
+
 @node OMP_DISPLAY_ENV
 @section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
 @cindex Environment Variable