Documentation/driver-api/dmaengine/provider.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/dmaengine/provider.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/dmaengine/provider.rst
Extension
.rst
Size
24304 bytes
Lines
663
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

==================================
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-eligible 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 a specific number of bits to be transferred 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 used as a source
or destination, can 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 without the controller splitting the
transfer into smaller sub-transfers.

Our theoretical 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 on
your hardware. Each DMA controller will require a different structure,
but all of them will require, for every chunk, at least the source and

Annotation

Implementation Notes