[PATCH v2 2/2] Documentation: dmaengine: Add a documentation for the dma controller API

[Maxime Ripard]

On Tue, Oct 07, 2014 at 02:16:47PM +0200, Nicolas Ferre wrote:
> Hi Maxime,
> 
> First of all, thanks a lot for this needed documentation.
> 
> I do my little comments on top of Laurent's ones.
> 
> 
> On 06/10/2014 14:09, Laurent Pinchart :
> > Hi Maxime,
> > 
> > Thank you for working on this. Please see below for a couple of comments in 
> > addition to Randy's proof-reading.
> > 
> > On Friday 26 September 2014 17:40:35 Maxime Ripard wrote:
> >> The dmaengine is neither trivial nor properly documented at the moment,
> >> which means a lot of trial and error development, which is not that good
> >> for such a central piece of the system.
> >>
> >> Attempt at making such a documentation.
> >>
> >> Signed-off-by: Maxime Ripard <maxime.ripard at free-electrons.com>
> >> ---
> >>  Documentation/dmaengine/provider.txt | 358 ++++++++++++++++++++++++++++++++
> >>  1 file changed, 358 insertions(+)
> >>  create mode 100644 Documentation/dmaengine/provider.txt
> >>
> >> diff --git a/Documentation/dmaengine/provider.txt
> >> b/Documentation/dmaengine/provider.txt new file mode 100644
> >> index 000000000000..ba407e706cde
> >> --- /dev/null
> >> +++ b/Documentation/dmaengine/provider.txt
> >> @@ -0,0 +1,358 @@
> >> +DMAengine controller documentation
> >> +==================================
> >> +
> >> +Hardware Introduction
> >> ++++++++++++++++++++++
> >> +
> >> +Most of the Slave DMA controllers have the same general principles of
> >> +operations.
> >> +
> >> +They have a given number of channels to use for the DMA transfers, and
> >> +a given number of requests lines.
> >> +
> >> +Requests and channels are pretty much orthogonal. Channels can be used
> >> +to serve several to any requests. To simplify, channels are the
> >> +entities that will be doing the copy, and requests what endpoints are
> >> +involved.
> >> +
> >> +The request lines actually correspond to physical lines going from the
> >> +DMA-elligible devices to the controller itself. Whenever the device
> >> +will want to start a transfer, it will assert a DMA request (DRQ) by
> >> +asserting that request line.
> >> +
> >> +A very simple DMA controller would only take into account a single
> >> +parameter: the transfer size. At each clock cycle, it would transfer a
> >> +byte of data from one buffer to another, until the transfer size has
> >> +been reached.
> >> +
> >> +That wouldn't work well in the real world, since slave devices might
> >> +require to have to retrieve various number of bits from memory at a
> >> +time. For example, we probably want to transfer 32 bits at a time when
> >> +doing a simple memory copy operation, but our audio device will
> >> +require to have 16 or 24 bits written to its FIFO. This is why most if
> >> +not all of the DMA controllers can adjust this, using a parameter
> >> +called the width.
> > 
> > DMA engines can have buses larger than 32 bits, I would thus phrase that as 
> > follows.
> > 
> > "That wouldn't work well in the real world, since slave devices might require 
> > a specific number of bits to be transfered in a single cycle. For example, we 
> > may want to transfer as much data as the physical bus allows to maximize 
> > performances when doing a simple memory copy operation, but our audio device 
> > could have a narrower FIFO that requires data to be written exactly 16 or 24 
> > bits at a time. This is why most if not all of the DMA controllers can adjust 
> > this, using a parameter called the transfer width."
> > 
> >> +Moreover, some DMA controllers, whenever the RAM is involved, can
> > 
> > s/the RAM is involved/RAM is used as a source or destination/ ?
> > 
> >> +group the reads or writes in memory into a buffer, so instead of
> >> +having a lot of small memory accesses, which is not really efficient,
> >> +you'll get several bigger transfers. This is done using a parameter
> >> +called the burst size, that defines how many single reads/writes it's
> >> +allowed to do in a single clock cycle.
> 
> Yes, here "single" word is used for different concepts and can have
> several meanings. We usually make the difference between "single"
> accesses and "burst" accesses.

Which was kind of what I was explaining, but it was probably not clear
enough.

> 
> > The burst size defines "how many read or write operations can be queued to 
> > buffers before being flushed to memory". Several clock cycles will still most 
> > likely be needed, the performance improvements here come from the fact that 
> > the accesses can be performed in bursts.
> > 
> >> +Our theorical DMA controller would then only be able to do transfers
> >> +that involve a single contiguous block of data. However, some of the
> >> +transfers we usually have are not, and want to copy data from
> >> +non-contiguous buffers to a contiguous buffer, which is called
> >> +scatter-gather.
> >> +
> >> +DMAEngine, at least for mem2dev transfers, require support for
> >> +scatter-gather. So we're left with two cases here: either we have a
> >> +quite simple DMA controller that doesn't support it, and we'll have to
> >> +implement it in software, or we have a more advanced DMA controller,
> >> +that implements in hardware scatter-gather.
> >> +
> >> +The latter are usually programmed using a collection of chunks to
> >> +transfer, and whenever the transfer is started, the controller will go
> >> +over that collection, doing whatever we programmed there.
> >> +
> >> +This collection is usually either a table or a linked list. You will
> >> +then push either the address of the table and its number of elements,
> >> +or the first item of the list to one channel of the DMA controller,
> >> +and whenever a DRQ will be asserted, it will go through the collection
> >> +to know where to fetch the data from.
> >> +
> >> +Either way, the format of this collection is completely dependent of
> >> +your hardware. Each DMA controller will require a different structure,
> >> +but all of them will require, for every chunk, at least the source and
> >> +destination addresses, wether it should increment these addresses or
> >> +not and the three parameters we saw earlier: the burst size, the bus
> >> +width and the transfer size.
> > 
> > I would talk about "transfer width" here, as the transfer width can be smaller 
> > than the bus width (I've even seen a strange case of a transfer width larger 
> > than the physical bus width).
> > 
> >> +The one last thing is that usually, slave devices won't issue DRQ by
> >> +default, and you have to enable this in your slave device driver first
> >> +whenever you're willing to use DMA.
> >> +
> >> +These were just the general memory-to-memory (also called mem2mem) or
> >> +memory-to-device (mem2dev) transfers. Other kind of transfers might be
> >> +offered by your DMA controller, and are probably already supported by
> >> +dmaengine.
> 
> I don't understand this part as you were talking about mem2dev and slave
> devices just above. I would just remove this last paragraph...

I wanted to introduce the XOR, interleaved, and all the other DMA
transfer variants that might be supported, beyond just memory to
device or memory to memory transfers.

> 
> >> +
> >> +DMA Support in Linux
> >> +++++++++++++++++++++
> >> +
> >> +Historically, DMA controller driver have been implemented using the
> > 
> > s/driver/drivers/
> > 
> >> +async TX API, to offload operations such as memory copy, XOR,
> >> +cryptography, etc, basically any memory to memory operation.
> >> +
> >> +Over the time, the need for memory to device transfers arose, and
> >> +dmaengine was extended. Nowadays, the async TX API is written as a
> >> +layer on top of dmaengine, and act as a client. Still, dmaengine
> >> +accomodates that API in some cases, and made some design choices to
> >> +ensure that it stayed compatible.
> >> +
> >> +For more information on the Async TX API, please look the relevant
> >> +documentation file in Documentation/crypto/async-tx-api.txt.
> >> +
> >> +DMAEngine Registration
> >> +++++++++++++++++++++++
> >> +
> >> +struct dma_device Initialization
> >> +--------------------------------
> >> +
> >> +Just like any other kernel framework, the whole DMAEngine registration
> >> +relies on the driver filling a structure and registering against the
> >> +framework. In our case, that structure is dma_device.
> >> +
> >> +The first thing you need to do in your driver is to allocate this
> >> +structure. Any of the usual memory allocator will do, but you'll also
> >> +need to initialize a few fields in there:
> >> +
> >> +  * chancnt:	should be the number of channels your driver is exposing
> >> +		to the system.
> >> +		This doesn't have to be the number of physical
> >> +		channels: some DMA controllers also expose virtual
> >> +		channels to the system to overcome the case where you
> >> +		have more consumers than physical channels available.
> > 
> > If I'm not mistaken the dma_async_register_device() function sets chancnt 
> > internally.
> > 
> >> +  * channels:	should be initialized as a list using the
> >> +		INIT_LIST_HEAD macro for example
> > 
> > More than that, drivers must fill that list before calling 
> > dma_async_register_device().
> > 
> >> +  * dev: 	should hold the pointer to the struct device associated
> >> +		to your current driver instance.
> >> +
> >> +Supported transaction types
> >> +---------------------------
> >> +The next thing you need is to actually set which transaction type your
> > 
> > You can drop the "actually".
> > 
> > s/type/types/
> > 
> >> +device (and driver) supports.
> >> +
> >> +Our dma_device structure has a field called caps_mask that holds the
> > 
> > s/caps_mask/cap_mask/
> > 
> >> +various types of transaction supported, and you need to modify this
> >> +mask using the dma_cap_set function, with various flags depending on
> >> +transaction types you support as an argument.
> >> +
> >> +All those capabilities are defined in the dma_transaction_type enum,
> >> +in include/linux/dmaengine.h
> >> +
> >> +Currently, the types available are:
> >> +  * DMA_MEMCPY
> >> +    - The device is able to do memory to memory copies
> >> +
> >> +  * DMA_XOR
> >> +    - The device is able to perform XOR operations on memory areas
> >> +    - Particularly useful to accelerate XOR intensive tasks, such as
> > 
> > s/- Particularly useful/  Used to/ ?
> > 
> >> +      RAID5
> >> +
> >> +  * DMA_XOR_VAL
> >> +    - The device is able to perform parity check using the XOR
> >> +      algorithm against a memory buffer.
> >> +
> >> +  * DMA_PQ
> >> +    - The device is able to perform RAID6 P+Q computations, P being a
> >> +      simple XOR, and Q being a Reed-Solomon algorithm.
> >> +
> >> +  * DMA_PQ_VAL
> >> +    - The device is able to perform parity check using RAID6 P+Q
> >> +      algorithm against a memory buffer.
> >> +
> >> +  * DMA_INTERRUPT
> >> +    /* TODO: Is it that the device has one interrupt per channel? */
> > 
> > If I'm not mistaken DMA_INTERRUPT means the device supports the 
> > device_prep_dma_interrupt() operation, which prepares a dummy transfer that 
> > will not transfer any data but will generate an interrupt, calling the 
> > complete callback.
> > 
> >> +
> >> +  * DMA_SG
> >> +    - The device supports memory to memory scatter-gather
> >> +      transfers.
> >> +    - Even though a plain memcpy can look like a particular case of a
> >> +      scatter-gather transfer, with a single chunk to transfer, it's a
> >> +      distinct transaction type in the mem2mem transfers case
> >> +
> >> +  * DMA_PRIVATE
> >> +    - The devices only supports slave transfers, and as such isn't
> >> +      avaible for async transfers.
> >> +
> >> +  * DMA_ASYNC_TX
> >> +    - Must not be set by the device, and will be set by the framework
> >> +      if needed
> >> +    - /* TODO: What is it about? */
> >> +
> >> +  * DMA_SLAVE
> >> +    - The device can handle device to memory transfers, including
> >> +      scatter-gather transfers.
> >> +    - While in the mem2mem case we were having two distinct types to
> >> +      deal with a single chunk to copy or a collection of them, here,
> >> +      we just have a single transaction type that is supposed to
> >> +      handle both.
> 
> For transferring an unique buffer, simply build a collection with only
> one element.

Yep.

> >> +
> >> +  * DMA_CYCLIC
> >> +    - The device can handle cyclic transfers.
> >> +    - A cyclic transfer is a transfer where the chunk collection will
> >> +      loop over itself, with the last item pointing to the first. It's
> >> +      usually used for audio transfers, where you want to operate on a
> >> +      single big buffer that you will fill with your audio data.
> > 
> > The buffer doesn't have to be big, I would s/big buffer/ring buffer/.
> > 
> >> +
> >> +  * DMA_INTERLEAVE
> >> +    - The device supports interleaved transfer. Those transfers
> >> +      usually involve an interleaved set of data, with chunks a few
> >> +      bytes wide, where a scatter-gather transfer would be quite
> >> +      inefficient.
> 
> Well, I don't know if it is related to efficiency. It is more another
> pattern for the transfer which is described by a "template": struct
> dma_interleaved_template.
> This mode is extremely flexible and due to its use of a different
> scatter-gather for source and destination can implement any memory
> organization. Think about 2D objects on a screen or picture-in-picture
> mode with consecutive addresses, holes, edges and frames boundaries.

True, thanks.

> 
> 
> > This is typically used to transfer 2D content such as uncompressed video.
> > 
> >> +These various types will also affect how the source and destination
> >> +addresses change over time, as DMA_SLAVE transfers will usually have
> >> +one of the addresses that will increment, while the other will not,
> >> +DMA_CYCLIC will have one address that will loop, while the other, will
> > 
> > s/the other,/the other/
> > 
> >> +not change, etc.
> 
> This is a little bit vague in my opinion. And usually, it is pretty
> implementation specific.

Which is why we can't really be more precise. If you have any other
wording coming to your mind, I'm all for it :)

> >> +Device operations
> >> +-----------------
> >> +
> >> +Our dma_device structure also requires a few function pointers in
> >> +order to implement the actual logic, now that we described what
> >> +operations we were able to perform.
> >> +
> >> +The functions that we have to fill in there, and hence have to
> >> +implement, obviously depend on the transaction types you reported as
> >> +supported.
> >> +
> >> +   * device_alloc_chan_resources
> >> +   * device_free_chan_resources
> >> +     - These functions will be called whenever a driver will call
> >> +       dma_request_channel or dma_release_channel for the first/last
> >> +       time on the channel associated to that driver.
> >> +     - They are in charge of allocating/freeing all the needed
> >> +       resources in order for that channel to be useful for your
> >> +       driver.
> >> +     - These functions can sleep.
> >> +
> >> +   * device_prep_dma_*
> >> +     - These functions are matching the capabilities you registered
> >> +       previously.
> >> +     - These functions all take the buffer or the scatterlist relevant
> >> +       for the transfer being prepared, and should create a hardware
> >> +       descriptor or a list of descriptors from it
> >> +     - These functions can be called from an interrupt context
> >> +     - Any allocation you might do should be using the GFP_NOWAIT
> >> +       flag, in order not to potentially sleep, but without depleting
> >> +       the emergency pool either.
> > 
> > You could add "Drivers should try to preallocate the data structures they 
> > require to prepare a transfer."
> > 
> >> +
> >> +     - It should return a unique instance of the
> >> +       dma_async_tx_descriptor structure, that further represents this
> >> +       particular transfer.
> >> +
> >> +     - This structure can be allocated using the function
> >> +       dma_async_tx_descriptor_init.
> > 
> > That function only initializes the tx descriptor, it doesn't allocate it.
> 
> Beware, it can be confusing when mixing "descriptors" and "hardware
> descriptors". The ones used by the DMA controller itself to describe the
> chunks of data (hardware descriptors) and the ones that would represent
> them in the driver (tx descriptors). However, it's true that both must
> be prepared by this set of functions.

There's a few "hardware" missing indeed, but we can't really avoid the
confusion here, since it does rely also on a dma_async_tx_descriptor.

> >> +     - You'll also need to set two fields in this structure:
> >> +       + flags:
> >> +		TODO: Can it be modified by the driver itself, or
> >> +		should it be always the flags passed in the arguments
> >> +
> >> +       + tx_submit:	A pointer to a function you have to implement,
> >> +			that is supposed to push the current descriptor
> >> +			to a pending queue, waiting for issue_pending to
> >> +			be called.
> 
> The question remains: why wait when all the information is already
> prepared and available for the DMA controller to start the job?
> Actually, we don't wait in at_hdmac, just to be more efficient, but I
> known that we kind of break this "requirement"... But sorry, it is
> another discussion which should be lead elsewhere.

It's just a guess, but maybe you might not be able to schedule the
transfer right away? Think about a very dumb 1-channel (or a more
realistic more-DRQ-than-channel) device. You might have all the
channels busy doing some other transfers, and it's not really part of
the client driver job to address that kind of contention: it just
wants to queue some work for a later transfer.

> >> +
> >> +   * device_issue_pending
> >> +     - Takes the first descriptor in the pending queue, and starts the
> >> +       transfer. Whenever that transfer is done, it should move to the
> >> +       next transaction in the list.
> >> +     - It should call the registered callback if any each time a
> >> +       transaction is done.
> 
> Can you clarify this?

The client driver might set up a callback, and it should be called
whenever that transaction is complete.

> >> +     - This function can be called in an interrupt context
> >> +
> >> +   * device_tx_status
> >> +     - Should report the bytes left to go over on the given channel
> 
> The first aim of this function is to poll for transaction completion, if
> I recall well. It reports also if there was an error during the transfer.
> 
> Moreover, I think it is not the number of "bytes" left, but the number
> of bytes using a granularity as described in enum
> dma_residue_granularity. All this depending on the capability of the
> controller to report such a value.

True.

> >> +     - Should also only concern about the given descriptor, not the
> >> +       currently active one.
> > 
> > I have to guess what you mean here :-)
> > 
> >> +     - The tx_state argument might be NULL
> >> +     - Should use dma_set_residue to report it
> >> +     - In the case of a cyclic transfer, it should only take into
> >> +       account the current period.
> >> +     - This function can be called in an interrupt context.
> >> +
> >> +   * device_control
> >> +     - Used by client drivers to control and configure the channel it
> >> +       has a handle on.
> >> +     - Called with a command and an argument
> >> +       + The command is one of the values listed by the enum
> >> +         dma_ctrl_cmd. To this date, the valid commands are:
> > 
> > s/To this date, the/The/
> > 
> >> +         + DMA_RESUME
> >> +           + Restarts a transfer on the channel
> >> +           + This command should operate synchronously on the channel,
> >> +             resuming right away the work of the given channel
> >> +         + DMA_PAUSE
> >> +           + Pauses a transfer on the channel
> >> +           + This command should operate synchronously on the channel,
> >> +             pausing right away the work of the given channel
> > 
> > I think you should list DMA_PAUSE first, and then explain that DMA_RESUME 
> > resumes operation of a paused channel.
> > 
> >> +         + DMA_TERMINATE_ALL
> >> +           + Aborts all the pending and ongoing transfers on the
> >> +             channel
> >> +           + This command should operate synchronously on the channel,
> >> +             terminating right away all the channels
> 
> Is it a strong requirement to "terminate right away" all the transfers
> on the channel? Must the ongoing transfer be stopped of can it ends its
> current chunk?

Since it's blocking, I guess it's fine to wait for the current chunk
to end as long as you block. But I'm not 100% sure on that. Russell? Vinod?

> >> +         + DMA_SLAVE_CONFIG
> >> +           + Reconfigures the channel with passed configuration
> >> +           + This command should NOT perform synchronously, or on any
> >> +             currently queued transfers, but only on subsequent ones
> >> +           + In this case, the function will receive a
> >> +             dma_slave_config structure pointer as an argument, that
> >> +             will detail which configuration to use.
> >> +           + Even though that structure contains a direction field,
> >> +             this field is deprecated in favor of the direction
> >> +             argument given to the prep_* functions
> >> +         + FSLDMA_EXTERNAL_START
> >> +           + TODO: Why does that even exist?
> >> +       + The argument is an opaque unsigned long. This actually is a
> >> +         pointer to a struct dma_slave_config that should be used only
> >> +         in the DMA_SLAVE_CONFIG.
> >> +
> >> +  * device_slave_caps
> >> +    - Called through the framework by client drivers in order to have
> >> +      an idea of what are the properties of the channel allocated to
> >> +      them.
> >> +    - Such properties are the buswidth, available directions, etc.
> >> +    - Required for every generic layer doing DMA transfers, such as
> >> +      ASoC.
> >> +
> >> +Misc notes (stuff that should be documented, but don't really know
> >> +where to put them)
> >> +------------------------------------------------------------------
> >> +  * dma_run_dependencies
> >> +    - Should be called at the end of an async TX transfer, and can be
> >> +      ignored ine the slave transfers case.
> > 
> > s/ine/in/
> > 
> >> +    - Makes sure that dependent operations are run before marking it
> >> +      as complete.
> >> +
> >> +  * dma_cookie_t
> >> +    - it's a DMA transaction ID, that will increment over time.
> >> +    - Not really relevant anymore since the introduction of virt-dma
> >> +      that abstracts it away.
> >> +
> >> +  * DMA_CTRL_ACK
> >> +    - Undocumented feature
> >> +    - No one really has an idea of what's it's about, beside being
> >> +      related to reusing the DMA descriptors or having additional
> >> +      transactions added to it in the async-tx API
> >> +    - Useless in the case of the slave API
> >> +
> >> +General Design Notes
> >> +--------------------
> >> +
> >> +Most of the DMAEngine drivers you'll see all are based on a similar
> >> +design that handles the end of transfer interrupts in the handler, but
> >> +defer most work to a tasklet, including the start of a new transfer
> >> +whenever the previous transfer ended.
> >> +
> >> +This is a rather inefficient design though, because the inter-transfer
> >> +latency will be not only the interrupt latency, but also the
> >> +scheduling latency of the tasklet, which will leave the channel idle
> >> +in between, which will slow down the global transfer rate.
> >> +
> >> +You should avoid this kind of pratice, and instead of electing a new
> >> +transfer in your tasklet, move that part to the interrupt handler in
> >> +order to have a shorter idle window (that we can't really avoid
> >> +anyway).
> >> +
> >> +Glossary
> >> +--------
> >> +
> >> +Burst:		Usually a few contiguous bytes that will be transfered
> >> +		at once by the DMA controller
> > 
> > A number of consecutive read or write operations that can be queued to buffers 
> > before being flushed to memory.

Will change.

Thanks!

Maxime

-- 
Maxime Ripard, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <http://lists.infradead.org/pipermail/linux-arm-kernel/attachments/20141007/364adba1/attachment-0001.sig>