Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.
1 DMA Engine API Guide 2 ==================== 3 4 Vinod Koul <vinod dot koul at intel.com> 5 6 NOTE: For DMA Engine usage in async_tx please see: 7 Documentation/crypto/async-tx-api.txt 8 9 10 Below is a guide to device driver writers on how to use the Slave-DMA API of the 11 DMA Engine. This is applicable only for slave DMA usage only. 12 13 The slave DMA usage consists of following steps: 14 1. Allocate a DMA slave channel 15 2. Set slave and controller specific parameters 16 3. Get a descriptor for transaction 17 4. Submit the transaction 18 5. Issue pending requests and wait for callback notification 19 20 1. Allocate a DMA slave channel 21 22 Channel allocation is slightly different in the slave DMA context, 23 client drivers typically need a channel from a particular DMA 24 controller only and even in some cases a specific channel is desired. 25 To request a channel dma_request_chan() API is used. 26 27 Interface: 28 struct dma_chan *dma_request_chan(struct device *dev, const char *name); 29 30 Which will find and return the 'name' DMA channel associated with the 'dev' 31 device. The association is done via DT, ACPI or board file based 32 dma_slave_map matching table. 33 34 A channel allocated via this interface is exclusive to the caller, 35 until dma_release_channel() is called. 36 37 2. Set slave and controller specific parameters 38 39 Next step is always to pass some specific information to the DMA 40 driver. Most of the generic information which a slave DMA can use 41 is in struct dma_slave_config. This allows the clients to specify 42 DMA direction, DMA addresses, bus widths, DMA burst lengths etc 43 for the peripheral. 44 45 If some DMA controllers have more parameters to be sent then they 46 should try to embed struct dma_slave_config in their controller 47 specific structure. That gives flexibility to client to pass more 48 parameters, if required. 49 50 Interface: 51 int dmaengine_slave_config(struct dma_chan *chan, 52 struct dma_slave_config *config) 53 54 Please see the dma_slave_config structure definition in dmaengine.h 55 for a detailed explanation of the struct members. Please note 56 that the 'direction' member will be going away as it duplicates the 57 direction given in the prepare call. 58 59 3. Get a descriptor for transaction 60 61 For slave usage the various modes of slave transfers supported by the 62 DMA-engine are: 63 64 slave_sg - DMA a list of scatter gather buffers from/to a peripheral 65 dma_cyclic - Perform a cyclic DMA operation from/to a peripheral till the 66 operation is explicitly stopped. 67 interleaved_dma - This is common to Slave as well as M2M clients. For slave 68 address of devices' fifo could be already known to the driver. 69 Various types of operations could be expressed by setting 70 appropriate values to the 'dma_interleaved_template' members. 71 72 A non-NULL return of this transfer API represents a "descriptor" for 73 the given transaction. 74 75 Interface: 76 struct dma_async_tx_descriptor *dmaengine_prep_slave_sg( 77 struct dma_chan *chan, struct scatterlist *sgl, 78 unsigned int sg_len, enum dma_data_direction direction, 79 unsigned long flags); 80 81 struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic( 82 struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len, 83 size_t period_len, enum dma_data_direction direction); 84 85 struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma( 86 struct dma_chan *chan, struct dma_interleaved_template *xt, 87 unsigned long flags); 88 89 The peripheral driver is expected to have mapped the scatterlist for 90 the DMA operation prior to calling dmaengine_prep_slave_sg(), and must 91 keep the scatterlist mapped until the DMA operation has completed. 92 The scatterlist must be mapped using the DMA struct device. 93 If a mapping needs to be synchronized later, dma_sync_*_for_*() must be 94 called using the DMA struct device, too. 95 So, normal setup should look like this: 96 97 nr_sg = dma_map_sg(chan->device->dev, sgl, sg_len); 98 if (nr_sg == 0) 99 /* error */ 100 101 desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags); 102 103 Once a descriptor has been obtained, the callback information can be 104 added and the descriptor must then be submitted. Some DMA engine 105 drivers may hold a spinlock between a successful preparation and 106 submission so it is important that these two operations are closely 107 paired. 108 109 Note: 110 Although the async_tx API specifies that completion callback 111 routines cannot submit any new operations, this is not the 112 case for slave/cyclic DMA. 113 114 For slave DMA, the subsequent transaction may not be available 115 for submission prior to callback function being invoked, so 116 slave DMA callbacks are permitted to prepare and submit a new 117 transaction. 118 119 For cyclic DMA, a callback function may wish to terminate the 120 DMA via dmaengine_terminate_async(). 121 122 Therefore, it is important that DMA engine drivers drop any 123 locks before calling the callback function which may cause a 124 deadlock. 125 126 Note that callbacks will always be invoked from the DMA 127 engines tasklet, never from interrupt context. 128 129 4. Submit the transaction 130 131 Once the descriptor has been prepared and the callback information 132 added, it must be placed on the DMA engine drivers pending queue. 133 134 Interface: 135 dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc) 136 137 This returns a cookie can be used to check the progress of DMA engine 138 activity via other DMA engine calls not covered in this document. 139 140 dmaengine_submit() will not start the DMA operation, it merely adds 141 it to the pending queue. For this, see step 5, dma_async_issue_pending. 142 143 5. Issue pending DMA requests and wait for callback notification 144 145 The transactions in the pending queue can be activated by calling the 146 issue_pending API. If channel is idle then the first transaction in 147 queue is started and subsequent ones queued up. 148 149 On completion of each DMA operation, the next in queue is started and 150 a tasklet triggered. The tasklet will then call the client driver 151 completion callback routine for notification, if set. 152 153 Interface: 154 void dma_async_issue_pending(struct dma_chan *chan); 155 156 Further APIs: 157 158 1. int dmaengine_terminate_sync(struct dma_chan *chan) 159 int dmaengine_terminate_async(struct dma_chan *chan) 160 int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */ 161 162 This causes all activity for the DMA channel to be stopped, and may 163 discard data in the DMA FIFO which hasn't been fully transferred. 164 No callback functions will be called for any incomplete transfers. 165 166 Two variants of this function are available. 167 168 dmaengine_terminate_async() might not wait until the DMA has been fully 169 stopped or until any running complete callbacks have finished. But it is 170 possible to call dmaengine_terminate_async() from atomic context or from 171 within a complete callback. dmaengine_synchronize() must be called before it 172 is safe to free the memory accessed by the DMA transfer or free resources 173 accessed from within the complete callback. 174 175 dmaengine_terminate_sync() will wait for the transfer and any running 176 complete callbacks to finish before it returns. But the function must not be 177 called from atomic context or from within a complete callback. 178 179 dmaengine_terminate_all() is deprecated and should not be used in new code. 180 181 2. int dmaengine_pause(struct dma_chan *chan) 182 183 This pauses activity on the DMA channel without data loss. 184 185 3. int dmaengine_resume(struct dma_chan *chan) 186 187 Resume a previously paused DMA channel. It is invalid to resume a 188 channel which is not currently paused. 189 190 4. enum dma_status dma_async_is_tx_complete(struct dma_chan *chan, 191 dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used) 192 193 This can be used to check the status of the channel. Please see 194 the documentation in include/linux/dmaengine.h for a more complete 195 description of this API. 196 197 This can be used in conjunction with dma_async_is_complete() and 198 the cookie returned from dmaengine_submit() to check for 199 completion of a specific DMA transaction. 200 201 Note: 202 Not all DMA engine drivers can return reliable information for 203 a running DMA channel. It is recommended that DMA engine users 204 pause or stop (via dmaengine_terminate_all()) the channel before 205 using this API. 206 207 5. void dmaengine_synchronize(struct dma_chan *chan) 208 209 Synchronize the termination of the DMA channel to the current context. 210 211 This function should be used after dmaengine_terminate_async() to synchronize 212 the termination of the DMA channel to the current context. The function will 213 wait for the transfer and any running complete callbacks to finish before it 214 returns. 215 216 If dmaengine_terminate_async() is used to stop the DMA channel this function 217 must be called before it is safe to free memory accessed by previously 218 submitted descriptors or to free any resources accessed within the complete 219 callback of previously submitted descriptors. 220 221 The behavior of this function is undefined if dma_async_issue_pending() has 222 been called between dmaengine_terminate_async() and this function.