aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorVinod Koul <vinod.koul@intel.com>2011-05-25 17:49:20 -0400
committerDan Williams <dan.j.williams@intel.com>2011-05-25 17:49:20 -0400
commit46b2903c05b248ed78304113ecfba368b4c55def (patch)
treefadcbea8400b014d75d5a075a505401bfcfc0b91 /Documentation
parentf2889fee8c7fe0ac9752186d43f9486392bb204d (diff)
dmaengine: Add API documentation for slave dma usage
Signed-off-by: Vinod Koul <vinod.koul@intel.com> Signed-off-by: Dan Williams <dan.j.williams@intel.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/dmaengine.txt97
1 files changed, 96 insertions, 1 deletions
diff --git a/Documentation/dmaengine.txt b/Documentation/dmaengine.txt
index 0c1c2f63c0a9..5a0cb1ef6164 100644
--- a/Documentation/dmaengine.txt
+++ b/Documentation/dmaengine.txt
@@ -1 +1,96 @@
1See Documentation/crypto/async-tx-api.txt 1 DMA Engine API Guide
2 ====================
3
4 Vinod Koul <vinod dot koul at intel.com>
5
6NOTE: For DMA Engine usage in async_tx please see:
7 Documentation/crypto/async-tx-api.txt
8
9
10Below is a guide to device driver writers on how to use the Slave-DMA API of the
11DMA Engine. This is applicable only for slave DMA usage only.
12
13The slave DMA usage consists of following steps
141. Allocate a DMA slave channel
152. Set slave and controller specific parameters
163. Get a descriptor for transaction
174. Submit the transaction and wait for callback notification
18
191. Allocate a DMA slave channel
20Channel allocation is slightly different in the slave DMA context, client
21drivers typically need a channel from a particular DMA controller only and even
22in some cases a specific channel is desired. To request a channel
23dma_request_channel() API is used.
24
25Interface:
26struct dma_chan *dma_request_channel(dma_cap_mask_t mask,
27 dma_filter_fn filter_fn,
28 void *filter_param);
29where dma_filter_fn is defined as:
30typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param);
31
32When the optional 'filter_fn' parameter is set to NULL dma_request_channel
33simply returns the first channel that satisfies the capability mask. Otherwise,
34when the mask parameter is insufficient for specifying the necessary channel,
35the filter_fn routine can be used to disposition the available channels in the
36system. The filter_fn routine is called once for each free channel in the
37system. Upon seeing a suitable channel filter_fn returns DMA_ACK which flags
38that channel to be the return value from dma_request_channel. A channel
39allocated via this interface is exclusive to the caller, until
40dma_release_channel() is called.
41
422. Set slave and controller specific parameters
43Next step is always to pass some specific information to the DMA driver. Most of
44the generic information which a slave DMA can use is in struct dma_slave_config.
45It allows the clients to specify DMA direction, DMA addresses, bus widths, DMA
46burst lengths etc. If some DMA controllers have more parameters to be sent then
47they should try to embed struct dma_slave_config in their controller specific
48structure. That gives flexibility to client to pass more parameters, if
49required.
50
51Interface:
52int dmaengine_slave_config(struct dma_chan *chan,
53 struct dma_slave_config *config)
54
553. Get a descriptor for transaction
56For slave usage the various modes of slave transfers supported by the
57DMA-engine are:
58slave_sg - DMA a list of scatter gather buffers from/to a peripheral
59dma_cyclic - Perform a cyclic DMA operation from/to a peripheral till the
60 operation is explicitly stopped.
61The non NULL return of this transfer API represents a "descriptor" for the given
62transaction.
63
64Interface:
65struct dma_async_tx_descriptor *(*chan->device->device_prep_dma_sg)(
66 struct dma_chan *chan,
67 struct scatterlist *dst_sg, unsigned int dst_nents,
68 struct scatterlist *src_sg, unsigned int src_nents,
69 unsigned long flags);
70struct dma_async_tx_descriptor *(*chan->device->device_prep_dma_cyclic)(
71 struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len,
72 size_t period_len, enum dma_data_direction direction);
73
744. Submit the transaction and wait for callback notification
75To schedule the transaction to be scheduled by dma device, the "descriptor"
76returned in above (3) needs to be submitted.
77To tell the dma driver that a transaction is ready to be serviced, the
78descriptor->submit() callback needs to be invoked. This chains the descriptor to
79the pending queue.
80The transactions in the pending queue can be activated by calling the
81issue_pending API. If channel is idle then the first transaction in queue is
82started and subsequent ones queued up.
83On completion of the DMA operation the next in queue is submitted and a tasklet
84triggered. The tasklet would then call the client driver completion callback
85routine for notification, if set.
86Interface:
87void dma_async_issue_pending(struct dma_chan *chan);
88
89==============================================================================
90
91Additional usage notes for dma driver writers
921/ Although DMA engine specifies that completion callback routines cannot submit
93any new operations, but typically for slave DMA subsequent transaction may not
94be available for submit prior to callback routine being called. This requirement
95is not a requirement for DMA-slave devices. But they should take care to drop
96the spin-lock they might be holding before calling the callback routine