namespace dnnl::ze_interop

Overview

Level Zero interoperability namespace. More…

namespace ze_interop {

// global functions

std::vector<uint8_t> get_engine_cache_blob_id(
    ze_driver_handle_t driver,
    ze_device_handle_t device
    );

std::vector<uint8_t> get_engine_cache_blob(const engine& aengine);

engine make_engine(
    ze_driver_handle_t driver,
    ze_device_handle_t device,
    ze_context_handle_t context,
    const std::vector<uint8_t>& cache_blob
    );

engine make_engine(
    ze_driver_handle_t adriver,
    ze_device_handle_t adevice,
    ze_context_handle_t acontext
    );

ze_context_handle_t get_context(const engine& aengine);
ze_device_handle_t get_device(const engine& aengine);
ze_driver_handle_t get_driver(const engine& aengine);

stream make_stream(
    const engine& aengine,
    ze_command_list_handle_t alist,
    bool aprofiling = false
    );

ze_command_list_handle_t get_list(const stream& astream);

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    std::vector<void*> handles = {}
    );

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    void* handle
    );

ze_event_handle_t execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<ze_event_handle_t>& deps = {}
    );

} // namespace ze_interop

Detailed Documentation

Level Zero interoperability namespace.

Global Functions

std::vector<uint8_t> get_engine_cache_blob_id(
    ze_driver_handle_t driver,
    ze_device_handle_t device
    )

Returns the cache blob ID of the Level Zero device.

Warning

This API is intended to be used with dnnl::ze_interop::get_engine_cache_blob(const engine &) and dnnl::ze_interop::make_engine(ze_driver_handle_t, ze_device_handle_t, ze_context_handle_t, const std::vector<uint8_t> &). The returned cache blob ID can only be used as an ID of the cache blob returned by dnnl::ze_interop::get_engine_cache_blob(const engine &).

Note

The cache blob ID can be empty (size will be 0 and cache_blob_id will be nullptr) if oneDNN doesn’t have anything to put in the cache blob. (dnnl_ze_interop_engine_get_cache_blob will return an empty cache blob).

Parameters:

driver	A Level Zero driver.
device	A Level Zero device.

Returns:

A vector containing the cache blob ID.

std::vector<uint8_t> get_engine_cache_blob(const engine& aengine)

Returns a cache blob for the engine.

Note

The cache blob vector can be empty if oneDNN doesn’t have anything to put in the cache blob. It’s the user’s responsibility to check whether it’s empty prior to passing it to dnnl::ze_interop::make_engine(ze_driver_handle_t, ze_device_handle_t, ze_context_handle_t, const std::vector<uint8_t> &)

Parameters:

aengine

Engine to query for the cache blob.

Returns:

Vector containing the cache blob.

engine make_engine(
    ze_driver_handle_t driver,
    ze_device_handle_t device,
    ze_context_handle_t context,
    const std::vector<uint8_t>& cache_blob
    )

Constructs an engine from the given cache blob.

Parameters:

driver	The Level Zero driver that this engine will encapsulate.
device	The Level Zero device that this engine will encapsulate.
context	The Level Zero context (containing the device) that this engine will use for all operations.
cache_blob	Cache blob.

Returns:

An engine.

engine make_engine(
    ze_driver_handle_t adriver,
    ze_device_handle_t adevice,
    ze_context_handle_t acontext
    )

Constructs an engine from Level Zero device and context objects.

Parameters:

adriver	Level Zero driver.
adevice	Level Zero device.
acontext	Level Zero context.

Returns:

Created engine.

ze_context_handle_t get_context(const engine& aengine)

Returns the Level Zero context associated with an engine.

Parameters:

aengine

Engine to query.

Returns:

The underlying Level Zero context of the engine.

ze_device_handle_t get_device(const engine& aengine)

Returns the Level Zero device associated with an engine.

Parameters:

aengine

Engine to query.

Returns:

The underlying Level Zero device of the engine.

ze_driver_handle_t get_driver(const engine& aengine)

Returns the Level Zero driver associated with an engine.

Parameters:

aengine

Engine to query.

Returns:

The underlying Level Zero driver of the engine.

stream make_stream(
    const engine& aengine,
    ze_command_list_handle_t alist,
    bool aprofiling = false
    )

Creates an execution stream for a given engine associated with a Level Zero command list.

Parameters:

aengine	Engine object to use for the stream.
alist	Level Zero immediate command list to use for the stream.
aprofiling	Flag enabling GPU kernel profiling.

Returns:

An execution stream.

ze_command_list_handle_t get_list(const stream& astream)

Returns the Level Zero immediate command list associated with an execution stream.

Parameters:

astream

Execution stream to query.

Returns:

Level Zero immediate command list object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    std::vector<void*> handles = {}
    )

Creates a memory object with multiple handles.

If the handles vector is not provided the library will allocate all buffers as if all handles have the special value DNNL_MEMORY_ALLOCATE.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
handles	Handles of the memory buffers to use as underlying storages. For each element of the handles array the following applies: A USM pointer to the user-allocated buffer. In this case the library doesn’t own the buffer. The DNNL_MEMORY_ALLOCATE special value. Instructs the library to allocate the buffer for the memory object. In this case the library owns the buffer. The DNNL_MEMORY_NONE specific value. Instructs the library to create memory object without an underlying buffer.

Returns:

Created memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    void* handle
    )

Creates a memory object.

Unless handle is equal to DNNL_MEMORY_NONE or DNNL_MEMORY_ALLOCATE, the constructed memory object will have the underlying buffer set. In this case, the buffer will be initialized as if:

• dnnl::ze_interop::set_mem_object() has been called.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
handle	Handle of the memory buffer to use as an underlying storage. A USM pointer to the user-allocated buffer. In this case the library doesn’t own the buffer. The DNNL_MEMORY_ALLOCATE special value. Instructs the library to allocate the buffer for the memory object. In this case the library owns the buffer. The DNNL_MEMORY_NONE specific value. Instructs the library to create memory object without an underlying buffer.

Returns:

Created memory object.

ze_event_handle_t execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<ze_event_handle_t>& deps = {}
    )

Executes computations specified by the primitive in a specified stream and returns a Level Zero event.

Arguments are passed via an arguments map containing <index, memory object> pairs. The index must be one of the DNNL_ARG_* values such as DNNL_ARG_SRC, and the memory must have a memory descriptor matching the one returned by dnnl::primitive_desc::query_md (query::exec_arg_md, index) unless using dynamic shapes (see DNNL_RUNTIME_DIM_VAL).

Parameters:

aprimitive	Primitive to execute.
astream	Stream object. The stream must belong to the same engine as the primitive.
args	Arguments map.
deps	Optional vector with ze_event_handle_t dependencies.

Returns:

Output event.