repository

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

enum dnnl_ocl_interop_memory_kind_t namespace dnnl::sycl_interop