repository

Contents

namespace dnnl::sycl_interop

Overview

SYCL interoperability namespace. More…

namespace sycl_interop {

// enums

enum memory_kind;

// global functions

dnnl_sycl_interop_memory_kind_t convert_to_c(memory_kind akind);
engine make_engine(const sycl::device& adevice, const sycl::context& acontext);
sycl::context get_context(const engine& aengine);
sycl::device get_device(const engine& aengine);
stream make_stream(const engine& aengine, sycl::queue& aqueue);
sycl::queue get_queue(const stream& astream);

template <typename T, int ndims = 1>
sycl::buffer<T, ndims> get_buffer(const memory& amemory);

template <typename T, int ndims>
void set_buffer(
    memory& amemory,
    sycl::buffer<T, ndims>& abuffer
    );

memory_kind get_memory_kind(const memory& amemory);

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind kind,
    std::vector<void*> handles = {}
    );

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind kind,
    void* handle
    );

template <typename T, int ndims = 1>
memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    sycl::buffer<T, ndims>& abuffer
    );

sycl::event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<sycl::event>& deps = {}
    );

} // namespace sycl_interop

Detailed Documentation

SYCL interoperability namespace.

Global Functions

dnnl_sycl_interop_memory_kind_t convert_to_c(memory_kind akind)

Converts a memory allocation kind enum value from C++ API to C API type.

Parameters:

akind

C++ API memory allocation kind enum value.

Returns:

Corresponding C API memory allocation kind enum value.

engine make_engine(const sycl::device& adevice, const sycl::context& acontext)

Constructs an engine from SYCL device and context objects.

Parameters:

adevice	SYCL device.
acontext	SYCL context.

Returns:

Created engine.

sycl::context get_context(const engine& aengine)

Returns the SYCL context associated with an engine.

Parameters:

aengine

Engine to query.

Returns:

The underlying SYCL device of the engine.

sycl::device get_device(const engine& aengine)

Returns the SYCL device associated with an engine.

Parameters:

aengine

Engine to query.

Returns:

The underlying SYCL context of the engine.

stream make_stream(const engine& aengine, sycl::queue& aqueue)

Creates an execution stream for a given engine associated with a SYCL queue.

Parameters:

aengine	Engine object to use for the stream.
aqueue	SYCL queue to use for the stream.

Returns:

An execution stream.

sycl::queue get_queue(const stream& astream)

Returns the SYCL queue associated with an execution stream.

Parameters:

astream

Execution stream to query.

Returns:

SYCL queue object.

template <typename T, int ndims = 1>
sycl::buffer<T, ndims> get_buffer(const memory& amemory)

Returns the SYCL buffer associated with a memory object.

Throws an exception if the memory allocation kind associated with the memory object is not equal to dnnl::sycl_interop::memory_kind::buffer.

Parameters:

T	Type of the requested buffer.
ndims	Number of dimensions of the requested buffer.
amemory	Memory object.

Returns:

SYCL buffer associated with the memory object.

template <typename T, int ndims>
void set_buffer(
    memory& amemory,
    sycl::buffer<T, ndims>& abuffer
    )

Sets SYCL buffer associated with a memory object.

Parameters:

T	Type of the buffer.
ndims	Number of dimensions of the buffer.
amemory	Memory object to change.
abuffer	SYCL buffer.

memory_kind get_memory_kind(const memory& amemory)

Returns the memory allocation kind associated with a memory object.

Parameters:

amemory

A memory object.

Returns:

The underlying memory allocation kind of the memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind kind,
    std::vector<void*> handles = {}
    )

Creates a memory object with multiple handles.

If the handles vector is not provided the library will allocate all buffers as if all handles have the special value DNNL_MEMORY_ALLOCATE.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
kind	Memory allocation kind to specify the type 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::memory_kind::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::memory_kind::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:

Created memory object.

memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    memory_kind 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::memory_kind::usm, or

• dnnl::sycl_interop::set_buffer() has been called, if memory_kind is equal to dnnl::sycl_interop::memory_kind::buffer.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
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::memory_kind::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::memory_kind::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:

Created memory object.

template <typename T, int ndims = 1>
memory make_memory(
    const memory::desc& memory_desc,
    const engine& aengine,
    sycl::buffer<T, ndims>& abuffer
    )

Constructs a memory object from a SYCL buffer.

Parameters:

memory_desc	Memory descriptor.
aengine	Engine to use.
abuffer	A SYCL buffer to use.

Returns:

Created memory object.

sycl::event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<sycl::event>& deps = {}
    )

Executes computations specified by the primitive in a specified stream and returns a SYCL event.

Arguments are passed via an arguments map containing <index, memory object> pairs. The index must be one of the DNNL_ARG_* values such as DNNL_ARG_SRC, and the memory must have a memory descriptor matching the one returned by dnnl::primitive_desc::query_md (query::exec_arg_md, index) unless using dynamic shapes (see DNNL_RUNTIME_DIM_VAL).

Parameters:

aprimitive	Primitive to execute.
astream	Stream object. The stream must belong to the same engine as the primitive.
args	Arguments map.
deps	Optional vector with sycl::event dependencies.

Returns:

Output event.

SYCL interoperability API enum dnnl::sycl_interop::memory_kind