DMA Ze Implementation API

group aml_dma_ze

dma between devices and host using level zero.

Ze dma is an implementation of aml dma to transfer data between devices and host using level zero backend. This dma implementation uses asynchronous immediate command queues on a single target device. 

#include <aml/dma/ze.h>

See also

https://spec.oneapi.com/level-zero/latest/core/PROG.html#command-queues-and-command-lists

See also

aml_dma

Defines

AML_DMA_ZE_REQUEST_FLAGS_PENDING
AML_DMA_ZE_REQUEST_FLAGS_DONE

Functions

int aml_dma_ze_create(struct aml_dma **dma, ze_device_handle_t device, int ordinal, int index)

Creation of a dma engine for ze backend. This dma engine can only perform continuous and contiguous copies. The underlying dma immediate command queue is set with:

  • ZE_COMMAND_QUEUE_FLAG_EXPLICIT_ONLY: “command queue should be optimized for submission to a single device engine”

  • ZE_COMMAND_QUEUE_MODE_ASYNCHRONOUS: “Device execution is scheduled and will complete in future”

  • ZE_COMMAND_QUEUE_PRIORITY_NORMAL: “[default] normal priority”

See also

struct aml_dma_ze_data.

Parameters:

  • dma – A pointer to set with a new allocated dma.

  • device – The target device that will be used as a dma engine.

  • ordinal – the ordinal for the command queue underlying the dma, use 1 as default.

  • index – the index for the command queue underlying the dma, use 0 as defaut.

Returns:

-AML_ENOMEM if allocation failed.

Returns:

AML_SUCCESS on success.

Returns:

Another aml error code translated from a ze_result_t that can result from a ze resource creation (context, command queue, event pool).

int aml_dma_ze_barrier(struct aml_dma_data *data)

AML dma ze barrier operator.

Returns:

AML_SUCCESS on success.

Returns:

AML error code caused by ze backend on error.

int aml_dma_ze_destroy(struct aml_dma **dma)

Destroy a created dma and set it to NULL

int aml_dma_ze_request_create(struct aml_dma_data *data, struct aml_dma_request **req, struct aml_layout *dest, struct aml_layout *src, aml_dma_operator op, void *op_arg)

AML dma ze request creation operator.

Parameters:

  • data – The dma engine used to create request.

  • req – The pointer to the space where to allocate the request.

  • dest – The destination layout of the request.

  • src – The source layout of the request.

  • op – This dma implementation performs 1D copies only. Hence, op argument is ignored.

  • op_arg – unused.

Returns:

AML_SUCCESS on success.

Returns:

-AML_ENOMEM if allocation failed.

Returns:

Another aml error code translated from a ze_result_t that can result from a event creation or copy submission.

int aml_dma_ze_request_wait(struct aml_dma_data *dma, struct aml_dma_request **req)

AML dma ze request wait operator.

Parameters:

  • dma – The dma engine used to create request.

  • req – The pointer to the request to wait.

Returns:

AML_SUCCESS on success.

Returns:

Another aml error code translated from a ze_result_t resulting from event synchronization.

int aml_dma_ze_request_destroy(struct aml_dma_data *dma, struct aml_dma_request **req)

AML dma ze request deletion operator.

Parameters:

  • dma – The dma engine used to create request.

  • req – The pointer to the request to free.

Returns:

AML_SUCCESS on success.

int aml_dma_ze_copy_1D(struct aml_layout *dst, const struct aml_layout *src, void *arg)

Level Zero DMA operator implementation: Use only with aml_dma_ze_request_create() or higher level aml_dma_async_copy_custom(). This copy operator assumes 1D layout of contiguous elements and is compatible only with:

  • This dma ze implementation,

  • Dense source and destination layouts of one dimension. Make a flat copy of contiguous bytes in between two layout raw pointers. The size of the byte stream is computed as the product of dimensions and element size.

    See also

    aml_layout_dense

Parameters:

  • dst – The layout where to copy data. dst must be a 1 dimensional layout of contiguous elements.

  • src – The layout from where to copy data. src must be a 1 dimensional layout of contiguous elements.

  • arg – Ignored.

Returns:

AML_SUCCESS on success.

int aml_dma_ze_memcpy_op(struct aml_layout *dst, const struct aml_layout *src, void *arg)

Level Zero DMA operator implementation: Use only with aml_dma_ze_request_create() or higher level aml_dma_async_copy_custom(). This copy operator is compatible only with:

  • This dma ze implementation,

  • Flat source and destination pointers. Make a flat asychronous copy of contiguous bytes between two raw pointers. It casts input layout pointers into void* and assumes these are contiguous set of bytes to copy from src to dst in the linux memcpy() fashion using zeCommandListAppendMemoryCopy().

Parameters:

  • dst – [out] The destination (void*) of the copy casted into a struct aml_layout *.

  • src – [in] The source (void*) of the copy casted into a struct aml_layout *.

  • arg – [in] The size (size_t) of the copy casted into a void*.

Returns:

AML_SUCCESS

Variables

struct aml_dma_ops aml_dma_ze_ops

Default dma ops used at dma creation

struct aml_dma *aml_dma_ze_default

Dma using first device of first driver

struct aml_dma_ze_data
#include <ze.h>

Data structure of aml ze dma data.

struct aml_dma_ze_request
#include <ze.h>

aml ze request structure

struct aml_dma_ze_copy_args
#include <ze.h>

Structure passed to aml_dma_operator arg argument by the request created in aml_dma_ze_request_create(). All aml_dma_operator implementations can expect to obtain a pointer to this structure as arg argument. The pointer is valid only for the lifetime of the aml_dma_operator call.