Programming Guide

Contents

oneDNN Usage

oneDNN supports systems based on Intel 64 architecture or compatible processors. A full list of supported CPU and graphics hardware is available from the Intel oneAPI Deep Neural Network Library System Requirements.
oneDNN detects the instruction set architecture (ISA) in the runtime and uses online generation to deploy the code optimized for the latest supported ISA.
Several packages are available for each operating system to ensure interoperability with CPU or GPU runtime libraries used by the application.
Package Availability by Operating System
Configuration
Dependency
cpu_dpcpp_gpu_dpcpp
DPC++ runtime
cpu_iomp
Intel OpenMP* runtime
cpu_gomp
GNU* OpenMP runtime
cpu_vcomp
Microsoft* Visual C++ OpenMP runtime
cpu_tbb
Intel oneAPI Threading Building Blocks
The packages do not include library dependencies and these need to be resolved in the application at build time with oneAPI toolkits or third-party tools.
When used in the SYCL* environment, oneDNN relies on the DPC++ SYCL runtime to interact with CPU or GPU hardware. oneDNN may be used with other code that uses SYCL. To do this, oneDNN provides API extensions to interoperate with underlying SYCL objects.
One of the possible scenarios is executing a SYCL kernel for a custom operation not provided by oneDNN. In this case, oneDNN provides all necessary APIs to seamlessly submit a kernel, sharing the execution context with oneDNN: using the same device and queue.
The interoperability API is provided for two scenarios:
  • Construction of oneDNN objects based on existing SYCL objects
  • Accessing SYCL objects for existing oneDNN objects
The mapping between oneDNN and SYCL objects is summarized in the tables below.
oneDNN and SYCL Object Mapping 1
oneDNN Objects
SYCL Objects
Engine
cl::sycl::device and cl::sycl::context
Stream
cl::sycl::queue
Memory
cl::sycl::buffer<uint8_t, 1> or Unified Shared Memory (USM) pointer
Internally, library memory objects use 1D uint8_t SYCL buffers, however SYCL buffers of a different type can be used to initialize and access memory. In this case, buffers will be reinterpreted to the underlying type
cl::sycl::buffer<uint8_t, 1>
.
oneDNN and SYCL Object Mapping 2
oneDNN Object
Constructing from SYCL Object
Engine
dnnl::sycl_interop::make_engine(sycl_dev, sycl_ctx)
Stream
dnnl::sycl_interop::make_stream(engine, sycl_queue)
Memory
USM based:
dnnl::memory(memory_desc, engine, usm_ptr)
Buffer based:
dnnl::sycl_interop::make_memory(memory_desc, engine, sycl_buf)
oneDNN and SYCL Object Mapping 3
oneDNN Object
Extracting SYCL Object
Engine
dnnl::sycl_interop::get_device(engine)
dnnl::sycl_interop::get_context(engine)
Stream
dnnl::sycl_interop::get_queue(stream)
Memory
USM pointer:
dnnl::memory::get_data_handle()
Buffer:
dnnl::sycl_interop::get_buffer(memory)
  • Building applications with oneDNN requires a compiler. The Intel oneAPI DPC++/C++ Compiler is available as part of the Intel oneAPI Base Toolkit.
  • You must include dnnl_sycl.hpp to enable the SYCL-interop API.
  • Because OpenMP does not rely on the passing of runtime objects, it does not require an interoperability API to work with oneDNN.

Product and Performance Information

1

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