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.