Skip to content

Commit 4618ff8

Browse files
authored
[SYCL][Doc] Update doc for ONEAPI_DEVICE_SELECTOR (#11581)
Level Zero added a new environment variable `ZE_FLAT_DEVICE_HIERARCHY` that affects the way devices are exposed to high-level languages like SYCL. Describe how this affects `ONEAPI_DEVICE_SELECTOR`.
1 parent 7d02379 commit 4618ff8

File tree

1 file changed

+14
-1
lines changed

1 file changed

+14
-1
lines changed

sycl/doc/EnvironmentVariables.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,22 @@ The following examples further illustrate the usage of this environment variable
8484
Notes:
8585
- The backend argument is always required. An error will be thrown if it is absent.
8686
- Additionally, the backend MUST be followed by colon ( `:` ) and at least one device specifier of some sort, else an error is thrown.
87-
- For sub-devices and sub-sub-devices, the parent device must support partitioning (`info::partition_property::partition_by_affinity_domain` and `info::partition_affinity_domain::next_partitionable`. See the SYCL 2020 specification for a precise definition.) For Intel GPUs, the sub-device and sub-sub-device syntax can be used to expose tiles or CCSs to the SYCL application as root devices. The exact mapping between sub-device, sub-sub-device, tiles, and CCSs is specific to the hardware.
87+
- The sub-device and sub-sub-device syntax attempt to partition the root device
88+
according to the rules defined by
89+
`info::partition_property::partition_by_affinity_domain` and
90+
`info::partition_affinity_domain::next_partitionable`.
91+
(See the SYCL 2020 specification for a precise definition.)
92+
The root device is determined by the underlying backend.
93+
- When using the Level Zero backend, see also the documentation of the
94+
[`ZE_FLAT_DEVICE_HIERARCHY`][ze-env] environment variable because it affects
95+
how this backend exposes root devices to SYCL.
96+
For Intel GPUs, the sub-device and sub-sub-device syntax can be used to
97+
expose tiles or CCSs to the SYCL application as SYCL root devices, however
98+
the exact mapping is determined by the `ZE_FLAT_DEVICE_HIERARCHY` environment
99+
variable.
88100
- The semi-colon character ( `;` ) and the exclamation mark character ( `!` ) are treated specially by many shells, so you may need to enclose the string in quotes if the selection string contains these characters.
89101

102+
[ze-env]: https://spec.oneapi.io/level-zero/latest/core/PROG.html#environment-variables
90103

91104

92105
### `SYCL_DEVICE_ALLOWLIST`

0 commit comments

Comments
 (0)