[PATCH] dmaengine: Add API documentation for slave dma usage

[per.forlin@linaro.org (Per Forlin)]

Hi Vinod,

On Tue, May 24, 2011 at 2:04 PM, Koul, Vinod <vinod.koul@intel.com> wrote:
> From: Vinod Koul <vinod.koul@intel.com>
>
> Signed-off-by: Vinod Koul <vinod.koul@intel.com>
> ---
> ?Documentation/dma-slave-api.txt | ? 74 +++++++++++++++++++++++++++++++++++++++
> ?1 files changed, 74 insertions(+), 0 deletions(-)
> ?create mode 100644 Documentation/dma-slave-api.txt
I suggest putting this in subsection of dmaengine.txt instead.
dmaengine.txt would be the natural place to look at.

>
> diff --git a/Documentation/dma-slave-api.txt b/Documentation/dma-slave-api.txt
> new file mode 100644
> index 0000000..7498807
> --- /dev/null
> +++ b/Documentation/dma-slave-api.txt
> @@ -0,0 +1,74 @@
> + ? ? ? ? ? ? ? ? ? ?Slave DMA API Guide
> + ? ? ? ? ? ? ? ? ? ?===================
> +
> + ? ? ? ? ? ? ? ?Vinod Koul <vinod dot koul@intel.com>
> +
> +This is a guide to device driver writers on how to use the Slave-DMA API of the
> +DMA Engine. This is applicable only for slave DMA usage and not async tx. For
> +the async tx usage of DMA Engine please see
> +Documentation/crypto/async-tx-api.txt
> +
> +The slave DMA usage consists of following steps
> +1. Allocate a DMA slave channel
> +2. Set slave and controller specific parameters
> +3. Get a descriptor for transaction
> +4. Submit the transaction and wait for callback notification
> +
> +1. Allocate a DMA slave channel
> +Channel allocation is slightly different in the slave DMA context, client
> +drivers typically need a channel from a particular DMA controller only and even
> +in some cases a specific channel is desired. To request a channel
> +__dma_request_channel() API is used.
> +
> +Interface:
> +struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
> + ? ? ? ? ? ? ? dma_filter_fn filter_fn,
> + ? ? ? ? ? ? ? void *filter_param);
> +where dma_filter_fn is defined as:
> +typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
> +
> +When the optional 'filter_fn' parameter is set to NULL dma_request_channel
> +simply returns the first channel that satisfies the capability mask. ?Otherwise,
> +when the mask parameter is insufficient for specifying the necessary channel,
> +the filter_fn routine can be used to disposition the available channels in the
> +system. The filter_fn routine is called once for each free channel in the
> +system. ?Upon seeing a suitable channel filter_fn returns DMA_ACK which flags
> +that channel to be the return value from dma_request_channel. ?A channel
> +allocated via this interface is exclusive to the caller, until
> +dma_release_channel() is called.
> +
> +2. Set slave and controller specific parameters
> +Next step is always to pass some specific information to the DMA driver. Most of
> +the generic information which a slave DMA can use is in struct dma_slave_config.
> +It allows the clients to specify DMA direction, DMA addresses, bus widths, DMA
> +burst lengths etc. If some DMA controllers have more parameters to be sent then
> +they should try to embed struct dma_slave_config in their controller specific
> +structure. That gives flexibility to client to pass more parameters, if
> +required.
> +
> +Interface:
> +struct dma_async_tx_descriptor *(*chan->device->device_prep_dma_sg)(
> + ? ? ? ? ? ? ? struct dma_chan *chan,
> + ? ? ? ? ? ? ? struct scatterlist *dst_sg, unsigned int dst_nents,
> + ? ? ? ? ? ? ? struct scatterlist *src_sg, unsigned int src_nents,
> + ? ? ? ? ? ? ? unsigned long flags);
> +struct dma_async_tx_descriptor *(*chan->device->device_prep_dma_cyclic)(
> + ? ? ? ? ? ? ? struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
> + ? ? ? ? ? ? ? size_t period_len, enum dma_data_direction direction);
> +
> +4. Submit the transaction(s) and wait for callback notification when slave API
> +is 3 above returns, the non NULL value would imply a "descriptor" for the
> +transaction. These transaction(s) would need to be submitted which pushes them
> +into queue in DMA driver. If DMA is idle then the first descriptor submit will
> +be pushed to DMA and subsequent ones will be queued. On completion of the DMA
> +operation the next in queue is submitted and a tasklet triggered. The tasklet
> +would then call the client driver completion callback routine for notification,
> +if set.
> +
Does submit really start the transfer as well? My interpretation of
submit is that is only adds desc to a pending queue. When calling
issue_pending all these descs will be schedule for DMA transfer. Calls
to submit after this point will added to the pending queue again and
not be issued until calling issue_pending once more.

Thanks for your initiative to document the slave parts of dmaegine.
Per