1==================== 2DMA Engine API Guide 3==================== 4 5Vinod Koul <vinod dot koul at intel.com> 6 7.. note:: For DMA Engine usage in async_tx please see: 8 ``Documentation/crypto/async-tx-api.rst`` 9 10 11Below is a guide to device driver writers on how to use the Slave-DMA API of the 12DMA Engine. This is applicable only for slave DMA usage only. 13 14DMA usage 15========= 16 17The slave DMA usage consists of following steps: 18 19- Allocate a DMA slave channel 20 21- Set slave and controller specific parameters 22 23- Get a descriptor for transaction 24 25- Submit the transaction 26 27- Issue pending requests and wait for callback notification 28 29The details of these operations are: 30 311. Allocate a DMA slave channel 32 33 Channel allocation is slightly different in the slave DMA context, 34 client drivers typically need a channel from a particular DMA 35 controller only and even in some cases a specific channel is desired. 36 To request a channel dma_request_chan() API is used. 37 38 Interface: 39 40 .. code-block:: c 41 42 struct dma_chan *dma_request_chan(struct device *dev, const char *name); 43 44 Which will find and return the ``name`` DMA channel associated with the 'dev' 45 device. The association is done via DT, ACPI or board file based 46 dma_slave_map matching table. 47 48 A channel allocated via this interface is exclusive to the caller, 49 until dma_release_channel() is called. 50 512. Set slave and controller specific parameters 52 53 Next step is always to pass some specific information to the DMA 54 driver. Most of the generic information which a slave DMA can use 55 is in struct dma_slave_config. This allows the clients to specify 56 DMA direction, DMA addresses, bus widths, DMA burst lengths etc 57 for the peripheral. 58 59 If some DMA controllers have more parameters to be sent then they 60 should try to embed struct dma_slave_config in their controller 61 specific structure. That gives flexibility to client to pass more 62 parameters, if required. 63 64 Interface: 65 66 .. code-block:: c 67 68 int dmaengine_slave_config(struct dma_chan *chan, 69 struct dma_slave_config *config) 70 71 Please see the dma_slave_config structure definition in dmaengine.h 72 for a detailed explanation of the struct members. Please note 73 that the 'direction' member will be going away as it duplicates the 74 direction given in the prepare call. 75 763. Get a descriptor for transaction 77 78 For slave usage the various modes of slave transfers supported by the 79 DMA-engine are: 80 81 - slave_sg: DMA a list of scatter gather buffers from/to a peripheral 82 83 - config_sg: Similar with slave_sg, just pass down dma_slave_config 84 struct to avoid calling dmaengine_slave_config() every time adjusting the 85 burst length or the FIFO address is needed. 86 87 - peripheral_dma_vec: DMA an array of scatter gather buffers from/to a 88 peripheral. Similar to slave_sg, but uses an array of dma_vec 89 structures instead of a scatterlist. 90 91 - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the 92 operation is explicitly stopped. 93 94 - interleaved_dma: This is common to Slave as well as M2M clients. For slave 95 address of devices' fifo could be already known to the driver. 96 Various types of operations could be expressed by setting 97 appropriate values to the 'dma_interleaved_template' members. Cyclic 98 interleaved DMA transfers are also possible if supported by the channel by 99 setting the DMA_PREP_REPEAT transfer flag. 100 101 A non-NULL return of this transfer API represents a "descriptor" for 102 the given transaction. 103 104 Interface: 105 106 .. code-block:: c 107 108 struct dma_async_tx_descriptor *dmaengine_prep_slave_sg( 109 struct dma_chan *chan, struct scatterlist *sgl, 110 unsigned int sg_len, enum dma_data_direction direction, 111 unsigned long flags); 112 113 struct dma_async_tx_descriptor *dmaengine_prep_config_sg( 114 struct dma_chan *chan, struct scatterlist *sgl, 115 unsigned int sg_len, enum dma_transfer_direction dir, 116 unsigned long flags, struct dma_slave_config *config); 117 118 struct dma_async_tx_descriptor *dmaengine_prep_peripheral_dma_vec( 119 struct dma_chan *chan, const struct dma_vec *vecs, 120 size_t nents, enum dma_data_direction direction, 121 unsigned long flags); 122 123 struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic( 124 struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len, 125 size_t period_len, enum dma_data_direction direction); 126 127 struct dma_async_tx_descriptor *dmaengine_prep_interleaved_dma( 128 struct dma_chan *chan, struct dma_interleaved_template *xt, 129 unsigned long flags); 130 131 The peripheral driver is expected to have mapped the scatterlist for 132 the DMA operation prior to calling dmaengine_prep_slave_sg(), and must 133 keep the scatterlist mapped until the DMA operation has completed. 134 The scatterlist must be mapped using the DMA struct device. 135 If a mapping needs to be synchronized later, dma_sync_*_for_*() must be 136 called using the DMA struct device, too. 137 So, normal setup should look like this: 138 139 .. code-block:: c 140 141 struct device *dma_dev = dmaengine_get_dma_device(chan); 142 143 nr_sg = dma_map_sg(dma_dev, sgl, sg_len); 144 if (nr_sg == 0) 145 /* error */ 146 147 desc = dmaengine_prep_slave_sg(chan, sgl, nr_sg, direction, flags); 148 149 Once a descriptor has been obtained, the callback information can be 150 added and the descriptor must then be submitted. Some DMA engine 151 drivers may hold a spinlock between a successful preparation and 152 submission so it is important that these two operations are closely 153 paired. 154 155 .. note:: 156 157 Although the async_tx API specifies that completion callback 158 routines cannot submit any new operations, this is not the 159 case for slave/cyclic DMA. 160 161 For slave DMA, the subsequent transaction may not be available 162 for submission prior to callback function being invoked, so 163 slave DMA callbacks are permitted to prepare and submit a new 164 transaction. 165 166 For cyclic DMA, a callback function may wish to terminate the 167 DMA via dmaengine_terminate_async(). 168 169 Therefore, it is important that DMA engine drivers drop any 170 locks before calling the callback function which may cause a 171 deadlock. 172 173 Note that callbacks will always be invoked from the DMA 174 engines tasklet, never from interrupt context. 175 176 **Optional: per descriptor metadata** 177 178 DMAengine provides two ways for metadata support. 179 180 DESC_METADATA_CLIENT 181 182 The metadata buffer is allocated/provided by the client driver and it is 183 attached to the descriptor. 184 185 .. code-block:: c 186 187 int dmaengine_desc_attach_metadata(struct dma_async_tx_descriptor *desc, 188 void *data, size_t len); 189 190 DESC_METADATA_ENGINE 191 192 The metadata buffer is allocated/managed by the DMA driver. The client 193 driver can ask for the pointer, maximum size and the currently used size of 194 the metadata and can directly update or read it. 195 196 Because the DMA driver manages the memory area containing the metadata, 197 clients must make sure that they do not try to access or get the pointer 198 after their transfer completion callback has run for the descriptor. 199 If no completion callback has been defined for the transfer, then the 200 metadata must not be accessed after issue_pending. 201 In other words: if the aim is to read back metadata after the transfer is 202 completed, then the client must use completion callback. 203 204 .. code-block:: c 205 206 void *dmaengine_desc_get_metadata_ptr(struct dma_async_tx_descriptor *desc, 207 size_t *payload_len, size_t *max_len); 208 209 int dmaengine_desc_set_metadata_len(struct dma_async_tx_descriptor *desc, 210 size_t payload_len); 211 212 Client drivers can query if a given mode is supported with: 213 214 .. code-block:: c 215 216 bool dmaengine_is_metadata_mode_supported(struct dma_chan *chan, 217 enum dma_desc_metadata_mode mode); 218 219 Depending on the used mode client drivers must follow different flow. 220 221 DESC_METADATA_CLIENT 222 223 - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM: 224 225 1. prepare the descriptor (dmaengine_prep_*) 226 construct the metadata in the client's buffer 227 2. use dmaengine_desc_attach_metadata() to attach the buffer to the 228 descriptor 229 3. submit the transfer 230 231 - DMA_DEV_TO_MEM: 232 233 1. prepare the descriptor (dmaengine_prep_*) 234 2. use dmaengine_desc_attach_metadata() to attach the buffer to the 235 descriptor 236 3. submit the transfer 237 4. when the transfer is completed, the metadata should be available in the 238 attached buffer 239 240 DESC_METADATA_ENGINE 241 242 - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM: 243 244 1. prepare the descriptor (dmaengine_prep_*) 245 2. use dmaengine_desc_get_metadata_ptr() to get the pointer to the 246 engine's metadata area 247 3. update the metadata at the pointer 248 4. use dmaengine_desc_set_metadata_len() to tell the DMA engine the 249 amount of data the client has placed into the metadata buffer 250 5. submit the transfer 251 252 - DMA_DEV_TO_MEM: 253 254 1. prepare the descriptor (dmaengine_prep_*) 255 2. submit the transfer 256 3. on transfer completion, use dmaengine_desc_get_metadata_ptr() to get 257 the pointer to the engine's metadata area 258 4. read out the metadata from the pointer 259 260 .. note:: 261 262 When DESC_METADATA_ENGINE mode is used the metadata area for the descriptor 263 is no longer valid after the transfer has been completed (valid up to the 264 point when the completion callback returns if used). 265 266 Mixed use of DESC_METADATA_CLIENT / DESC_METADATA_ENGINE is not allowed, 267 client drivers must use either of the modes per descriptor. 268 2694. Submit the transaction 270 271 Once the descriptor has been prepared and the callback information 272 added, it must be placed on the DMA engine drivers pending queue. 273 274 Interface: 275 276 .. code-block:: c 277 278 dma_cookie_t dmaengine_submit(struct dma_async_tx_descriptor *desc) 279 280 This returns a cookie can be used to check the progress of DMA engine 281 activity via other DMA engine calls not covered in this document. 282 283 dmaengine_submit() will not start the DMA operation, it merely adds 284 it to the pending queue. For this, see step 5, dma_async_issue_pending. 285 286 .. note:: 287 288 After calling ``dmaengine_submit()`` the submitted transfer descriptor 289 (``struct dma_async_tx_descriptor``) belongs to the DMA engine. 290 Consequently, the client must consider invalid the pointer to that 291 descriptor. 292 2935. Issue pending DMA requests and wait for callback notification 294 295 The transactions in the pending queue can be activated by calling the 296 issue_pending API. If channel is idle then the first transaction in 297 queue is started and subsequent ones queued up. 298 299 On completion of each DMA operation, the next in queue is started and 300 a tasklet triggered. The tasklet will then call the client driver 301 completion callback routine for notification, if set. 302 303 Interface: 304 305 .. code-block:: c 306 307 void dma_async_issue_pending(struct dma_chan *chan); 308 309Further APIs 310------------ 311 3121. Terminate APIs 313 314 .. code-block:: c 315 316 int dmaengine_terminate_sync(struct dma_chan *chan) 317 int dmaengine_terminate_async(struct dma_chan *chan) 318 int dmaengine_terminate_all(struct dma_chan *chan) /* DEPRECATED */ 319 320 This causes all activity for the DMA channel to be stopped, and may 321 discard data in the DMA FIFO which hasn't been fully transferred. 322 No callback functions will be called for any incomplete transfers. 323 324 Two variants of this function are available. 325 326 dmaengine_terminate_async() might not wait until the DMA has been fully 327 stopped or until any running complete callbacks have finished. But it is 328 possible to call dmaengine_terminate_async() from atomic context or from 329 within a complete callback. dmaengine_synchronize() must be called before it 330 is safe to free the memory accessed by the DMA transfer or free resources 331 accessed from within the complete callback. 332 333 dmaengine_terminate_sync() will wait for the transfer and any running 334 complete callbacks to finish before it returns. But the function must not be 335 called from atomic context or from within a complete callback. 336 337 dmaengine_terminate_all() is deprecated and should not be used in new code. 338 3392. Pause API 340 341 .. code-block:: c 342 343 int dmaengine_pause(struct dma_chan *chan) 344 345 This pauses activity on the DMA channel without data loss. 346 3473. Resume API 348 349 .. code-block:: c 350 351 int dmaengine_resume(struct dma_chan *chan) 352 353 Resume a previously paused DMA channel. It is invalid to resume a 354 channel which is not currently paused. 355 3564. Check Txn complete 357 358 .. code-block:: c 359 360 enum dma_status dma_async_is_tx_complete(struct dma_chan *chan, 361 dma_cookie_t cookie, dma_cookie_t *last, dma_cookie_t *used) 362 363 This can be used to check the status of the channel. Please see 364 the documentation in include/linux/dmaengine.h for a more complete 365 description of this API. 366 367 This can be used in conjunction with dma_async_is_complete() and 368 the cookie returned from dmaengine_submit() to check for 369 completion of a specific DMA transaction. 370 371 .. note:: 372 373 Not all DMA engine drivers can return reliable information for 374 a running DMA channel. It is recommended that DMA engine users 375 pause or stop (via dmaengine_terminate_all()) the channel before 376 using this API. 377 3785. Synchronize termination API 379 380 .. code-block:: c 381 382 void dmaengine_synchronize(struct dma_chan *chan) 383 384 Synchronize the termination of the DMA channel to the current context. 385 386 This function should be used after dmaengine_terminate_async() to synchronize 387 the termination of the DMA channel to the current context. The function will 388 wait for the transfer and any running complete callbacks to finish before it 389 returns. 390 391 If dmaengine_terminate_async() is used to stop the DMA channel this function 392 must be called before it is safe to free memory accessed by previously 393 submitted descriptors or to free any resources accessed within the complete 394 callback of previously submitted descriptors. 395 396 The behavior of this function is undefined if dma_async_issue_pending() has 397 been called between dmaengine_terminate_async() and this function. 398