.rst .pdf

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 cl::sycl::device& adevice,
    const cl::sycl::context& acontext
    );

cl::sycl::context get_context(const engine& aengine);
cl::sycl::device get_device(const engine& aengine);
stream make_stream(const engine& aengine, cl::sycl::queue& aqueue);
cl::sycl::queue get_queue(const stream& astream);

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

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

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

memory_kind get_memory_kind(const memory& amemory);

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

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

cl::sycl::event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<cl::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 cl::sycl::device& adevice,
    const cl::sycl::context& acontext
    )

Constructs an engine from SYCL device and context objects.

Parameters:

adevice	SYCL device.
acontext	SYCL context.

Returns:

Created engine.

cl::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.

cl::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, cl::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.

cl::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>
cl::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,
    cl::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.

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

Sets SYCL buffer associated with a memory object in a specified stream.

Parameters:

T	Type of the buffer.
ndims	Number of dimensions of the buffer.
amemory	Memory object to change.
abuffer	SYCL buffer.
astream	Stream to use to execute padding in.

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,
    void* handle = DNNL_MEMORY_ALLOCATE
    )

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,
    cl::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.

cl::sycl::event execute(
    const dnnl::primitive& aprimitive,
    const stream& astream,
    const std::unordered_map<int, memory>& args,
    const std::vector<cl::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 cl::sycl::event dependencies.

Returns:

Output event.

SYCL interoperability API enum dnnl::sycl_interop::memory_kind