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.

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:

dnnl_memory_set_data_handle() has been called, if memory_kind is equal to dnnl_ocl_interop_usm, or
dnnl_ocl_interop_memory_set_mem_object() has been called, if memory_kind is equal to dnnl_ocl_interop_buffer.

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.

Runtime interoperability API namespace dnnl::ocl_interop

oneDNN v2.5.4 documentation

OpenCL interoperability API¶

Overview¶

Detailed Documentation¶

Global Functions¶