.. index:: pair: group; SYCL interoperability API .. _doxid-group__dnnl__api__sycl__interop: SYCL interoperability API ========================= .. toctree:: :hidden: namespace_dnnl_sycl_interop.rst enum_dnnl_sycl_interop_memory_kind_t.rst Overview ~~~~~~~~ API extensions to interact with the underlying SYCL run-time. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // namespaces namespace :ref:`dnnl::sycl_interop`; // enums enum :ref:`dnnl_sycl_interop_memory_kind_t`; // global functions :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_engine_create`( :ref:`dnnl_engine_t`* engine, const void* device, const void* context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_engine_get_context`( :ref:`dnnl_engine_t` engine, void** context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_engine_get_device`( :ref:`dnnl_engine_t` engine, void** device ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_memory_create`( :ref:`dnnl_memory_t`* memory, :ref:`const_dnnl_memory_desc_t` memory_desc, :ref:`dnnl_engine_t` engine, :ref:`dnnl_sycl_interop_memory_kind_t` memory_kind, void* handle ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_memory_get_memory_kind`( :ref:`const_dnnl_memory_t` memory, :ref:`dnnl_sycl_interop_memory_kind_t`* memory_kind ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_memory_set_buffer`( :ref:`dnnl_memory_t` memory, void* buffer ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_stream_create`( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, void* queue ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_stream_get_queue`( :ref:`dnnl_stream_t` stream, void** queue ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_sycl_interop_primitive_execute`( :ref:`const_dnnl_primitive_t` primitive, :ref:`dnnl_stream_t` stream, int nargs, const :ref:`dnnl_exec_arg_t`* args, const void* deps, void* return_event ); .. _details-group__dnnl__api__sycl__interop: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ API extensions to interact with the underlying SYCL run-time. .. rubric:: See also: :ref:`DPC++ Interoperability ` in developer guide Global Functions ---------------- .. index:: pair: function; dnnl_sycl_interop_engine_create .. _doxid-group__dnnl__api__sycl__interop_1ga7d768ee527493380e13fdf2983b32b70: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_engine_create( :ref:`dnnl_engine_t`* engine, const void* device, const void* context ) Creates an engine associated with a SYCL device and a SYCL context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Output engine. * - device - Pointer to the SYCL device to use for the engine. * - context - Pointer to the SYCL context to use for the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_engine_get_context .. _doxid-group__dnnl__api__sycl__interop_1ga23b777c4d60c3dd9b542126973cb69a5: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_engine_get_context( :ref:`dnnl_engine_t` engine, void** context ) Returns the SYCL context associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - context - Pointer to the underlying SYCL context of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_engine_get_device .. _doxid-group__dnnl__api__sycl__interop_1gaf6a88b22743cc5ca54ad46ee88fbb71e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_engine_get_device( :ref:`dnnl_engine_t` engine, void** device ) Returns the SYCL device associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - device - Pointer to the underlying SYCL device of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_memory_create .. _doxid-group__dnnl__api__sycl__interop_1gafe0b9a934268c1954b87475d376d600e: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_memory_create( :ref:`dnnl_memory_t`* memory, :ref:`const_dnnl_memory_desc_t` memory_desc, :ref:`dnnl_engine_t` engine, :ref:`dnnl_sycl_interop_memory_kind_t` memory_kind, 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: * :ref:`dnnl_memory_set_data_handle() ` had been called, if ``memory_kind`` is equal to dnnl_sycl_interop_usm, or * :ref:`dnnl_sycl_interop_memory_set_buffer() ` has been called, if ``memory_kind`` is equal to dnnl_sycl_interop_buffer. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Output memory object. * - memory_desc - Memory descriptor. * - engine - Engine to use. * - memory_kind - Memory allocation kind to specify the type of handle. * - 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. Requires ``memory_kind`` to be equal to dnnl_sycl_interop_usm. * A pointer to SYCL buffer. In this case the library doesn't own the buffer. Requires ``memory_kind`` be equal to be equal to dnnl_sycl_interop_buffer. * The DNNL_MEMORY_ALLOCATE special value. Instructs the library to allocate the buffer that corresponds to the memory allocation kind ``memory_kind`` 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_sycl_interop_memory_get_memory_kind .. _doxid-group__dnnl__api__sycl__interop_1ga3c24bba041823efb72fd4ce003a4436c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_memory_get_memory_kind( :ref:`const_dnnl_memory_t` memory, :ref:`dnnl_sycl_interop_memory_kind_t`* memory_kind ) Returns the memory allocation kind associated with a memory object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Memory to query. * - memory_kind - Output underlying memory allocation kind of the memory object. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_memory_set_buffer .. _doxid-group__dnnl__api__sycl__interop_1ga62c1cb33d766f2035d83b7010db7adf9: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_memory_set_buffer( :ref:`dnnl_memory_t` memory, void* buffer ) Sets a SYCL buffer for a memory object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Memory object. * - buffer - SYCL buffer to be set in the memory object. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_stream_create .. _doxid-group__dnnl__api__sycl__interop_1ga64dc62b1586d688afcd110840e570cd5: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_stream_create( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, void* queue ) Creates an execution stream for a given engine associated with a SYCL queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Output execution stream. * - engine - Engine to create the execution stream on. * - queue - SYCL queue to use. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_stream_get_queue .. _doxid-group__dnnl__api__sycl__interop_1gab279fc3922a8b4ab59d4b328f1610172: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_stream_get_queue( :ref:`dnnl_stream_t` stream, void** queue ) Returns the SYCL queue associated with an execution stream. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Execution stream to query. * - queue - Output SYCL command queue. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_sycl_interop_primitive_execute .. _doxid-group__dnnl__api__sycl__interop_1ga49aea2229b2e3afcd66e31ef76fcbe64: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_sycl_interop_primitive_execute( :ref:`const_dnnl_primitive_t` primitive, :ref:`dnnl_stream_t` stream, int nargs, const :ref:`dnnl_exec_arg_t`* args, const void* deps, void* return_event ) Executes computations specified by the primitive in a specified stream and returns a SYCL 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). * - deps - A pointer to std::vector that contains dependencies. * - return_event - Output event. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise.