Developer Guide and Reference

  • 2022.1
  • 04/11/2022
  • Public Content
Contents

OpenCL interoperability API

Overview

API extensions to interact with the underlying OpenCL run-time. More…
// namespaces namespace dnnl::ocl_interop; // enums enum dnnl_ocl_interop_memory_kind_t; // global functions dnnl_status_t DNNL_API dnnl_ocl_interop_memory_create( dnnl_memory_t* memory, const dnnl_memory_desc_t* memory_desc, dnnl_engine_t engine, dnnl_ocl_interop_memory_kind_t memory_kind, void* handle ); dnnl_status_t DNNL_API dnnl_ocl_interop_memory_get_memory_kind( const_dnnl_memory_t memory, dnnl_ocl_interop_memory_kind_t* memory_kind ); dnnl_status_t DNNL_API dnnl_ocl_interop_memory_get_mem_object( const_dnnl_memory_t memory, cl_mem* mem_object ); dnnl_status_t DNNL_API dnnl_ocl_interop_memory_set_mem_object( dnnl_memory_t memory, cl_mem mem_object ); dnnl_status_t DNNL_API dnnl_ocl_interop_engine_create( dnnl_engine_t* engine, cl_device_id device, cl_context context ); dnnl_status_t DNNL_API dnnl_ocl_interop_engine_get_context( dnnl_engine_t engine, cl_context* context ); dnnl_status_t DNNL_API dnnl_ocl_interop_get_device( dnnl_engine_t engine, cl_device_id* device ); dnnl_status_t DNNL_API dnnl_ocl_interop_stream_create( dnnl_stream_t* stream, dnnl_engine_t engine, cl_command_queue queue ); dnnl_status_t DNNL_API dnnl_ocl_interop_stream_get_command_queue( dnnl_stream_t stream, cl_command_queue* queue );

Detailed Documentation

API extensions to interact with the underlying OpenCL run-time.
See also:
OpenCL Interoperability in developer guide
Global Functions
dnnl_status_t DNNL_API dnnl_ocl_interop_memory_create( dnnl_memory_t* memory, const dnnl_memory_desc_t* memory_desc, dnnl_engine_t engine, 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:
Parameters:
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.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_memory_get_memory_kind( const_dnnl_memory_t memory, dnnl_ocl_interop_memory_kind_t* memory_kind )
Returns the memory allocation kind associated with a memory object.
Parameters:
memory
Memory to query.
memory_kind
Output underlying memory allocation kind of the memory object.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_memory_get_mem_object( const_dnnl_memory_t memory, cl_mem* mem_object )
Returns an OpenCL memory object associated with a memory object.
Parameters:
memory
Memory object.
mem_object
Output OpenCL memory object.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_memory_set_mem_object( dnnl_memory_t memory, cl_mem mem_object )
Sets OpenCL memory object associated with a memory object.
For behavioral details, see dnnl_memory_set_data_handle().
Parameters:
memory
Memory object.
mem_object
OpenCL memory object.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_engine_create( dnnl_engine_t* engine, cl_device_id device, cl_context context )
Creates an engine associated with an OpenCL device and an OpenCL context.
Parameters:
engine
Output engine.
device
Underlying OpenCL device to use for the engine.
context
Underlying OpenCL context to use for the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_engine_get_context( dnnl_engine_t engine, cl_context* context )
Returns the OpenCL context associated with an engine.
Parameters:
engine
Engine to query.
context
Output underlying OpenCL context of the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_get_device( dnnl_engine_t engine, cl_device_id* device )
Returns the OpenCL device associated with an engine.
Parameters:
engine
Engine to query.
device
Output underlying OpenCL device of the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_stream_create( dnnl_stream_t* stream, dnnl_engine_t engine, cl_command_queue queue )
Creates an execution stream for a given engine associated with an OpenCL command queue.
Parameters:
stream
Output execution stream.
engine
Engine to create the execution stream on.
queue
OpenCL command queue to use.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_ocl_interop_stream_get_command_queue( dnnl_stream_t stream, cl_command_queue* queue )
Returns the OpenCL command queue associated with an execution stream.
Parameters:
stream
Execution stream to query.
queue
Output OpenCL command queue.
Returns:
dnnl_success on success and a status describing the error otherwise.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.