namespace dnnl::ocl_interop

Overview

OpenCL interoperability namespace. More…

namespace ocl_interop {

// enums

enum memory_kind;

// global functions

dnnl_ocl_interop_memory_kind_t convert_to_c(memory_kind akind);
std::vector<uint8_t> get_engine_cache_blob_id(cl_device_id device);
std::vector<uint8_t> get_engine_cache_blob(const engine& aengine);

engine make_engine(
    cl_device_id device,
    cl_context context,
    const std::vector<uint8_t>& cache_blob
    );

engine make_engine(cl_device_id device, cl_context context);
cl_context get_context(const engine& aengine);
cl_device_id get_device(const engine& aengine);
stream make_stream(const engine& aengine, cl_command_queue queue);
cl_command_queue get_command_queue(const stream& astream);
cl_mem get_mem_object(const memory& amemory);
void set_mem_object(memory& amemory, cl_mem mem_object);
memory_kind get_memory_kind(const memory& amemory);

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind kind,
    void* handle = DNNL_MEMORY_ALLOCATE
    );

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    cl_mem mem_object
    );

cl_event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<cl_event>& deps = {}
    );

} // namespace ocl_interop

Detailed Documentation

OpenCL interoperability namespace.

Global Functions

dnnl_ocl_interop_memory_kind_t convert_to_c(memory_kind akind)

Converts a memory allocation kind enum value from C++ API to C API type.

Parameters:

akind

C++ API memory allocation kind enum value.

Returns:

Corresponding C API memory allocation kind enum value.

std::vector<uint8_t> get_engine_cache_blob_id(cl_device_id device)

Returns the cache blob ID of the OpenCL device.

Warning

This API is intended to be used with dnnl::ocl_interop::get_engine_cache_blob() and dnnl::ocl_interop::make_engine(cl_device_id, cl_context, const std::vector<uint8_t> &). The returned cache blob ID can only be used as an ID of the cache blob returned by dnnl::ocl_interop::get_engine_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. (dnnl_ocl_interop_engine_get_cache_blob will return an empty cache blob).

Parameters:

device

An OpenCL device.

Returns:

A vector containing the cache blob ID.

std::vector<uint8_t> get_engine_cache_blob(const engine& aengine)

Returns a cache blob for the engine.

Note

The cache blob vector can be empty 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 dnnl::ocl_interop::make_engine(cl_device_id, cl_context, const std::vector<uint8_t> &)

Parameters:

aengine

Engine to query for the cache blob.

Returns:

Vector containing the cache blob.

engine make_engine(
    cl_device_id device,
    cl_context context,
    const std::vector<uint8_t>& cache_blob
    )

Constructs an engine from the given cache blob.

Parameters:

device

The OpenCL device that this engine will encapsulate.

context

The OpenCL context (containing the device) that this engine will use for all operations.

cache_blob

Cache blob.

Returns:

An engine.

engine make_engine(cl_device_id device, cl_context context)

Constructs an engine from OpenCL device and context objects.

Parameters:

device

The OpenCL device that this engine will encapsulate.

context

The OpenCL context (containing the device) that this engine will use for all operations.

Returns:

An engine.

cl_context get_context(const engine& aengine)

Returns OpenCL context associated with the engine.

Parameters:

aengine

An engine.

Returns:

Underlying OpenCL context.

cl_device_id get_device(const engine& aengine)

Returns OpenCL device associated with the engine.

Parameters:

aengine

An engine.

Returns:

Underlying OpenCL device.

stream make_stream(const engine& aengine, cl_command_queue queue)

Constructs an execution stream for the specified engine and OpenCL queue.

Parameters:

aengine

Engine to create the stream on.

queue

OpenCL queue to use for the stream.

Returns:

An execution stream.

cl_command_queue get_command_queue(const stream& astream)

Returns OpenCL queue object associated with the execution stream.

Parameters:

astream

An execution stream.

Returns:

Underlying OpenCL queue.

cl_mem get_mem_object(const memory& amemory)

Returns the OpenCL memory object associated with the memory object.

Parameters:

amemory

A memory object.

Returns:

Underlying OpenCL memory object.

void set_mem_object(memory& amemory, cl_mem mem_object)

Sets the OpenCL memory object associated with the memory object.

For behavioral details see memory::set_data_handle().

Parameters:

amemory

A memory object.

mem_object

OpenCL cl_mem object to use as the underlying storage. It must have at least get_desc().get_size() bytes allocated.

memory_kind get_memory_kind(const memory& amemory)

Returns the memory allocation kind associated with a memory object.

Parameters:

amemory

A memory object.

Returns:

The underlying memory allocation kind of the memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind kind,
    void* handle = DNNL_MEMORY_ALLOCATE
    )

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_desc

Memory descriptor.

aengine

Engine to use.

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::memory_kind::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::memory_kind::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:

Created memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    cl_mem mem_object
    )

Constructs a memory object from an OpenCL buffer.

Parameters:

memory_desc

Memory descriptor.

aengine

Engine to use.

mem_object

An OpenCL buffer to use.

Returns:

Created memory object.

cl_event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<cl_event>& deps = {}
    )

Executes computations specified by the primitive in a specified stream and returns a SYCL event.

Arguments are passed via an arguments map containing <index, memory object> pairs. The index must be one of the DNNL_ARG_* values such as DNNL_ARG_SRC, and the memory must have a memory descriptor matching the one returned by dnnl::primitive_desc::query_md (query::exec_arg_md, index) unless using dynamic shapes (see DNNL_RUNTIME_DIM_VAL).

Parameters:

aprimitive

Primitive to execute.

astream

Stream object. The stream must belong to the same engine as the primitive.

args

Arguments map.

deps

Optional vector with cl_event dependencies.

Returns:

Output event. It’s the user’s responsibility to manage lifetime of the event.