Intel® oneAPI Level Zero Backend Specification
Introduction
This extension introduces a Level Zero backend for
Data Parallel C++ (
, which is built on top of Level Zero runtime enabled with the
oneAPI Level Zero Specification. The supported targets are Intel GPUs, starting with Gen9.
DPC++
)This specification is a draft. It is not complete or exhaustive in its descriptions. More information, including explanations on mapping the
Data Parallel C++ (
programming model to a Level Zero API, is forthcoming. In the future, it will conform to the SYCL* 2020 spec.
DPC++
)Prerequisites
The Level Zero loader and drivers must be installed on your system for the
DPC++
User-visible Level Zero Backend Selection and Default Backend
The Level Zero backend is added to the
cl::sycl::backend
enumeration with:
enum class backend { // ... level_zero, // ... };
The sections below explain the different ways the Level Zero backend can be selected.
Through an Environment Variable
The
runtime to use only a subset of the system's devices. By using
backend. For more information, see the
Environment Variables.
SYCL_DEVICE_FILTER
environment variable limits the
DPC++
level_zero
for the backend in
SYCL_DEVICE_FILTER
, you can select the use of Level Zero as a
DPC++
Through a Programming API
The Filter Selector extension is described in
SYCL* Proposals: Filter Selector. Similar to how the
SYCL_DEVICE_FILTER
applies filtering to the entire process, this device selector can be used to programmatically select the Level Zero backend.
If the environment variable or filtering device selector is NOT used, the implementation chooses the Level Zero backend for GPU devices that are supported by the installed Level Zero runtime. The serving backend for a
platform can be queried with the
DPC++
get_backend()
member function of the
cl::sycl::platform
command.
Interoperability with the Level Zero API
The sections below describe the various interoperabilities that are possible between
and Level Zero. The application must include the following headers to use any of the inter-operation APIs described in this section. These headers must be included in the order shown:
DPC++
#include "level_zero/ze_api.h" #include "sycl/backend/level_zero.hpp"
Mapping of
Objects to Level Zero Handles
DPC++
These
objects encapsulate the corresponding Level Zero handles:
DPC++
DPC++ | Level Zero Handle
|
---|---|
Platform
| ze_driver_handle_t |
Device
| ze_device_handle_t |
Context
| ze_context_handle_t |
Queue
| ze_command_queue_handle_t |
Program
| ze_module_handle_t |
Obtaining Built-in Level Zero Handles from
Objects
DPC++
The
object. The function is supported for the
get_native<cl::sycl::backend::level_zero>()
member function is how you can use a raw native Level Zero handle to obtain a specific
DPC++
DPC++
platform
,
device
,
context
,
queue
,
event
and
program
classes. You can use a free-function defined in the
cl::sycl
namespace instead of the member function with:
template <backend BackendName, class SyclObjectT> auto get_native(const SyclObjectT &Obj) -> typename interop<BackendName, SyclObjectT>::type;
Construct a
Object from a Level Zero Handle
DPC++
The following free functions, defined in the
object that encapsulates a corresponding Level Zero object:
cl::sycl::level_zero
namespace, allow an application to create a
DPC++
Level Zero Interoperability Function
| Description
|
---|---|
make<platform>(ze_driver_handle_t); | Constructs a
DPC++ ze_driver_handle_t .
|
make<device>(const platform &, ze_device_handle_t); | Constructs a
DPC++ ze_device_handle_t . The platform argument gives a
DPC++ |
make<context>(const vector_class<device> &, ze_context_handle_t); | Constructs a
DPC++ ze_context_handle_t . The context is created against the devices that are passed in. You must give at least one device and all the devices must be from the same
DPC++ |
make<queue>(const context &, ze_command_queue_handle_t); | Constructs a
DPC++ ze_command_queue_handle_t . The context argument must be a valid
DPC++ DPC++ |
make<program>(const context &, ze_module_handle_t); | Constructs a
DPC++ ze_module_handle_t . The context argument must be a valid
DPC++ zeModuleDynamicLink ) and then the
DPC++ |
Level Zero Handle Ownership and Thread-safety
The Level Zero runtime does not do reference-counting of its objects, so it is crucial to adhere to these practices of how Level Zero handles are managed:
- : Whenever the application creates aRuntime Takes OwnershipDPC++object from the corresponding Level Zero handle, via one of theDPC++make<T>()functions, theruntime takes ownership of the Level Zero handle. The application must not use the Level Zero handle after the last host copy of theDPC++object is destroyed. The application must not destroy the Level Zero handle. For more information see the SYCL Common Reference Semantics section: https://www.khronos.org/registry/SYCL/specs/sycl-2020/pdf/sycl-2020.pdfDPC++
- : The application may call theRuntime Assumes OwnershipDPC++get_native<T>()member function of aobject to retrieve the underlying Level Zero handle, however, theDPC++runtime continues to retain ownership of this handle. The application must not use this handle after the last host copy of theDPC++object is destroyed. The application must not destroy the Level Zero handle. For more information see the SYCL Common Reference Semantics section: https://www.khronos.org/registry/SYCL/specs/sycl-2020/pdf/sycl-2020.pdfDPC++
- Considerations for Multi-threaded Environment: The Level Zero API is not thread-safe, refer to Multithreading and Concurrency for more information. Applications must make sure that the Level Zero handles are not used simultaneously from different threads. Theruntime takes ownership of the Level Zero handles and should not attempt further direct use of those handles.DPC++