| 1 | ====================
|
| 2 | DMA Engine API Guide
|
| 3 | ====================
|
| 4 |
|
| 5 | Vinod 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 |
|
| 11 | Below is a guide to device driver writers on how to use the Slave-DMA API of the
|
| 12 | DMA Engine. This is applicable only for slave DMA usage only.
|
| 13 |
|
| 14 | DMA usage
|
| 15 | =========
|
| 16 |
|
| 17 | The 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 |
|
| 29 | The details of these operations are:
|
| 30 |
|
| 31 | 1. 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 |
|
| 51 | 2. 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 |
|
| 76 | 3. 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 |
|
| 269 | 4. 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 |
|
| 293 | 5. 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 |
|
| 309 | Further APIs
|
| 310 | ------------
|
| 311 |
|
| 312 | 1. 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 |
|
| 339 | 2. 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 |
|
| 347 | 3. 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 |
|
| 356 | 4. 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 |
|
| 378 | 5. 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.
|