| 1 | ==================================
|
| 2 | DMAengine controller documentation
|
| 3 | ==================================
|
| 4 |
|
| 5 | Hardware Introduction
|
| 6 | =====================
|
| 7 |
|
| 8 | Most of the Slave DMA controllers have the same general principles of
|
| 9 | operations.
|
| 10 |
|
| 11 | They have a given number of channels to use for the DMA transfers, and
|
| 12 | a given number of requests lines.
|
| 13 |
|
| 14 | Requests and channels are pretty much orthogonal. Channels can be used
|
| 15 | to serve several to any requests. To simplify, channels are the
|
| 16 | entities that will be doing the copy, and requests what endpoints are
|
| 17 | involved.
|
| 18 |
|
| 19 | The request lines actually correspond to physical lines going from the
|
| 20 | DMA-eligible devices to the controller itself. Whenever the device
|
| 21 | will want to start a transfer, it will assert a DMA request (DRQ) by
|
| 22 | asserting that request line.
|
| 23 |
|
| 24 | A very simple DMA controller would only take into account a single
|
| 25 | parameter: the transfer size. At each clock cycle, it would transfer a
|
| 26 | byte of data from one buffer to another, until the transfer size has
|
| 27 | been reached.
|
| 28 |
|
| 29 | That wouldn't work well in the real world, since slave devices might
|
| 30 | require a specific number of bits to be transferred in a single
|
| 31 | cycle. For example, we may want to transfer as much data as the
|
| 32 | physical bus allows to maximize performances when doing a simple
|
| 33 | memory copy operation, but our audio device could have a narrower FIFO
|
| 34 | that requires data to be written exactly 16 or 24 bits at a time. This
|
| 35 | is why most if not all of the DMA controllers can adjust this, using a
|
| 36 | parameter called the transfer width.
|
| 37 |
|
| 38 | Moreover, some DMA controllers, whenever the RAM is used as a source
|
| 39 | or destination, can group the reads or writes in memory into a buffer,
|
| 40 | so instead of having a lot of small memory accesses, which is not
|
| 41 | really efficient, you'll get several bigger transfers. This is done
|
| 42 | using a parameter called the burst size, that defines how many single
|
| 43 | reads/writes it's allowed to do without the controller splitting the
|
| 44 | transfer into smaller sub-transfers.
|
| 45 |
|
| 46 | Our theoretical DMA controller would then only be able to do transfers
|
| 47 | that involve a single contiguous block of data. However, some of the
|
| 48 | transfers we usually have are not, and want to copy data from
|
| 49 | non-contiguous buffers to a contiguous buffer, which is called
|
| 50 | scatter-gather.
|
| 51 |
|
| 52 | DMAEngine, at least for mem2dev transfers, require support for
|
| 53 | scatter-gather. So we're left with two cases here: either we have a
|
| 54 | quite simple DMA controller that doesn't support it, and we'll have to
|
| 55 | implement it in software, or we have a more advanced DMA controller,
|
| 56 | that implements in hardware scatter-gather.
|
| 57 |
|
| 58 | The latter are usually programmed using a collection of chunks to
|
| 59 | transfer, and whenever the transfer is started, the controller will go
|
| 60 | over that collection, doing whatever we programmed there.
|
| 61 |
|
| 62 | This collection is usually either a table or a linked list. You will
|
| 63 | then push either the address of the table and its number of elements,
|
| 64 | or the first item of the list to one channel of the DMA controller,
|
| 65 | and whenever a DRQ will be asserted, it will go through the collection
|
| 66 | to know where to fetch the data from.
|
| 67 |
|
| 68 | Either way, the format of this collection is completely dependent on
|
| 69 | your hardware. Each DMA controller will require a different structure,
|
| 70 | but all of them will require, for every chunk, at least the source and
|
| 71 | destination addresses, whether it should increment these addresses or
|
| 72 | not and the three parameters we saw earlier: the burst size, the
|
| 73 | transfer width and the transfer size.
|
| 74 |
|
| 75 | The one last thing is that usually, slave devices won't issue DRQ by
|
| 76 | default, and you have to enable this in your slave device driver first
|
| 77 | whenever you're willing to use DMA.
|
| 78 |
|
| 79 | These were just the general memory-to-memory (also called mem2mem) or
|
| 80 | memory-to-device (mem2dev) kind of transfers. Most devices often
|
| 81 | support other kind of transfers or memory operations that dmaengine
|
| 82 | support and will be detailed later in this document.
|
| 83 |
|
| 84 | DMA Support in Linux
|
| 85 | ====================
|
| 86 |
|
| 87 | Historically, DMA controller drivers have been implemented using the
|
| 88 | async TX API, to offload operations such as memory copy, XOR,
|
| 89 | cryptography, etc., basically any memory to memory operation.
|
| 90 |
|
| 91 | Over time, the need for memory to device transfers arose, and
|
| 92 | dmaengine was extended. Nowadays, the async TX API is written as a
|
| 93 | layer on top of dmaengine, and acts as a client. Still, dmaengine
|
| 94 | accommodates that API in some cases, and made some design choices to
|
| 95 | ensure that it stayed compatible.
|
| 96 |
|
| 97 | For more information on the Async TX API, please look the relevant
|
| 98 | documentation file in Documentation/crypto/async-tx-api.rst.
|
| 99 |
|
| 100 | DMAEngine APIs
|
| 101 | ==============
|
| 102 |
|
| 103 | ``struct dma_device`` Initialization
|
| 104 | ------------------------------------
|
| 105 |
|
| 106 | Just like any other kernel framework, the whole DMAEngine registration
|
| 107 | relies on the driver filling a structure and registering against the
|
| 108 | framework. In our case, that structure is dma_device.
|
| 109 |
|
| 110 | The first thing you need to do in your driver is to allocate this
|
| 111 | structure. Any of the usual memory allocators will do, but you'll also
|
| 112 | need to initialize a few fields in there:
|
| 113 |
|
| 114 | - ``channels``: should be initialized as a list using the
|
| 115 | INIT_LIST_HEAD macro for example
|
| 116 |
|
| 117 | - ``src_addr_widths``:
|
| 118 | should contain a bitmask of the supported source transfer width
|
| 119 |
|
| 120 | - ``dst_addr_widths``:
|
| 121 | should contain a bitmask of the supported destination transfer width
|
| 122 |
|
| 123 | - ``directions``:
|
| 124 | should contain a bitmask of the supported slave directions
|
| 125 | (i.e. excluding mem2mem transfers)
|
| 126 |
|
| 127 | - ``residue_granularity``:
|
| 128 | granularity of the transfer residue reported to dma_set_residue.
|
| 129 | This can be either:
|
| 130 |
|
| 131 | - Descriptor:
|
| 132 | your device doesn't support any kind of residue
|
| 133 | reporting. The framework will only know that a particular
|
| 134 | transaction descriptor is done.
|
| 135 |
|
| 136 | - Segment:
|
| 137 | your device is able to report which chunks have been transferred
|
| 138 |
|
| 139 | - Burst:
|
| 140 | your device is able to report which burst have been transferred
|
| 141 |
|
| 142 | - ``dev``: should hold the pointer to the ``struct device`` associated
|
| 143 | to your current driver instance.
|
| 144 |
|
| 145 | Supported transaction types
|
| 146 | ---------------------------
|
| 147 |
|
| 148 | The next thing you need is to set which transaction types your device
|
| 149 | (and driver) supports.
|
| 150 |
|
| 151 | Our ``dma_device structure`` has a field called cap_mask that holds the
|
| 152 | various types of transaction supported, and you need to modify this
|
| 153 | mask using the dma_cap_set function, with various flags depending on
|
| 154 | transaction types you support as an argument.
|
| 155 |
|
| 156 | All those capabilities are defined in the ``dma_transaction_type enum``,
|
| 157 | in ``include/linux/dmaengine.h``
|
| 158 |
|
| 159 | Currently, the types available are:
|
| 160 |
|
| 161 | - DMA_MEMCPY
|
| 162 |
|
| 163 | - The device is able to do memory to memory copies
|
| 164 |
|
| 165 | - No matter what the overall size of the combined chunks for source and
|
| 166 | destination is, only as many bytes as the smallest of the two will be
|
| 167 | transmitted. That means the number and size of the scatter-gather buffers in
|
| 168 | both lists need not be the same, and that the operation functionally is
|
| 169 | equivalent to a ``strncpy`` where the ``count`` argument equals the smallest
|
| 170 | total size of the two scatter-gather list buffers.
|
| 171 |
|
| 172 | - It's usually used for copying pixel data between host memory and
|
| 173 | memory-mapped GPU device memory, such as found on modern PCI video graphics
|
| 174 | cards. The most immediate example is the OpenGL API function
|
| 175 | ``glReadPixels()``, which might require a verbatim copy of a huge
|
| 176 | framebuffer from local device memory onto host memory.
|
| 177 |
|
| 178 | - DMA_XOR
|
| 179 |
|
| 180 | - The device is able to perform XOR operations on memory areas
|
| 181 |
|
| 182 | - Used to accelerate XOR intensive tasks, such as RAID5
|
| 183 |
|
| 184 | - DMA_XOR_VAL
|
| 185 |
|
| 186 | - The device is able to perform parity check using the XOR
|
| 187 | algorithm against a memory buffer.
|
| 188 |
|
| 189 | - DMA_PQ
|
| 190 |
|
| 191 | - The device is able to perform RAID6 P+Q computations, P being a
|
| 192 | simple XOR, and Q being a Reed-Solomon algorithm.
|
| 193 |
|
| 194 | - DMA_PQ_VAL
|
| 195 |
|
| 196 | - The device is able to perform parity check using RAID6 P+Q
|
| 197 | algorithm against a memory buffer.
|
| 198 |
|
| 199 | - DMA_MEMSET
|
| 200 |
|
| 201 | - The device is able to fill memory with the provided pattern
|
| 202 |
|
| 203 | - The pattern is treated as a single byte signed value.
|
| 204 |
|
| 205 | - DMA_INTERRUPT
|
| 206 |
|
| 207 | - The device is able to trigger a dummy transfer that will
|
| 208 | generate periodic interrupts
|
| 209 |
|
| 210 | - Used by the client drivers to register a callback that will be
|
| 211 | called on a regular basis through the DMA controller interrupt
|
| 212 |
|
| 213 | - DMA_PRIVATE
|
| 214 |
|
| 215 | - The devices only supports slave transfers, and as such isn't
|
| 216 | available for async transfers.
|
| 217 |
|
| 218 | - DMA_ASYNC_TX
|
| 219 |
|
| 220 | - The device supports asynchronous memory-to-memory operations,
|
| 221 | including memcpy, memset, xor, pq, xor_val, and pq_val.
|
| 222 |
|
| 223 | - This capability is automatically set by the DMA engine
|
| 224 | framework and must not be configured manually by device
|
| 225 | drivers.
|
| 226 |
|
| 227 | - DMA_SLAVE
|
| 228 |
|
| 229 | - The device can handle device to memory transfers, including
|
| 230 | scatter-gather transfers.
|
| 231 |
|
| 232 | - While in the mem2mem case we were having two distinct types to
|
| 233 | deal with a single chunk to copy or a collection of them, here,
|
| 234 | we just have a single transaction type that is supposed to
|
| 235 | handle both.
|
| 236 |
|
| 237 | - If you want to transfer a single contiguous memory buffer,
|
| 238 | simply build a scatter list with only one item.
|
| 239 |
|
| 240 | - DMA_CYCLIC
|
| 241 |
|
| 242 | - The device can handle cyclic transfers.
|
| 243 |
|
| 244 | - A cyclic transfer is a transfer where the chunk collection will
|
| 245 | loop over itself, with the last item pointing to the first.
|
| 246 |
|
| 247 | - It's usually used for audio transfers, where you want to operate
|
| 248 | on a single ring buffer that you will fill with your audio data.
|
| 249 |
|
| 250 | - DMA_INTERLEAVE
|
| 251 |
|
| 252 | - The device supports interleaved transfer.
|
| 253 |
|
| 254 | - These transfers can transfer data from a non-contiguous buffer
|
| 255 | to a non-contiguous buffer, opposed to DMA_SLAVE that can
|
| 256 | transfer data from a non-contiguous data set to a continuous
|
| 257 | destination buffer.
|
| 258 |
|
| 259 | - It's usually used for 2d content transfers, in which case you
|
| 260 | want to transfer a portion of uncompressed data directly to the
|
| 261 | display to print it
|
| 262 |
|
| 263 | - DMA_COMPLETION_NO_ORDER
|
| 264 |
|
| 265 | - The device does not support in order completion.
|
| 266 |
|
| 267 | - The driver should return DMA_OUT_OF_ORDER for device_tx_status if
|
| 268 | the device is setting this capability.
|
| 269 |
|
| 270 | - All cookie tracking and checking API should be treated as invalid if
|
| 271 | the device exports this capability.
|
| 272 |
|
| 273 | - At this point, this is incompatible with polling option for dmatest.
|
| 274 |
|
| 275 | - If this cap is set, the user is recommended to provide an unique
|
| 276 | identifier for each descriptor sent to the DMA device in order to
|
| 277 | properly track the completion.
|
| 278 |
|
| 279 | - DMA_REPEAT
|
| 280 |
|
| 281 | - The device supports repeated transfers. A repeated transfer, indicated by
|
| 282 | the DMA_PREP_REPEAT transfer flag, is similar to a cyclic transfer in that
|
| 283 | it gets automatically repeated when it ends, but can additionally be
|
| 284 | replaced by the client.
|
| 285 |
|
| 286 | - This feature is limited to interleaved transfers, this flag should thus not
|
| 287 | be set if the DMA_INTERLEAVE flag isn't set. This limitation is based on
|
| 288 | the current needs of DMA clients, support for additional transfer types
|
| 289 | should be added in the future if and when the need arises.
|
| 290 |
|
| 291 | - DMA_LOAD_EOT
|
| 292 |
|
| 293 | - The device supports replacing repeated transfers at end of transfer (EOT)
|
| 294 | by queuing a new transfer with the DMA_PREP_LOAD_EOT flag set.
|
| 295 |
|
| 296 | - Support for replacing a currently running transfer at another point (such
|
| 297 | as end of burst instead of end of transfer) will be added in the future
|
| 298 | based on DMA clients needs, if and when the need arises.
|
| 299 |
|
| 300 | These various types will also affect how the source and destination
|
| 301 | addresses change over time.
|
| 302 |
|
| 303 | Addresses pointing to RAM are typically incremented (or decremented)
|
| 304 | after each transfer. In case of a ring buffer, they may loop
|
| 305 | (DMA_CYCLIC). Addresses pointing to a device's register (e.g. a FIFO)
|
| 306 | are typically fixed.
|
| 307 |
|
| 308 | Per descriptor metadata support
|
| 309 | -------------------------------
|
| 310 | Some data movement architecture (DMA controller and peripherals) uses metadata
|
| 311 | associated with a transaction. The DMA controller role is to transfer the
|
| 312 | payload and the metadata alongside.
|
| 313 | The metadata itself is not used by the DMA engine itself, but it contains
|
| 314 | parameters, keys, vectors, etc for peripheral or from the peripheral.
|
| 315 |
|
| 316 | The DMAengine framework provides a generic ways to facilitate the metadata for
|
| 317 | descriptors. Depending on the architecture the DMA driver can implement either
|
| 318 | or both of the methods and it is up to the client driver to choose which one
|
| 319 | to use.
|
| 320 |
|
| 321 | - DESC_METADATA_CLIENT
|
| 322 |
|
| 323 | The metadata buffer is allocated/provided by the client driver and it is
|
| 324 | attached (via the dmaengine_desc_attach_metadata() helper to the descriptor.
|
| 325 |
|
| 326 | From the DMA driver the following is expected for this mode:
|
| 327 |
|
| 328 | - DMA_MEM_TO_DEV / DEV_MEM_TO_MEM
|
| 329 |
|
| 330 | The data from the provided metadata buffer should be prepared for the DMA
|
| 331 | controller to be sent alongside of the payload data. Either by copying to a
|
| 332 | hardware descriptor, or highly coupled packet.
|
| 333 |
|
| 334 | - DMA_DEV_TO_MEM
|
| 335 |
|
| 336 | On transfer completion the DMA driver must copy the metadata to the client
|
| 337 | provided metadata buffer before notifying the client about the completion.
|
| 338 | After the transfer completion, DMA drivers must not touch the metadata
|
| 339 | buffer provided by the client.
|
| 340 |
|
| 341 | - DESC_METADATA_ENGINE
|
| 342 |
|
| 343 | The metadata buffer is allocated/managed by the DMA driver. The client driver
|
| 344 | can ask for the pointer, maximum size and the currently used size of the
|
| 345 | metadata and can directly update or read it. dmaengine_desc_get_metadata_ptr()
|
| 346 | and dmaengine_desc_set_metadata_len() is provided as helper functions.
|
| 347 |
|
| 348 | From the DMA driver the following is expected for this mode:
|
| 349 |
|
| 350 | - get_metadata_ptr()
|
| 351 |
|
| 352 | Should return a pointer for the metadata buffer, the maximum size of the
|
| 353 | metadata buffer and the currently used / valid (if any) bytes in the buffer.
|
| 354 |
|
| 355 | - set_metadata_len()
|
| 356 |
|
| 357 | It is called by the clients after it have placed the metadata to the buffer
|
| 358 | to let the DMA driver know the number of valid bytes provided.
|
| 359 |
|
| 360 | Note: since the client will ask for the metadata pointer in the completion
|
| 361 | callback (in DMA_DEV_TO_MEM case) the DMA driver must ensure that the
|
| 362 | descriptor is not freed up prior the callback is called.
|
| 363 |
|
| 364 | Device operations
|
| 365 | -----------------
|
| 366 |
|
| 367 | Our dma_device structure also requires a few function pointers in
|
| 368 | order to implement the actual logic, now that we described what
|
| 369 | operations we were able to perform.
|
| 370 |
|
| 371 | The functions that we have to fill in there, and hence have to
|
| 372 | implement, obviously depend on the transaction types you reported as
|
| 373 | supported.
|
| 374 |
|
| 375 | - ``device_alloc_chan_resources``
|
| 376 |
|
| 377 | - ``device_free_chan_resources``
|
| 378 |
|
| 379 | - These functions will be called whenever a driver will call
|
| 380 | ``dma_request_channel`` or ``dma_release_channel`` for the first/last
|
| 381 | time on the channel associated to that driver.
|
| 382 |
|
| 383 | - They are in charge of allocating/freeing all the needed
|
| 384 | resources in order for that channel to be useful for your driver.
|
| 385 |
|
| 386 | - These functions can sleep.
|
| 387 |
|
| 388 | - ``device_prep_dma_*``
|
| 389 |
|
| 390 | - These functions are matching the capabilities you registered
|
| 391 | previously.
|
| 392 |
|
| 393 | - These functions all take the buffer or the scatterlist relevant
|
| 394 | for the transfer being prepared, and should create a hardware
|
| 395 | descriptor or a list of hardware descriptors from it
|
| 396 |
|
| 397 | - These functions can be called from an interrupt context
|
| 398 |
|
| 399 | - Any allocation you might do should be using the GFP_NOWAIT
|
| 400 | flag, in order not to potentially sleep, but without depleting
|
| 401 | the emergency pool either.
|
| 402 |
|
| 403 | - Drivers should try to pre-allocate any memory they might need
|
| 404 | during the transfer setup at probe time to avoid putting to
|
| 405 | much pressure on the nowait allocator.
|
| 406 |
|
| 407 | - It should return a unique instance of the
|
| 408 | ``dma_async_tx_descriptor structure``, that further represents this
|
| 409 | particular transfer.
|
| 410 |
|
| 411 | - This structure can be initialized using the function
|
| 412 | ``dma_async_tx_descriptor_init``.
|
| 413 |
|
| 414 | - You'll also need to set following fields in this structure:
|
| 415 |
|
| 416 | - flags:
|
| 417 | TODO: Can it be modified by the driver itself, or
|
| 418 | should it be always the flags passed in the arguments
|
| 419 |
|
| 420 | - tx_submit: A pointer to a function you have to implement,
|
| 421 | that is supposed to push the current transaction descriptor to a
|
| 422 | pending queue, waiting for issue_pending to be called.
|
| 423 |
|
| 424 | - phys: Physical address of the descriptor which is used later by
|
| 425 | the dma engine to read the descriptor and initiate transfer.
|
| 426 |
|
| 427 | - In this structure the function pointer callback_result can be
|
| 428 | initialized in order for the submitter to be notified that a
|
| 429 | transaction has completed. In the earlier code the function pointer
|
| 430 | callback has been used. However it does not provide any status to the
|
| 431 | transaction and will be deprecated. The result structure defined as
|
| 432 | ``dmaengine_result`` that is passed in to callback_result
|
| 433 | has two fields:
|
| 434 |
|
| 435 | - result: This provides the transfer result defined by
|
| 436 | ``dmaengine_tx_result``. Either success or some error condition.
|
| 437 |
|
| 438 | - residue: Provides the residue bytes of the transfer for those that
|
| 439 | support residue.
|
| 440 |
|
| 441 | - ``device_prep_peripheral_dma_vec``
|
| 442 |
|
| 443 | - Similar to ``device_prep_slave_sg``, but it takes a pointer to a
|
| 444 | array of ``dma_vec`` structures, which (in the long run) will replace
|
| 445 | scatterlists.
|
| 446 |
|
| 447 | - ``device_issue_pending``
|
| 448 |
|
| 449 | - Takes the first transaction descriptor in the pending queue,
|
| 450 | and starts the transfer. Whenever that transfer is done, it
|
| 451 | should move to the next transaction in the list.
|
| 452 |
|
| 453 | - This function can be called in an interrupt context
|
| 454 |
|
| 455 | - ``device_tx_status``
|
| 456 |
|
| 457 | - Should report the bytes left to go over on the given channel
|
| 458 |
|
| 459 | - Should only care about the transaction descriptor passed as
|
| 460 | argument, not the currently active one on a given channel
|
| 461 |
|
| 462 | - The tx_state argument might be NULL
|
| 463 |
|
| 464 | - Should use dma_set_residue to report it
|
| 465 |
|
| 466 | - In the case of a cyclic transfer, it should only take into
|
| 467 | account the total size of the cyclic buffer.
|
| 468 |
|
| 469 | - Should return DMA_OUT_OF_ORDER if the device does not support in order
|
| 470 | completion and is completing the operation out of order.
|
| 471 |
|
| 472 | - This function can be called in an interrupt context.
|
| 473 |
|
| 474 | - device_config
|
| 475 |
|
| 476 | - Reconfigures the channel with the configuration given as argument
|
| 477 |
|
| 478 | - This command should NOT perform synchronously, or on any
|
| 479 | currently queued transfers, but only on subsequent ones
|
| 480 |
|
| 481 | - In this case, the function will receive a ``dma_slave_config``
|
| 482 | structure pointer as an argument, that will detail which
|
| 483 | configuration to use.
|
| 484 |
|
| 485 | - Even though that structure contains a direction field, this
|
| 486 | field is deprecated in favor of the direction argument given to
|
| 487 | the prep_* functions
|
| 488 |
|
| 489 | - This call is mandatory for slave operations only. This should NOT be
|
| 490 | set or expected to be set for memcpy operations.
|
| 491 | If a driver support both, it should use this call for slave
|
| 492 | operations only and not for memcpy ones.
|
| 493 |
|
| 494 | - device_pause
|
| 495 |
|
| 496 | - Pauses a transfer on the channel
|
| 497 |
|
| 498 | - This command should operate synchronously on the channel,
|
| 499 | pausing right away the work of the given channel
|
| 500 |
|
| 501 | - device_resume
|
| 502 |
|
| 503 | - Resumes a transfer on the channel
|
| 504 |
|
| 505 | - This command should operate synchronously on the channel,
|
| 506 | resuming right away the work of the given channel
|
| 507 |
|
| 508 | - device_terminate_all
|
| 509 |
|
| 510 | - Aborts all the pending and ongoing transfers on the channel
|
| 511 |
|
| 512 | - For aborted transfers the complete callback should not be called
|
| 513 |
|
| 514 | - Can be called from atomic context or from within a complete
|
| 515 | callback of a descriptor. Must not sleep. Drivers must be able
|
| 516 | to handle this correctly.
|
| 517 |
|
| 518 | - Termination may be asynchronous. The driver does not have to
|
| 519 | wait until the currently active transfer has completely stopped.
|
| 520 | See device_synchronize.
|
| 521 |
|
| 522 | - device_synchronize
|
| 523 |
|
| 524 | - Must synchronize the termination of a channel to the current
|
| 525 | context.
|
| 526 |
|
| 527 | - Must make sure that memory for previously submitted
|
| 528 | descriptors is no longer accessed by the DMA controller.
|
| 529 |
|
| 530 | - Must make sure that all complete callbacks for previously
|
| 531 | submitted descriptors have finished running and none are
|
| 532 | scheduled to run.
|
| 533 |
|
| 534 | - May sleep.
|
| 535 |
|
| 536 |
|
| 537 | Misc notes
|
| 538 | ==========
|
| 539 |
|
| 540 | (stuff that should be documented, but don't really know
|
| 541 | where to put them)
|
| 542 |
|
| 543 | ``dma_run_dependencies``
|
| 544 |
|
| 545 | - Should be called at the end of an async TX transfer, and can be
|
| 546 | ignored in the slave transfers case.
|
| 547 |
|
| 548 | - Makes sure that dependent operations are run before marking it
|
| 549 | as complete.
|
| 550 |
|
| 551 | dma_cookie_t
|
| 552 |
|
| 553 | - it's a DMA transaction ID that will increment over time.
|
| 554 |
|
| 555 | - Not really relevant any more since the introduction of ``virt-dma``
|
| 556 | that abstracts it away.
|
| 557 |
|
| 558 | dma_vec
|
| 559 |
|
| 560 | - A small structure that contains a DMA address and length.
|
| 561 |
|
| 562 | DMA_CTRL_ACK
|
| 563 |
|
| 564 | - If clear, the descriptor cannot be reused by provider until the
|
| 565 | client acknowledges receipt, i.e. has a chance to establish any
|
| 566 | dependency chains
|
| 567 |
|
| 568 | - This can be acked by invoking async_tx_ack()
|
| 569 |
|
| 570 | - If set, does not mean descriptor can be reused
|
| 571 |
|
| 572 | DMA_CTRL_REUSE
|
| 573 |
|
| 574 | - If set, the descriptor can be reused after being completed. It should
|
| 575 | not be freed by provider if this flag is set.
|
| 576 |
|
| 577 | - The descriptor should be prepared for reuse by invoking
|
| 578 | ``dmaengine_desc_set_reuse()`` which will set DMA_CTRL_REUSE.
|
| 579 |
|
| 580 | - ``dmaengine_desc_set_reuse()`` will succeed only when channel support
|
| 581 | reusable descriptor as exhibited by capabilities
|
| 582 |
|
| 583 | - As a consequence, if a device driver wants to skip the
|
| 584 | ``dma_map_sg()`` and ``dma_unmap_sg()`` in between 2 transfers,
|
| 585 | because the DMA'd data wasn't used, it can resubmit the transfer right after
|
| 586 | its completion.
|
| 587 |
|
| 588 | - Descriptor can be freed in few ways
|
| 589 |
|
| 590 | - Clearing DMA_CTRL_REUSE by invoking
|
| 591 | ``dmaengine_desc_clear_reuse()`` and submitting for last txn
|
| 592 |
|
| 593 | - Explicitly invoking ``dmaengine_desc_free()``, this can succeed only
|
| 594 | when DMA_CTRL_REUSE is already set
|
| 595 |
|
| 596 | - Terminating the channel
|
| 597 |
|
| 598 | - DMA_PREP_CMD
|
| 599 |
|
| 600 | - If set, the client driver tells DMA controller that passed data in DMA
|
| 601 | API is command data.
|
| 602 |
|
| 603 | - Interpretation of command data is DMA controller specific. It can be
|
| 604 | used for issuing commands to other peripherals/register reads/register
|
| 605 | writes for which the descriptor should be in different format from
|
| 606 | normal data descriptors.
|
| 607 |
|
| 608 | - DMA_PREP_REPEAT
|
| 609 |
|
| 610 | - If set, the transfer will be automatically repeated when it ends until a
|
| 611 | new transfer is queued on the same channel with the DMA_PREP_LOAD_EOT flag.
|
| 612 | If the next transfer to be queued on the channel does not have the
|
| 613 | DMA_PREP_LOAD_EOT flag set, the current transfer will be repeated until the
|
| 614 | client terminates all transfers.
|
| 615 |
|
| 616 | - This flag is only supported if the channel reports the DMA_REPEAT
|
| 617 | capability.
|
| 618 |
|
| 619 | - DMA_PREP_LOAD_EOT
|
| 620 |
|
| 621 | - If set, the transfer will replace the transfer currently being executed at
|
| 622 | the end of the transfer.
|
| 623 |
|
| 624 | - This is the default behaviour for non-repeated transfers, specifying
|
| 625 | DMA_PREP_LOAD_EOT for non-repeated transfers will thus make no difference.
|
| 626 |
|
| 627 | - When using repeated transfers, DMA clients will usually need to set the
|
| 628 | DMA_PREP_LOAD_EOT flag on all transfers, otherwise the channel will keep
|
| 629 | repeating the last repeated transfer and ignore the new transfers being
|
| 630 | queued. Failure to set DMA_PREP_LOAD_EOT will appear as if the channel was
|
| 631 | stuck on the previous transfer.
|
| 632 |
|
| 633 | - This flag is only supported if the channel reports the DMA_LOAD_EOT
|
| 634 | capability.
|
| 635 |
|
| 636 | General Design Notes
|
| 637 | ====================
|
| 638 |
|
| 639 | Most of the DMAEngine drivers you'll see are based on a similar design
|
| 640 | that handles the end of transfer interrupts in the handler, but defer
|
| 641 | most work to a tasklet, including the start of a new transfer whenever
|
| 642 | the previous transfer ended.
|
| 643 |
|
| 644 | This is a rather inefficient design though, because the inter-transfer
|
| 645 | latency will be not only the interrupt latency, but also the
|
| 646 | scheduling latency of the tasklet, which will leave the channel idle
|
| 647 | in between, which will slow down the global transfer rate.
|
| 648 |
|
| 649 | You should avoid this kind of practice, and instead of electing a new
|
| 650 | transfer in your tasklet, move that part to the interrupt handler in
|
| 651 | order to have a shorter idle window (that we can't really avoid
|
| 652 | anyway).
|
| 653 |
|
| 654 | Glossary
|
| 655 | ========
|
| 656 |
|
| 657 | - Burst: A number of consecutive read or write operations that
|
| 658 | can be queued to buffers before being flushed to memory.
|
| 659 |
|
| 660 | - Chunk: A contiguous collection of bursts
|
| 661 |
|
| 662 | - Transfer: A collection of chunks (be it contiguous or not)
|