namespace dnnl::ocl

Intel® oneAPI Deep Neural Network Developer Guide and Reference

Download PDF

ID 768875

Date 9/17/2024

Version

Public

Visible to Intel only — GUID: GUID-5ECC57D8-878D-4A67-85D6-3908566FA9A3

View Details

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,
    std::vector<void*> handles = {}
    );

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    std::vector<cl_mem> mem_objects
    );

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

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,
    std::vector<void*> handles = {}
    )

Creates a memory object with multiple handles.

If the handles vector is not provided the library will allocate all buffers as if all handles have the special value DNNL_MEMORY_ALLOCATE.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
kind	Memory allocation kind to specify the type of handles.
handles	Handles of the memory buffers to use as underlying storages. For each element of the `handles` array the following applies: 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.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    std::vector<cl_mem> mem_objects
    )

Constructs a memory object with multiple OpenCL buffers.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
mem_objects	A vector of OpenCL buffers to use.

Returns:

Created memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind 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() had been called, if memory_kind is equal to dnnl::ocl_interop::memory_kind::usm, or
dnnl::ocl_interop::set_mem_object() has been called, if memory_kind is equal to dnnl::ocl_interop::memory_kind::buffer.

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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® oneAPI Deep Neural Network Developer Guide and Reference

namespace dnnl::ocl_interop

Overview

Detailed Documentation