.. index:: pair: group; OpenCL interoperability API .. _doxid-group__dnnl__api__ocl__interop: OpenCL interoperability API =========================== .. toctree:: :hidden: namespace_dnnl_ocl_interop.rst enum_dnnl_ocl_interop_memory_kind_t.rst Overview ~~~~~~~~ API extensions to interact with the underlying OpenCL run-time. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block // namespaces namespace :ref:`dnnl::ocl_interop`; // enums enum :ref:`dnnl_ocl_interop_memory_kind_t`; // global functions :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_memory_create`( :ref:`dnnl_memory_t`* memory, const :ref:`dnnl_memory_desc_t`* memory_desc, :ref:`dnnl_engine_t` engine, :ref:`dnnl_ocl_interop_memory_kind_t` memory_kind, void* handle ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_memory_get_memory_kind`( :ref:`const_dnnl_memory_t` memory, :ref:`dnnl_ocl_interop_memory_kind_t`* memory_kind ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_memory_get_mem_object`( :ref:`const_dnnl_memory_t` memory, cl_mem* mem_object ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_memory_set_mem_object`( :ref:`dnnl_memory_t` memory, cl_mem mem_object ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_engine_create`( :ref:`dnnl_engine_t`* engine, cl_device_id device, cl_context context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_engine_get_context`( :ref:`dnnl_engine_t` engine, cl_context* context ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_get_device`( :ref:`dnnl_engine_t` engine, cl_device_id* device ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_stream_create`( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, cl_command_queue queue ); :ref:`dnnl_status_t` DNNL_API :ref:`dnnl_ocl_interop_stream_get_command_queue`( :ref:`dnnl_stream_t` stream, cl_command_queue* queue ); .. _details-group__dnnl__api__ocl__interop: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ API extensions to interact with the underlying OpenCL run-time. .. rubric:: See also: :ref:`OpenCL Interoperability ` in developer guide Global Functions ---------------- .. index:: pair: function; dnnl_ocl_interop_memory_create .. _doxid-group__dnnl__api__ocl__interop_1ga5cafdbf17fcfad7154d773994b4390f0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_memory_create( :ref:`dnnl_memory_t`* memory, const :ref:`dnnl_memory_desc_t`* memory_desc, :ref:`dnnl_engine_t` engine, :ref:`dnnl_ocl_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() ` has been called, if ``memory_kind`` is equal to dnnl_ocl_interop_usm, or * :ref:`dnnl_ocl_interop_memory_set_mem_object() ` has been called, if ``memory_kind`` is equal to dnnl_ocl_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_ocl_interop_usm. * An OpenCL buffer. In this case the library doesn't own the buffer. Requires ``memory_kind`` be equal to be equal to dnnl_ocl_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_ocl_interop_memory_get_memory_kind .. _doxid-group__dnnl__api__ocl__interop_1gaa6c00a54ba3ca30d00d9e1c43e9b4bc2: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_memory_get_memory_kind( :ref:`const_dnnl_memory_t` memory, :ref:`dnnl_ocl_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_ocl_interop_memory_get_mem_object .. _doxid-group__dnnl__api__ocl__interop_1ga383b09734d764bb45872b2c65f7dad70: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_memory_get_mem_object( :ref:`const_dnnl_memory_t` memory, cl_mem* mem_object ) Returns an OpenCL memory object associated with a memory object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Memory object. * - mem_object - Output OpenCL memory object. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_memory_set_mem_object .. _doxid-group__dnnl__api__ocl__interop_1ga493946609c6bae83329241c4950edbce: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_memory_set_mem_object( :ref:`dnnl_memory_t` memory, cl_mem mem_object ) Sets OpenCL memory object associated with a memory object. For behavioral details, see :ref:`dnnl_memory_set_data_handle() `. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - memory - Memory object. * - mem_object - OpenCL memory object. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_engine_create .. _doxid-group__dnnl__api__ocl__interop_1ga52edd1810d72a2a08a881b122c7ada70: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_engine_create( :ref:`dnnl_engine_t`* engine, cl_device_id device, cl_context context ) Creates an engine associated with an OpenCL device and an OpenCL context. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Output engine. * - device - Underlying OpenCL device to use for the engine. * - context - Underlying OpenCL context to use for the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_engine_get_context .. _doxid-group__dnnl__api__ocl__interop_1ga6be452e1d11ad63d1f20a072258547c8: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_engine_get_context( :ref:`dnnl_engine_t` engine, cl_context* context ) Returns the OpenCL context associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - context - Output underlying OpenCL context of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_get_device .. _doxid-group__dnnl__api__ocl__interop_1gafd0a653afb5a16d4d1fc71cd0615e44a: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_get_device( :ref:`dnnl_engine_t` engine, cl_device_id* device ) Returns the OpenCL device associated with an engine. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - engine - Engine to query. * - device - Output underlying OpenCL device of the engine. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_stream_create .. _doxid-group__dnnl__api__ocl__interop_1ga9a9007c6661472d701b2bbfb43ddf07c: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_stream_create( :ref:`dnnl_stream_t`* stream, :ref:`dnnl_engine_t` engine, cl_command_queue queue ) Creates an execution stream for a given engine associated with an OpenCL command queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Output execution stream. * - engine - Engine to create the execution stream on. * - queue - OpenCL command queue to use. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise. .. index:: pair: function; dnnl_ocl_interop_stream_get_command_queue .. _doxid-group__dnnl__api__ocl__interop_1ga0290e83f9217e83eba910454348c0819: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`dnnl_status_t` DNNL_API dnnl_ocl_interop_stream_get_command_queue( :ref:`dnnl_stream_t` stream, cl_command_queue* queue ) Returns the OpenCL command queue associated with an execution stream. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - stream - Execution stream to query. * - queue - Output OpenCL command queue. .. rubric:: Returns: :ref:`dnnl_success ` on success and a status describing the error otherwise.