[lkml]   [2011]   [May]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
    SubjectRe: [PATCH] dmaengine: Add API documentation for slave dma usage
    Hi Vinod,

    On Tue, May 24, 2011 at 2:04 PM, Koul, Vinod <> wrote:
    > From: Vinod Koul <>
    > Signed-off-by: Vinod Koul <>
    > ---
    >  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 at>
    > +
    > +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.
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to
    More majordomo info at
    Please read the FAQ at

     \ /
      Last update: 2011-05-24 17:43    [W:0.029 / U:87.608 seconds]
    ©2003-2017 Jasper Spaans. hosted at Digital OceanAdvertise on this site