Developer Guide and Reference

  • 2022.1
  • 04/11/2022
  • Public Content
Contents

SYCL interoperability API

Overview

API extensions to interact with the underlying SYCL run-time. More…
// namespaces namespace dnnl::sycl_interop; // enums enum dnnl_sycl_interop_memory_kind_t; // global functions dnnl_status_t DNNL_API dnnl_sycl_interop_engine_create( dnnl_engine_t* engine, const void* device, const void* context ); dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_context( dnnl_engine_t engine, void** context ); dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_device( dnnl_engine_t engine, void** device ); dnnl_status_t DNNL_API dnnl_sycl_interop_memory_create( dnnl_memory_t* memory, const dnnl_memory_desc_t* memory_desc, dnnl_engine_t engine, dnnl_sycl_interop_memory_kind_t memory_kind, void* handle ); dnnl_status_t DNNL_API dnnl_sycl_interop_memory_get_memory_kind( const_dnnl_memory_t memory, dnnl_sycl_interop_memory_kind_t* memory_kind ); dnnl_status_t DNNL_API dnnl_sycl_interop_memory_set_buffer( dnnl_memory_t memory, void* buffer, dnnl_stream_t stream ); dnnl_status_t DNNL_API dnnl_sycl_interop_stream_create( dnnl_stream_t* stream, dnnl_engine_t engine, void* queue ); dnnl_status_t DNNL_API dnnl_sycl_interop_stream_get_queue( dnnl_stream_t stream, void** queue ); dnnl_status_t DNNL_API dnnl_sycl_interop_primitive_execute( const_dnnl_primitive_t primitive, dnnl_stream_t stream, int nargs, const dnnl_exec_arg_t* args, const void* deps, void* return_event );

Detailed Documentation

API extensions to interact with the underlying SYCL run-time.
See also:
DPC++ Interoperability in developer guide
Global Functions
dnnl_status_t DNNL_API dnnl_sycl_interop_engine_create( dnnl_engine_t* engine, const void* device, const void* context )
Creates an engine associated with a SYCL device and a SYCL context.
Parameters:
engine
Output engine.
device
Pointer to the SYCL device to use for the engine.
context
Pointer to the SYCL context to use for the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_context( dnnl_engine_t engine, void** context )
Returns the SYCL context associated with an engine.
Parameters:
engine
Engine to query.
context
Pointer to the underlying SYCL context of the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_device( dnnl_engine_t engine, void** device )
Returns the SYCL device associated with an engine.
Parameters:
engine
Engine to query.
device
Pointer to the underlying SYCL device of the engine.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_memory_create( dnnl_memory_t* memory, const dnnl_memory_desc_t* memory_desc, dnnl_engine_t engine, dnnl_sycl_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:
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_sycl_interop_usm.
  • A pointer to SYCL buffer. In this case the library doesn’t own the buffer. Requires
    memory_kind
    be equal to be equal to dnnl_sycl_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_sycl_interop_memory_get_memory_kind( const_dnnl_memory_t memory, dnnl_sycl_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_sycl_interop_memory_set_buffer( dnnl_memory_t memory, void* buffer, dnnl_stream_t stream )
Sets a SYCL buffer for a memory object.
Parameters:
memory
Memory object.
buffer
SYCL buffer to be set in the memory object.
stream
Stream to use to execute padding in.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_stream_create( dnnl_stream_t* stream, dnnl_engine_t engine, void* queue )
Creates an execution stream for a given engine associated with a SYCL queue.
Parameters:
stream
Output execution stream.
engine
Engine to create the execution stream on.
queue
SYCL queue to use.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_stream_get_queue( dnnl_stream_t stream, void** queue )
Returns the SYCL queue associated with an execution stream.
Parameters:
stream
Execution stream to query.
queue
Output SYCL command queue.
Returns:
dnnl_success on success and a status describing the error otherwise.
dnnl_status_t DNNL_API dnnl_sycl_interop_primitive_execute( const_dnnl_primitive_t primitive, dnnl_stream_t stream, int nargs, const dnnl_exec_arg_t* args, const void* deps, void* return_event )
Executes computations specified by the primitive in a specified stream and returns a SYCL event.
Parameters:
primitive
Primitive to execute.
stream
Stream to use.
nargs
Number of arguments.
args
Array of arguments. Each argument is an <index, dnnl_memory_t> pair. The index is one of the
DNNL_ARG_*
values such as
DNNL_ARG_SRC
. Unless runtime shapes are used (see DNNL_RUNTIME_DIM_VAL), the memory object must have the same memory descriptor as that returned by dnnl_primitive_desc_query_md (dnnl_query_exec_arg_md, index).
deps
A pointer to std::vector<sycl::event> that contains dependencies.
return_event
Output event.
Returns:
dnnl_success on success and a status describing the error otherwise.

Product and Performance Information

1

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