Intel® oneAPI Deep Neural Network Developer Guide and Reference
A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-13EC88B4-D8E9-4F68-9F3B-940D605C5E86
Visible to Intel only — GUID: GUID-13EC88B4-D8E9-4F68-9F3B-940D605C5E86
OpenCL Interoperability
Overview
oneDNN uses the OpenCL runtime for GPU engines to interact with the GPU. Users may need to use oneDNN with other code that uses OpenCL. For that purpose, the library provides API extensions to interoperate with underlying OpenCL objects. This interoperability API is defined in the dnnl_ocl.hpp header.
The interoperability API is provided for two scenarios:
Construction of oneDNN objects based on existing OpenCL objects
Accessing OpenCL objects for existing oneDNN objects
The mapping between oneDNN and OpenCL objects is provided in the following table:
oneDNN object |
OpenCL object(s) |
|---|---|
Engine |
cl_device_id and cl_context |
Stream |
cl_command_queue |
Memory (Buffer-based) |
cl_mem |
Memory (USM-based) |
Unified Shared Memory (USM) pointer |
The table below summarizes how to construct oneDNN objects based on OpenCL objects and how to query underlying OpenCL objects for existing oneDNN objects.
oneDNN object |
API to construct oneDNN object |
API to access OpenCL object(s) |
|---|---|---|
Engine |
dnnl::ocl_interop::get_device(const engine &)dnnl::ocl_interop::get_context(const engine &) |
|
Stream |
dnnl::ocl_interop::make_stream(const engine &, cl_command_queue) |
|
Memory (Buffer-based) |
||
Memory (USM-based) |
OpenCL Buffers and USM Interfaces for Memory Objects
The memory model in OpenCL is based on OpenCL buffers. Intel extension further extends the programming model with a Unified Shared Memory (USM) alternative, which provides the ability to allocate and use memory in a uniform way on host and OpenCL devices.
oneDNN supports both buffer and USM memory models. The buffer model is the default. The USM model requires using the interoperability API.
To construct a oneDNN memory object, use one of the following interfaces:
-
Constructs a USM-based or buffer-based memory object depending on memory allocation kind kind. The handle could be one of special values DNNL_MEMORY_ALLOCATE or DNNL_MEMORY_NONE, or it could be a user-provided USM pointer. The latter works only when kind is dnnl::ocl_interop::memory_kind::usm.
dnnl::memory(const memory::desc &, const engine &, void *)
Constructs a buffer-based memory object. The call is equivalent to calling the function above with with kind equal to dnnl::ocl_interop::memory_kind::buffer.
dnnl::ocl_interop::make_memory(const memory::desc &, const engine &, cl_mem)
Constructs a buffer-based memory object based on a user-provided OpenCL buffer.
To identify whether a memory object is USM-based or buffer-based, dnnl::ocl_interop::get_memory_kind() query can be used.
Handling Dependencies
OpenCL queues could be in-order or out-of-order. For out-of-order queues, the order of execution is defined by the dependencies between OpenCL tasks therefore users must handle the dependencies using OpenCL events.
oneDNN provides two mechanisms to handle dependencies:
dnnl::ocl_interop::execute() interface
This interface enables the user to pass dependencies between primitives using OpenCL events. In this case, the user is responsible for passing proper dependencies for every primitive execution.
In-order oneDNN stream
oneDNN enables the user to create in-order streams when submitted primitives are executed in the order they were submitted. Using in-order streams prevents possible read-before-write or concurrent read/write issues.