DMAs: Moving Data Across Areas

group aml_dma

Management of low-level memory movements.

AML DMA (inspired by Direct Memory Access engines) is an abstraction over the ability to move data between places. A DMAs presents an interface that allows clients to create an asynchronous request to move data and to wait for this request to complete. Depending on the exact operation it is configured to do, the DMA might transform the data during the operation.

Implementations are mostly responsible for providing access to various types of execution engine for data movement itself.

../_images/dma.png

Defines

AML_DMA_REQUEST_TYPE_INVALID

Internal macros used for tracking DMA request types. Invalid request type. Used for marking inactive requests in the vector.

AML_DMA_REQUEST_TYPE_LAYOUT

The request is in the format (dest layout, src layout)

aml_dma_copy(dma, d, s)
aml_dma_async_copy(dma, r, d, s)

Typedefs

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

Type of the function used to perform the DMA between two layouts.

Param dst:

[out] destination layout

Param src:

[in] source layout

Param arg:

[inout] extra argument needed by the operator

Functions

int aml_dma_copy_custom(struct aml_dma *dma, struct aml_layout *dest, struct aml_layout *src, aml_dma_operator op, void *op_arg)

Request a synchronous data copy between two different buffers.

Layouts are copied internally if necessary, avoiding the need for users to keep the layouts alive during the request.

Parameters:
  • dma[inout] an initialized DMA structure.

  • dest[out] layout describing the destination.

  • src[in] layout describing the source.

  • op[in] optional custom operator for this dma

  • op_arg[in] optional argument to the operator

Returns:

0 if successful; an error code otherwise.

int aml_dma_async_copy_custom(struct aml_dma *dma, struct aml_dma_request **req, struct aml_layout *dest, struct aml_layout *src, aml_dma_operator op, void *op_arg)

Request a data copy between two different buffers.This is an asynchronous version of aml_dma_copy().

Layouts are copied internally if necessary, avoiding the need for users to keep the layouts alive during the request.

Parameters:
  • dma[inout] an initialized DMA structure.

  • req[inout] an address where the pointer to the newly assigned DMA request will be stored. Created requests via this call must be destroyed with a call to aml_dma_wait(). If req is NULL, then no request is stored in req and the user can only wait for the request with a call to aml_dma_barrier().

  • dest[out] layout describing the destination.

  • src[in] layout describing the source.

  • op[in] optional custom operator for this dma

  • op_arg[in] optional argument to the operator

Returns:

0 if successful; an error code otherwise.

int aml_dma_wait(struct aml_dma *dma, struct aml_dma_request **req)

Wait for an asynchronous DMA request to complete.

Parameters:
  • dma[inout] n initialized DMA structure.

  • req[inout] a DMA request obtained using aml_dma_async_*() calls.

Returns:

0 if successful; an error code otherwise.

int aml_dma_barrier(struct aml_dma *dma)

Block until all pending dma requests are finished. Requests obtained via aml_dma_async_copy_custom() must still be destroyed with aml_dma_wait().

Parameters:

dma[inout] n initialized DMA structure.

Returns:

0 if successful; an error code otherwise.

int aml_dma_cancel(struct aml_dma *dma, struct aml_dma_request **req)

Tear down an asynchronous DMA request before it completes.

Parameters:
  • dma[inout] an initialized DMA structure.

  • req[inout] a DMA request obtained using aml_dma_async_*() calls.

Returns:

0 if successful; an error code otherwise.

int aml_dma_fprintf(FILE *stream, const char *prefix, const struct aml_dma *dma)

Print on the file handle the metadata associated with this dma.

Parameters:
  • stream[in] the stream to print on

  • prefix[in] prefix to use on all lines

  • dma[in] DMA to print

Returns:

0 if successful, an error code otherwise.

int aml_copy_layout_transform_generic(struct aml_layout *dst, const struct aml_layout *src, const size_t *target_dims)

Helper to copy from one layout to another layout with different dimensions.

Parameters:
  • dst[out] destination layout

  • src[in] source layout

  • target_dims[in] a non_NULL array with the dimensions of the destination layout.

struct aml_dma_ops
#include <aml.h>

aml_dma_ops is a structure containing operations for a specific aml_dma implementation. These operation are operation are detailed in the structure. They are specific in:

  • the type of aml_area source and destination,

  • the progress engine performing the operation,

  • the type of of source and destination data structures.

Each different combination of these three points may require a different set of dma operations.

struct aml_dma
#include <aml.h>

aml_dma is an abstraction for (asynchronously) moving data from one area to another. The implementation of dma to use is depends on the source and destination areas. The appropriate dma choice is delegated to the user.

See also

struct aml_area.

Implementations