@item @code{metadirective} directive @tab N @tab
@item @code{declare variant} directive
@tab P @tab @emph{simd} traits not handled correctly
-@item @emph{target-offload-var} ICV and @code{OMP_TARGET_OFFLOAD}
+@item @var{target-offload-var} ICV and @code{OMP_TARGET_OFFLOAD}
env variable @tab Y @tab
-@item Nested-parallel changes to @emph{max-active-levels-var} ICV @tab Y @tab
+@item Nested-parallel changes to @var{max-active-levels-var} ICV @tab Y @tab
@item @code{requires} directive @tab P
@tab complete but no non-host devices provides @code{unified_shared_memory}
@item @code{teams} construct outside an enclosing target region @tab Y @tab
@multitable @columnfractions .60 .10 .25
@headitem Description @tab Status @tab Comments
-@item @code{omp_in_explicit_task} routine and @emph{explicit-task-var} ICV
+@item @code{omp_in_explicit_task} routine and @var{explicit-task-var} ICV
@tab Y @tab
@item @code{omp}/@code{ompx}/@code{omx} sentinels and @code{omp_}/@code{ompx_}
namespaces @tab N/A
@item For Fortran, optional comma between directive and clause @tab N @tab
@item Conforming device numbers and @code{omp_initial_device} and
@code{omp_invalid_device} enum/PARAMETER @tab Y @tab
-@item Initial value of @emph{default-device-var} ICV with
+@item Initial value of @var{default-device-var} ICV with
@code{OMP_TARGET_OFFLOAD=mandatory} @tab Y @tab
@item @emph{interop_types} in any position of the modifier list for the @code{init} clause
of the @code{interop} construct @tab N @tab
regions with @code{omp_set_max_active_levels} to one to disable, or
above one to enable.
+Note that the @code{omp_get_nested} API routine was deprecated
+in the OpenMP specification 5.2 in favor of @code{omp_get_max_active_levels}.
+
@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{int omp_get_nested(void);}
@end multitable
@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{omp_set_nested},
+@ref{omp_get_max_active_levels}, @ref{omp_set_nested},
@ref{OMP_MAX_ACTIVE_LEVELS}, @ref{OMP_NESTED}
@item @emph{Reference}:
active nested regions to the maximum supported. Disabling nested parallel
regions will set the maximum number of active nested regions to one.
+Note that the @code{omp_set_nested} API routine was deprecated
+in the OpenMP specification 5.2 in favor of @code{omp_set_max_active_levels}.
+
@item @emph{C/C++}:
@multitable @columnfractions .20 .80
@item @emph{Prototype}: @tab @code{void omp_set_nested(int nested);}
@chapter OpenMP Environment Variables
The environment variables which beginning with @env{OMP_} are defined by
-section 4 of the OpenMP specification in version 4.5, while those
-beginning with @env{GOMP_} are GNU extensions.
+section 4 of the OpenMP specification in version 4.5 or in a later version
+of the specification, while those beginning with @env{GOMP_} are GNU extensions.
+Most @env{OMP_} environment variables have an associated internal control
+variable (ICV).
+
+For any OpenMP environment variable that sets an ICV and is neither
+@code{OMP_DEFAULT_DEVICE} nor has global ICV scope, associated
+device-specific environment variables exist. For them, the environment
+variable without suffix affects the host. The suffix @code{_DEV_} followed
+by a non-negative device number less that the number of available devices sets
+the ICV for the corresponding device. The suffix @code{_DEV} sets the ICV
+of all non-host devices for which a device-specific corresponding environment
+variable has not been set while the @code{_ALL} suffix sets the ICV of all
+host and non-host devices for which a more specific corresponding environment
+variable is not set.
@menu
* OMP_ALLOCATOR:: Set the default allocator
@section @env{OMP_ALLOCATOR} -- Set the default allocator
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{available-devices-var}
+@item @emph{Scope:} data environment
@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 if an OpenMP memory
or a predefined memory space followed by a colon and a comma-separated list
of memory trait and value pairs, separated by @code{=}.
+Note: The corresponding device environment variables are currently not
+supported. Therefore, the non-host @var{def-allocator-var} ICVs are always
+initialized to @code{omp_default_mem_alloc}. However, on all devices,
+the @code{omp_set_default_allocator} API routine can be used to change
+value.
+
@multitable @columnfractions .45 .45
@headitem Predefined allocators @tab Predefined memory spaces
@item omp_default_mem_alloc @tab omp_default_mem_space
@section @env{OMP_AFFINITY_FORMAT} -- Set the format string used for affinity display
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{affinity-format-var}
+@item @emph{Scope:} device
@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
@section @env{OMP_CANCELLATION} -- Set whether cancellation is activated
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{cancel-var}
+@item @emph{Scope:} global
@item @emph{Description}:
If set to @code{TRUE}, the cancellation is activated. If set to @code{FALSE} or
if unset, cancellation is disabled and the @code{cancel} construct is ignored.
@section @env{OMP_DISPLAY_AFFINITY} -- Display thread affinity information
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{display-affinity-var}
+@item @emph{Scope:} global
@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
@section @env{OMP_DISPLAY_ENV} -- Show OpenMP version and environment variables
@cindex Environment Variable
@table @asis
+@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}.
@section @env{OMP_DEFAULT_DEVICE} -- Set the device used in target regions
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{default-device-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Set to choose the device which is used in a @code{target} region, unless the
value is overridden by @code{omp_set_default_device} or by a @code{device}
@section @env{OMP_DYNAMIC} -- Dynamic adjustment of threads
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{dyn-var}
+@item @emph{Scope:} global
@item @emph{Description}:
Enable or disable the dynamic adjustment of the number of threads
within a team. The value of this environment variable shall be
@section @env{OMP_MAX_ACTIVE_LEVELS} -- Set the maximum number of nested parallel regions
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{max-active-levels-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Specifies the initial value for the maximum number of nested parallel
regions. The value of this variable shall be a positive integer.
it will be set to one.
@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{OMP_NESTED}
+@ref{omp_set_max_active_levels}, @ref{OMP_NESTED}, @ref{OMP_PROC_BIND},
+@ref{OMP_NUM_THREADS}
+
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.9
number that can be set for a task.
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{max-task-priority-var}
+@item @emph{Scope:} global
@item @emph{Description}:
Specifies the initial value for the maximum priority value that can be
set for a task. The value of this variable shall be a non-negative
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
+@item @emph{ICV:} @var{max-active-levels-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Enable or disable nested parallel regions, i.e., whether team members
are allowed to create new teams. The value of this environment variable
@env{OMP_NUM_THREADS} or @env{OMP_PROC_BINDS} are defined to a list with
more than one item, otherwise they are disabled by default.
+Note that the @code{OMP_NESTED} environment variable was deprecated in
+the OpenMP specification 5.2 in favor of @code{OMP_MAX_ACTIVE_LEVELS}.
+
@item @emph{See also}:
-@ref{omp_set_max_active_levels}, @ref{omp_set_nested}
+@ref{omp_set_max_active_levels}, @ref{omp_set_nested},
+@ref{OMP_MAX_ACTIVE_LEVELS}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.6
@section @env{OMP_NUM_TEAMS} -- Specifies the number of teams to use by teams region
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{nteams-var}
+@item @emph{Scope:} device
@item @emph{Description}:
Specifies the upper bound for number of teams to use in teams regions
without explicit @code{num_teams} clause. The value of this variable shall
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
+@item @emph{ICV:} @var{nthreads-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Specifies the default number of threads to use in parallel regions. The
value of this variable shall be a comma-separated list of positive integers;
level. Specifying more than one item in the list will automatically enable
nesting by default. If undefined one thread per CPU is used.
+When a list with more than value is specified, it also affects the
+@var{max-active-levels-var} ICV as described in @ref{OMP_MAX_ACTIVE_LEVELS}.
+
@item @emph{See also}:
-@ref{omp_set_num_threads}, @ref{OMP_NESTED}
+@ref{omp_set_num_threads}, @ref{OMP_MAX_ACTIVE_LEVELS}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.2
@section @env{OMP_PROC_BIND} -- Whether threads may be moved between CPUs
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{bind-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Specifies whether threads may be moved between processors. If set to
@code{TRUE}, OpenMP threads should not be moved; if set to @code{FALSE}
across the place partitions is used. Specifying more than one item in the
list will automatically enable nesting by default.
+When a list is specified, it also affects the @var{max-active-levels-var} ICV
+as described in @ref{OMP_MAX_ACTIVE_LEVELS}.
+
When undefined, @env{OMP_PROC_BIND} defaults to @code{TRUE} when
@env{OMP_PLACES} or @env{GOMP_CPU_AFFINITY} is set and @code{FALSE} otherwise.
@item @emph{See also}:
-@ref{omp_get_proc_bind}, @ref{GOMP_CPU_AFFINITY},
-@ref{OMP_NESTED}, @ref{OMP_PLACES}
+@ref{omp_get_proc_bind}, @ref{GOMP_CPU_AFFINITY}, @ref{OMP_PLACES},
+@ref{OMP_MAX_ACTIVE_LEVELS}
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.4
@section @env{OMP_PLACES} -- Specifies on which CPUs the threads should be placed
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{place-partition-var}
+@item @emph{Scope:} implicit tasks
@item @emph{Description}:
The thread placement can be either specified using an abstract name or by an
explicit list of the places. The abstract names @code{threads}, @code{cores},
@section @env{OMP_STACKSIZE} -- Set default thread stack size
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{stacksize-var}
+@item @emph{Scope:} device
@item @emph{Description}:
Set the default thread stack size in kilobytes, unless the number
is suffixed by @code{B}, @code{K}, @code{M} or @code{G}, in which
stack size is left unchanged. If undefined, the stack size is system
dependent.
+@item @emph{See also}:
+@ref{GOMP_STACKSIZE}
+
@item @emph{Reference}:
@uref{https://www.openmp.org, OpenMP specification v4.5}, Section 4.7
@end table
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
+@item @emph{ICV:} @var{run-sched-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Allows to specify @code{schedule type} and @code{chunk size}.
The value of the variable shall have the form: @code{type[,chunk]} where
@cindex Environment Variable
@cindex Implementation specific setting
@table @asis
+@item @emph{ICV:} @var{target-offload-var}
+@item @emph{Scope:} global
@item @emph{Description}:
Specifies the behaviour with regard to offloading code to a device. This
variable can be set to one of three values - @code{MANDATORY}, @code{DISABLED}
@section @env{OMP_TEAMS_THREAD_LIMIT} -- Set the maximum number of threads imposed by teams
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{teams-thread-limit-var}
+@item @emph{Scope:} device
@item @emph{Description}:
Specifies an upper bound for the number of threads to use by each contention
group created by a teams construct without explicit @code{thread_limit}
@section @env{OMP_THREAD_LIMIT} -- Set the maximum number of threads
@cindex Environment Variable
@table @asis
+@item @emph{ICV:} @var{thread-limit-var}
+@item @emph{Scope:} data environment
@item @emph{Description}:
Specifies the number of threads to use for the whole program. The
value of this variable shall be a positive integer. If undefined,
@chapter OpenMP-Implementation Specifics
@menu
+* Implementation-defined ICV Initialization::
* OpenMP Context Selectors::
* Memory allocation with libmemkind::
@end menu
+@node Implementation-defined ICV Initialization
+@section Implementation-defined ICV Initialization
+@cindex Implementation specific setting
+
+@multitable @columnfractions .30 .70
+@item @var{affinity-format-var} @tab See @ref{OMP_AFFINITY_FORMAT}.
+@item @var{def-allocator-var} @tab See @ref{OMP_ALLOCATOR}.
+@item @var{max-active-levels-var} @tab See @ref{OMP_MAX_ACTIVE_LEVELS}.
+@item @var{dyn-var} @tab See @ref{OMP_DYNAMIC}.
+@item @var{nthreads-var} @tab See @code{OMP_NUM_THREADS}.
+@item @var{num-devices-var} @tab Number of non-host devices found
+by GCC's run-time library
+@item @var{num-procs-var} @tab The number of CPU cores on the
+initial device, except that affinity settings might lead to a
+smaller number. On non-host devices, the value of the
+@var{nthreads-var} ICV.
+@item @var{place-partition-var} @tab See @ref{OMP_PLACES}.
+@item @var{run-sched-var} @tab See @ref{OMP_SCHEDULE}.
+@item @var{stacksize-var} @tab See @ref{OMP_STACKSIZE}.
+@item @var{thread-limit-var} @tab See @ref{OMP_TEAMS_THREAD_LIMIT}
+@item @var{wait-policy-var} @tab See @ref{OMP_WAIT_POLICY} and
+@ref{GOMP_SPINCOUNT}
+@end multitable
+
@node OpenMP Context Selectors
@section OpenMP Context Selectors
@item OpenMP code that has a @code{requires} directive with
@code{unified_shared_memory} will remove any nvptx device from the
list of available devices (``host fallback'').
+@item The default per-warp stack size is 128 kiB; see also @code{-msoft-stack}
+ in the GCC manual.
@end itemize
projects / thirdparty / gcc.git / commitdiff
