Commit f75a7bf8 authored by ndenoyelle's avatar ndenoyelle

polish dma doc

parent 4b129cab
Pipeline #8930 passed with stages
in 9 minutes and 58 seconds
...@@ -730,13 +730,41 @@ struct aml_layout *aml_tiling_index_byid(const struct aml_tiling *tiling, ...@@ -730,13 +730,41 @@ struct aml_layout *aml_tiling_index_byid(const struct aml_tiling *tiling,
* @brief Management of low-level memory movements. * @brief Management of low-level memory movements.
* *
* AML DMA (inspired by Direct Memory Access engines) is an abstraction over the * 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 * ability to move data between areas and between layouts.
* clients to create an asynchronous request to move data and to wait for this * @see aml_area
* request to complete. Depending on the exact operation it is configured to do, * @see aml_layout
* the DMA might transform the data during the operation. * Through DMAs, AML exposes an interface allowing clients to instanciate
* asynchronous requests to copy data and wait for these requests to complete.
* @see aml_dma_copy()
* @see aml_dma_async_copy()
* @see aml_dma_request
*
* The performance of the execution of a dma is highly dependent on the type of
* source and destination layouts. For instance a copy of continuous and
* contiguous address space can easily be vectorized, packed, etc...
* The optimization of such a copy is encapsulated by the aml_dma_operator
* abstraction. aml_dma_operator is a function provided by the dma implementer
* that is passed to aml_dma_copy() and aml_dma_async_copy() by the user.
* With the knowledge of source and destination layouts, the user is able to
* select a good aml_dma_operator to make the copy faster.
* @see aml_dma_operator
* *
* Implementations are mostly responsible for providing access to various types * Implementing a DMA requires to implement 4 abstractions:
* of execution engine for data movement itself. * * struct aml_dma_request
* * struct aml_dma_data
* * struct aml_dma_ops
* * fn aml_dma_operator
* A DMA engine is an implementation of a struct aml_dma that is further
* provided to aml_dma_*() functions from the high level interface.
* The struct contains an internal data handle (aml_dma_data) to manage the
* engine, and a set of functions (aml_dma_ops) required to implement the
* high level interface. aml_dma_ops will allow to create a aml_dma_request
* to handle a transfer. A request is responsible for managing the transfer
* performed by a aml_dma_operator. When a request is iniciated by a user,
* the latter will need to provide a performant implementation of the
* aml_dma_operator, which is provided by the dma implementation.
* @see aml_dma_data
* @see aml_dma_ops
* *
* @image html dma.png width=600 * @image html dma.png width=600
* @{ * @{
...@@ -745,43 +773,43 @@ struct aml_layout *aml_tiling_index_byid(const struct aml_tiling *tiling, ...@@ -745,43 +773,43 @@ struct aml_layout *aml_tiling_index_byid(const struct aml_tiling *tiling,
//////////////////////////////////////////////////////////////////////////////// ////////////////////////////////////////////////////////////////////////////////
/** /**
* aml_dma is mainly used to asynchronously move data. * Handle output of aml_dma_async_copy() to wait handle dma completion
* aml_dma_request is an opaque structure containing information * and errors.
* about ongoing request for data movement in a dma operation. * Implementers of struct aml_dma_ops will populate and destroy requests.
* @see aml_dma_ops * @see aml_dma_ops
* @see aml_dma_async_copy() * @see aml_dma_async_copy()
**/ **/
struct aml_dma_request; struct aml_dma_request;
/** /**
* Opaque handle implemented by each aml_dma implementations. * Internal data, specific to a dma engine implementation.
* Should not be used by end-users. * Should not be used by end-users.
**/ **/
struct aml_dma_data; struct aml_dma_data;
/** /**
* Type of the function used to perform the DMA between two layouts. * Function called in a request to perform the copy between two areas and two
* @param dst: destination layout * layouts.
* @param src: source layout * @param[in] dst: destination layout
* @param arg: extra argument needed by the operator * @param[in] src: source layout
* @param[in] arg: extra argument needed by the operator.
* See operator implementators for more details.
* @param[out] out: Output of the operator.
* See operator implementators for more details.
**/ **/
typedef int (*aml_dma_operator)(struct aml_layout *dst, typedef int (*aml_dma_operator)(struct aml_layout *dst,
const struct aml_layout *src, const struct aml_layout *src,
void *arg, void *arg, void **out);
void **out);
/**
/** * aml_dma_ops is a structure containing operations for a specific
aml_dma_ops is a structure containing operations for a specific * aml_dma implementation. These operations are detailed in the structure.
* aml_dma implementation. * They are specific in:
* These operation are operation are detailed in the structure. * - the type of aml_area source and destination,
* They are specific in: * - the progress engine performing the operation (thread, hardware dma, ...).
* - the type of aml_area source and destination, * Each different combination of these two points may require a different
* - the progress engine performing the operation, * set of dma operations.
* - 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_ops { struct aml_dma_ops {
/** /**
* Initiate a data movement, from a source pointer to a destination * Initiate a data movement, from a source pointer to a destination
...@@ -823,11 +851,9 @@ struct aml_dma_ops { ...@@ -823,11 +851,9 @@ struct aml_dma_ops {
}; };
/** /**
* aml_dma is an abstraction for (asynchronously) moving data * This is the high level structure containing the implementation
* from one area to another. The implementation of dma to use * specific data and methods.
* is depends on the source and destination areas. The appropriate * @see struct aml_dma.
* dma choice is delegated to the user.
* @see struct aml_area.
**/ **/
struct aml_dma { struct aml_dma {
/** @see aml_dma_ops **/ /** @see aml_dma_ops **/
...@@ -845,8 +871,10 @@ struct aml_dma { ...@@ -845,8 +871,10 @@ struct aml_dma {
* @param op_arg: optional argument to the operator * @param op_arg: optional argument to the operator
* @return 0 if successful; an error code otherwise. * @return 0 if successful; an error code otherwise.
**/ **/
int aml_dma_copy(struct aml_dma *dma, struct aml_layout *dest, int aml_dma_copy(struct aml_dma *dma,
struct aml_layout *src, aml_dma_operator op, void *op_arg); struct aml_layout *dest,
struct aml_layout *src,
aml_dma_operator op, void *op_arg);
/** /**
* Requests a data copy between two different buffers.This is an asynchronous * Requests a data copy between two different buffers.This is an asynchronous
...@@ -860,7 +888,8 @@ int aml_dma_copy(struct aml_dma *dma, struct aml_layout *dest, ...@@ -860,7 +888,8 @@ int aml_dma_copy(struct aml_dma *dma, struct aml_layout *dest,
* @param op_arg: optional argument to the operator * @param op_arg: optional argument to the operator
* @return 0 if successful; an error code otherwise. * @return 0 if successful; an error code otherwise.
**/ **/
int aml_dma_async_copy(struct aml_dma *dma, struct aml_dma_request **req, int aml_dma_async_copy(struct aml_dma *dma,
struct aml_dma_request **req,
struct aml_layout *dest, struct aml_layout *dest,
struct aml_layout *src, struct aml_layout *src,
aml_dma_operator op, void *op_arg); aml_dma_operator op, void *op_arg);
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment