.. index:: pair: group; Level Zero interoperability API .. _doxid-group__dnnl__api__ze__interop: Level Zero interoperability API =============================== .. toctree:: :hidden: namespace_dnnl_ze_interop.rst Overview ~~~~~~~~ API extensions to interact with the underlying Level Zero run-time. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // namespaces namespace :ref:`dnnl::ze_interop`; // global functions :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_get_cache_blob_id`( ze_driver_handle_t driver, ze_device_handle_t device, size_t* size, uint8_t* cache_blob_id ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_get_cache_blob`( :ref:`dnnl_engine_t` engine, size_t* size, uint8_t* cache_blob ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_create_from_cache_blob`( :ref:`dnnl_engine_t`* engine, ze_driver_handle_t driver, ze_device_handle_t device, ze_context_handle_t context, size_t size, const uint8_t* cache_blob ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_create`( :ref:`dnnl_engine_t`* engine, ze_driver_handle_t driver, ze_device_handle_t device, ze_context_handle_t context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_get_context`( :ref:`dnnl_engine_t` engine, ze_context_handle_t* context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_get_device`( :ref:`dnnl_engine_t` engine, ze_device_handle_t* device ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_engine_get_driver`( :ref:`dnnl_engine_t` engine, ze_driver_handle_t* driver ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_stream_create`( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, ze_command_list_handle_t list, int profiling ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_stream_get_list`( :ref:`dnnl_stream_t` stream, ze_command_list_handle_t* list ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_memory_create`( :ref:`dnnl_memory_t`* memory, :ref:`const_dnnl_memory_desc_t` memory_desc, :ref:`dnnl_engine_t` engine, int nhandles, void** handles ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ze_interop_primitive_execute`( :ref:`const_dnnl_primitive_t` primitive, :ref:`dnnl_stream_t` stream, int nargs, const :ref:`dnnl_exec_arg_t`* args, int ndeps, const ze_event_handle_t* deps, ze_event_handle_t* return_event ); .. _details-group__dnnl__api__ze__interop: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ API extensions to interact with the underlying Level Zero run-time. .. rubric:: See also: :ref:`Level Zero Interoperability ` in developer guide Global Functions ---------------- .. index:: pair: function; dnnl_ze_interop_engine_get_cache_blob_id .. _doxid-group__dnnl__api__ze__interop_1gab47027d3d859c24a07060b0ffc19f2da: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_get_cache_blob_id( ze_driver_handle_t driver, ze_device_handle_t device, size_t* size, uint8_t* cache_blob_id ) Retrieves a cache blob ID for the Level Zero device. .. warning:: This API is intended to be used with :ref:`dnnl_ze_interop_engine_get_cache_blob() ` and :ref:`dnnl_ze_interop_engine_create_from_cache_blob() `. The returned cache blob ID can only be used as an ID of the cache blob returned by :ref:`dnnl_ze_interop_engine_get_cache_blob() `. .. 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. (:ref:`dnnl_ze_interop_engine_get_cache_blob ` will return an empty cache blob). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - driver - A Level Zero driver. * - device - A Level Zero device. * - size - Size of the cache blob ID in bytes. * - cache_blob_id - Cache blob id of size ``size``. If the ``cache_blob_id`` is nullptr then the size of the cache blob ID is returned in ``size``. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_get_cache_blob .. _doxid-group__dnnl__api__ze__interop_1gae48eaec22ed32acb6ff38e0bc0d7b8e5: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_get_cache_blob( :ref:`dnnl_engine_t` engine, size_t* size, uint8_t* cache_blob ) Retrieves a cache blob associated with the given engine. .. note:: The cache blob can be empty (``size`` will be 0 and ``cache_blob`` will be nullptr) 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 :ref:`dnnl_ze_interop_engine_create_from_cache_blob() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query for the cache blob. * - size - Size of the cache blob in bytes. * - cache_blob - Cache blob of size ``size``. If the ``cache_blob`` is nullptr then the size of the cache blob is returned in ``size``. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_create_from_cache_blob .. _doxid-group__dnnl__api__ze__interop_1gaf83e20191a60b265e4e6f1f841266b04: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_create_from_cache_blob( :ref:`dnnl_engine_t`* engine, ze_driver_handle_t driver, ze_device_handle_t device, ze_context_handle_t context, size_t size, const uint8_t* cache_blob ) Creates an engine from the given cache blob. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Output engine. * - 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. * - size - Size of the cache blob in bytes. * - cache_blob - Cache blob of size ``size``. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_create .. _doxid-group__dnnl__api__ze__interop_1gacd1128872929a2949781027c9a53bb9d: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_create( :ref:`dnnl_engine_t`* engine, ze_driver_handle_t driver, ze_device_handle_t device, ze_context_handle_t context ) Creates an engine associated with a Level Zero device and a Level Zero context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Output engine. * - driver - Pointer to the Level Zero driver to use for the engine. * - device - Pointer to the Level Zero device to use for the engine. * - context - Pointer to the Level Zero context to use for the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_get_context .. _doxid-group__dnnl__api__ze__interop_1gaac241e8e0fd2821810c37b1654f4b860: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_get_context( :ref:`dnnl_engine_t` engine, ze_context_handle_t* context ) Returns the Level Zero context associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - context - Pointer to the underlying Level Zero context of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_get_device .. _doxid-group__dnnl__api__ze__interop_1ga75268a10b903481ec94b4eb16a2e5843: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_get_device( :ref:`dnnl_engine_t` engine, ze_device_handle_t* device ) Returns the Level Zero device associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - device - Pointer to the underlying Level Zero device of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_engine_get_driver .. _doxid-group__dnnl__api__ze__interop_1gae276cf5c283bfb4faa7e186e76fa466a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_engine_get_driver( :ref:`dnnl_engine_t` engine, ze_driver_handle_t* driver ) Returns the Level Zero driver associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - driver - Pointer to the underlying Level Zero driver of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_stream_create .. _doxid-group__dnnl__api__ze__interop_1ga34230de0437ced14603f85f7901fba93: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_stream_create( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, ze_command_list_handle_t list, int profiling ) Creates an execution stream for a given engine associated with a Level Zero command list. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Output execution stream. * - engine - Engine to create the execution stream on. * - list - Level Zero command list to use. * - profiling - Flag enabling GPU kernels profiling. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_stream_get_list .. _doxid-group__dnnl__api__ze__interop_1ga410b2e08f2bd94287bcbe08c3778918a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_stream_get_list( :ref:`dnnl_stream_t` stream, ze_command_list_handle_t* list ) Returns the Level Zero command list associated with an execution stream. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Execution stream to query. * - list - Output Level Zero command list. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_memory_create .. _doxid-group__dnnl__api__ze__interop_1gad39c5ee134fbeadb3f2ea58418106e7e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_memory_create( :ref:`dnnl_memory_t`* memory, :ref:`const_dnnl_memory_desc_t` memory_desc, :ref:`dnnl_engine_t` engine, int nhandles, void** handles ) 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 :ref:`dnnl_memory_set_data_handle() ` had been called. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Output memory object. * - memory_desc - Memory descriptor. * - engine - Engine to use. * - nhandles - Number of handles. * - handles - Handles of the memory buffers to use as underlying storages. * 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. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ze_interop_primitive_execute .. _doxid-group__dnnl__api__ze__interop_1ga9d01549ef3799f20eed6109a2792c7e0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ze_interop_primitive_execute( :ref:`const_dnnl_primitive_t` primitive, :ref:`dnnl_stream_t` stream, int nargs, const :ref:`dnnl_exec_arg_t`* args, int ndeps, const ze_event_handle_t* deps, ze_event_handle_t* return_event ) Executes computations specified by the primitive in a specified stream and returns a Level Zero event. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - primitive - Primitive to execute. * - stream - Stream to use. * - nargs - Number of arguments. * - args - Array of arguments. Each argument is an `> pair. The index is one of the ``DNNL_ARG_*`` values such as ``DNNL_ARG_SRC``. Unless runtime shapes are used (see :ref:`DNNL_RUNTIME_DIM_VAL `), the memory object must have the same memory descriptor as that returned by :ref:`dnnl_primitive_desc_query_md ` (:ref:`dnnl_query_exec_arg_md `, index). * - ndeps - Number of dependencies. * - deps - A pointer to a vector of size ``ndeps`` that contains dependencies. * - return_event - Output event. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise.