Commit 7d083ae9 authored by Peter Ujfalusi's avatar Peter Ujfalusi Committed by Vinod Koul

dmaengine: doc: Add sections for per descriptor metadata support

Update the provider and client documentation with details about the
metadata support.
Signed-off-by: default avatarPeter Ujfalusi <peter.ujfalusi@ti.com>
Reviewed-by: default avatarTero Kristo <t-kristo@ti.com>
Tested-by: default avatarKeerthy <j-keerthy@ti.com>
Reviewed-by: default avatarGrygorii Strashko <grygorii.strashko@ti.com>
Link: https://lore.kernel.org/r/20191223110458.30766-4-peter.ujfalusi@ti.comSigned-off-by: default avatarVinod Koul <vkoul@kernel.org>
parent 5fe4beaa
...@@ -151,6 +151,93 @@ The details of these operations are: ...@@ -151,6 +151,93 @@ The details of these operations are:
Note that callbacks will always be invoked from the DMA Note that callbacks will always be invoked from the DMA
engines tasklet, never from interrupt context. engines tasklet, never from interrupt context.
Optional: per descriptor metadata
---------------------------------
DMAengine provides two ways for metadata support.
DESC_METADATA_CLIENT
The metadata buffer is allocated/provided by the client driver and it is
attached to the descriptor.
.. code-block:: c
int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc,
void *data, size_t len);
DESC_METADATA_ENGINE
The metadata buffer is allocated/managed by the DMA driver. The client
driver can ask for the pointer, maximum size and the currently used size of
the metadata and can directly update or read it.
Becasue the DMA driver manages the memory area containing the metadata,
clients must make sure that they do not try to access or get the pointer
after their transfer completion callback has run for the descriptor.
If no completion callback has been defined for the transfer, then the
metadata must not be accessed after issue_pending.
In other words: if the aim is to read back metadata after the transfer is
completed, then the client must use completion callback.
.. code-block:: c
void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc,
size_t *payload_len, size_t *max_len);
int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc,
size_t payload_len);
Client drivers can query if a given mode is supported with:
.. code-block:: c
bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan,
enum dma_desc_metadata_mode mode);
Depending on the used mode client drivers must follow different flow.
DESC_METADATA_CLIENT
- DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
1. prepare the descriptor (dmaengine_prep_*)
construct the metadata in the client's buffer
2. use dmaengine_desc_attach_metadata() to attach the buffer to the
descriptor
3. submit the transfer
- DMA_DEV_TO_MEM:
1. prepare the descriptor (dmaengine_prep_*)
2. use dmaengine_desc_attach_metadata() to attach the buffer to the
descriptor
3. submit the transfer
4. when the transfer is completed, the metadata should be available in the
attached buffer
DESC_METADATA_ENGINE
- DMA_MEM_TO_DEV / DEV_MEM_TO_MEM:
1. prepare the descriptor (dmaengine_prep_*)
2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the
engine's metadata area
3. update the metadata at the pointer
4. use dmaengine_desc_set_metadata_len() to tell the DMA engine the
amount of data the client has placed into the metadata buffer
5. submit the transfer
- DMA_DEV_TO_MEM:
1. prepare the descriptor (dmaengine_prep_*)
2. submit the transfer
3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get
the pointer to the engine's metadata area
4. read out the metadata from the pointer
.. note::
When DESC_METADATA_ENGINE mode is used the metadata area for the descriptor
is no longer valid after the transfer has been completed (valid up to the
point when the completion callback returns if used).
Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed,
client drivers must use either of the modes per descriptor.
4. Submit the transaction 4. Submit the transaction
Once the descriptor has been prepared and the callback information Once the descriptor has been prepared and the callback information
......
...@@ -247,6 +247,54 @@ after each transfer. In case of a ring buffer, they may loop ...@@ -247,6 +247,54 @@ after each transfer. In case of a ring buffer, they may loop
(DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO) (DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO)
are typically fixed. are typically fixed.
Per descriptor metadata support
-------------------------------
Some data movement architecture (DMA controller and peripherals) uses metadata
associated with a transaction. The DMA controller role is to transfer the
payload and the metadata alongside.
The metadata itself is not used by the DMA engine itself, but it contains
parameters, keys, vectors, etc for peripheral or from the peripheral.
The DMAengine framework provides a generic ways to facilitate the metadata for
descriptors. Depending on the architecture the DMA driver can implement either
or both of the methods and it is up to the client driver to choose which one
to use.
- DESC_METADATA_CLIENT
The metadata buffer is allocated/provided by the client driver and it is
attached (via the dmaengine_desc_attach_metadata() helper to the descriptor.
From the DMA driver the following is expected for this mode:
- DMA_MEM_TO_DEV / DEV_MEM_TO_MEM
The data from the provided metadata buffer should be prepared for the DMA
controller to be sent alongside of the payload data. Either by copying to a
hardware descriptor, or highly coupled packet.
- DMA_DEV_TO_MEM
On transfer completion the DMA driver must copy the metadata to the client
provided metadata buffer before notifying the client about the completion.
After the transfer completion, DMA drivers must not touch the metadata
buffer provided by the client.
- DESC_METADATA_ENGINE
The metadata buffer is allocated/managed by the DMA driver. The client driver
can ask for the pointer, maximum size and the currently used size of the
metadata and can directly update or read it. dmaengine_desc_get_metadata_ptr()
and dmaengine_desc_set_metadata_len() is provided as helper functions.
From the DMA driver the following is expected for this mode:
- get_metadata_ptr
Should return a pointer for the metadata buffer, the maximum size of the
metadata buffer and the currently used / valid (if any) bytes in the buffer.
- set_metadata_len
It is called by the clients after it have placed the metadata to the buffer
to let the DMA driver know the number of valid bytes provided.
Note: since the client will ask for the metadata pointer in the completion
callback (in DMA_DEV_TO_MEM case) the DMA driver must ensure that the
descriptor is not freed up prior the callback is called.
Device operations Device operations
----------------- -----------------
......
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