SYCL interoperability API

Intel® oneAPI Deep Neural Network Developer Guide and Reference

Download PDF

ID 768875

Date 3/31/2025

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

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_create_v2(
    dnnl_memory_t* memory,
    const_dnnl_memory_desc_t memory_desc,
    dnnl_engine_t engine,
    dnnl_sycl_interop_memory_kind_t memory_kind,
    int nhandles,
    void** handles
    );

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

dnnl_memory_set_data_handle() had been called, if memory_kind is equal to dnnl_sycl_interop_usm, or
dnnl_sycl_interop_memory_set_buffer() has been called, if memory_kind is equal to dnnl_sycl_interop_buffer.

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_create_v2(
    dnnl_memory_t* memory,
    const_dnnl_memory_desc_t memory_desc,
    dnnl_engine_t engine,
    dnnl_sycl_interop_memory_kind_t memory_kind,
    int nhandles,
    void** handles
    )

Creates a memory object with multiple handles.

Parameters:

memory	Output memory object.
memory_desc	Memory descriptor.
engine	Engine to use.
memory_kind	Memory allocation kind to specify the type of handles.
nhandles	Number 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_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
    )

Sets a SYCL buffer for a memory object.

Parameters:

memory	Memory object.
buffer	SYCL buffer to be set in the memory object.

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.

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

SYCL interoperability API

Overview

Detailed Documentation