DMA Framework Technology

The DMA Software Controller

This is the TDmac object. It has two purposes:

• It defines the main interface between the platform independent and platform specific layers.

• it is a container for channels, descriptors and descriptor headers

The Channel Manager

The channel manager is a DmaChannelMgr object.

DmaChannelMgr is a static class defined by the platform independent layer but implemented in the platform specific layer. The functionality is used by the platform independent layer. It contains:

• a function to open a DMA channel: DmaChannelMgr::Open()

• a function that is called when a channel is closed: DmaChannelMgr::Close()

• a function that can be used to extend the framework with platform specific functionality on a channel independent basis: DmaChannelMgr::StaticExtension()

Descriptors

DMA controllers operating in scatter/gather mode are configured via a linked list of small data structures describing the data to be transferred. These data structures are called descriptors. (Note that the use of the term descriptor in the context of DMA should not be confused with the same term widely used in Symbian platform to refer to the family of TDesC derived classes).

The Symbian platform DMA Framework always uses descriptor data structures to store transfer-configuration-information, even if the underlying DMA controller does not support scatter/gather mode.

The following example illustrates the idea: assume that a device driver needs to transfer two disjoint blocks of memory, A and B, into another block C. Block A starts at address 1000 and is 300 bytes long. Block B starts at address 2000 and is 700 bytes long. The destination buffer C starts at address 5000 and is 1000 bytes long. Assume that the DMA descriptors are allocated in a pool starting at address 600. The following diagram shows the scatter/gather list that the device driver might create:

If the DMA controller supports the scatter/gather arrangement, then the framework uses a structure that will be specific to the hardware. This structure is defined in the platform specific layer.

If the DMA controller does not support scatter/gather, then the framework uses the generic structure SDmaPseudoDes containing the following information:

• a set of generic flags that characterise the transfer. For example, is the source of the data memory or a peripheral; is the destination memory or peripheral; what addressing mode is to be used?

• the source and destination location. This is in the form of the base virtual address for a memory buffer, and a 32-bit value (or cookie) for peripherals. The meaning of the 32-bit value is interpreted by the platform specific layer.

• The number of bytes to be transferred.

• A word that only has meaning for the platform specific layer, and passed by the client at request fragmentation time.

Descriptor headers

These are objects of type SDmaDesHdr.

A descriptor header allows additional information about a descriptor to be stored. The header is a separate object from the descriptor because it is difficult to embed additional data in a structure whose layout may be hardware-imposed.

Descriptors and descriptor headers are stored in two parallel arrays allocated at boot-time, and each descriptor is always associated with the header of same index, so that there is always a one-to-one relationship between the header and the descriptor.

In the current design, the only information in the descriptor header is a pointer, SDmaDesHdr::iNext, that is used to chain headers together on various lists. So, although the pool of headers is allocated as an array, they are almost always accessed by following the chain of pointers linking one header to the next.

Descriptors are always accessed through their associated header.

The platform independent layer never directly accesses hardware-specific descriptors. It just passes descriptor headers to the platform specific layer. However, the platform independent layer does directly manipulate the generic descriptors, SDmaPseudoDes.

Transfer Requests

A transfer request is the way in which a device driver sets up and initiates a DMA transfer, and is represented by a DDmaRequest object.

A transfer request has a number of characteristics:

• it is always associated with exactly one channel.

• it stores a client-provided callback function, which is invoked when the whole request completes, whether successfully or not.

• it can be in one of four states:

  • not configured

  • idle

  • being transferred

  • pending; this state only occurs in streaming mode.

Internally, a transfer request is represented as a singly linked list of descriptor headers. Each header in the list is associated with a descriptor that specifies how to transfer one fragment of the whole request. Transfer requests have pointers to the first and last headers in the list.

When the request is idle, the header list ends with a NULL pointer. This is not always true when the request is queued (i.e. when the request is being transferred or is still pending). The following diagram shows an idle request with three fragments.

Splitting a request into fragments is useful because:

• it insulates device drivers from the maximum transfer size supported by the underlying DMA controller.

• the source and destination DMA buffers may not be physically contiguous and thus require fragmenting.

Both of these situations can be handled by using the generic fragmentation algorithm DDmaRequest::Fragment().

Some device drivers may have to create custom descriptors lists. For example, the USB section of the PXA250 manual describes how to build custom lists where a descriptor containing data transfer information is followed by another one poking an I/O port to issue a command to the USB controller.

To cover that case, DDmaRequest provides the DDmaRequest::ExpandDesList() member function to allocate a list of headers associated with blank descriptors whose content is then set by device drivers. Blank descriptors thus created can be accessed in the following way (this example was taken and simplified from the PXA250 USB controller driver):

TDmaChannel* channel;
TDmaChannel::SCreateInfo info;
info.x = y;
if (TDmaChannel::Open(info, channel) != KErrNone)
    ... return;
DDmaRequest* req = new DDmaRequest(*channel);
if (!req)
    ... return;
const TDmac* dmac = req->iChannel.Controller();
if (req->ExpandDesList(2) != KErrNone)
    ... return;
TDmaDesc* desc1 = static_cast<TDmaDesc*>(dmac->HdrToHwDes(*req->iFirstHdr));
TDmaDesc* desc2 = static_cast<TDmaDesc*>(dmac->HdrToHwDes(*req->iFirstHdr->iNext));
desc1->iSrcAddr  = ...;
desc1->iDestAddr = ...;
desc1->iDescAddr = ...;
desc1->iCmd      = ...;
desc2...
...

Channels

A channel is a TDmaChannel object, and there is one of these for each hardware DMA channel.

A channel can be in one of 4 states:

• closed

• open and idle

• open and transferring data

• suspended following an error.

On opening a channel, the client device driver specifies:

• A 32-bit value (cookie) that is used by the platform specific layer to select which channel is to be opened

• The number of descriptors that must be reserved for this channel.

• A DFC to be used by the framework to service DMA interrupts.

A channel maintains a queue of transfer requests. If the channel is being used for one-shot transfers, the queue will always contain an idle or a transferring request. In streaming mode, the queue may contain several requests, the first one being transferred and the remaining ones pending. When a request is completely transferred, it is removed from the queue. The first request is always the one being transferred.

A transferring channel has a pointer to the header associated with the descriptor being transferred. The headers of all queued requests are linked together on one linked list.

The following diagram shows a DMA channel with a three-fragment request being transferred and a two-fragment one pending. The fragment currently being transferred is the second one of the first request.

The TDmaChannel class contains the code and data that is common to all of the channel types. The code and data for the specific channel types: single buffer, double buffer, and scatter/gather channels, are implemented in the derived classes: TDmaSbChannel, TDmaDbChannel, and TDmaSgChannel respectively.

TDmaSbChannel State Machine

For reference purposes, the following diagram shows the state machine that TDmaSbChannel implements to deal with a single buffer channel.

TDmaDbChannel State Machine

For reference purposes, the following diagram shows the state machine that TDmaDbChannel implements to deal with a double buffer channel.

TDmaSgChannel State Machine

For reference purposes, the following diagram shows the state machine that TDmaSgChannel implements to deal with a scatter/gather channel.

Streaming and Scatter/Gather DMA Controllers

When a transfer request is queued onto a channel that is already transferring data, the header descriptor for the new list of descriptors is appended to the header of the previous request on the queue. If the underlying DMA controller supports hardware descriptors, they must also be linked together.

The following diagram shows how headers and descriptors for a new request are appended to the existing ones for a DMA controller. The dashed arrows represent the new links.

Note that hardware descriptors are linked together using physical addresses, not virtual ones.

Linking hardware descriptors together is implemented in the platform specific layer. There are two issues to consider:

• The channel may go idle before the linking is complete, which means that the data for the new request would not be transferred.

• If the channel is transferring the last descriptor in the list, then updating the “next” field in the descriptor will have no effect because the content of the descriptor will already have been loaded in the controller registers. Again the channel would go idle without transferring the data associated with the new request.

The solutions available when porting the DMA Framework are:

• If the DMA controller has hardware support for appending descriptors while transferring data, then there is no problem.

• If the peripheral attached to the channel can withstand a short disruption in the transfer flow, then the channel can be suspended while the appending takes place. This should be done with interrupts disabled to minimise disruption.

• The alternative technique is to append the new list with interrupts disabled and set a flag. When the next interrupt occurs, if the flag is set and the channel idle, then the interrupt service routine must restart the transfer.

See Channels.

Interrupt Service Routine (ISR) and DFC Issues

The platform specific layer must notify the platform independent layer when the following events occur:

• when an error occurs.

• when each fragment completes, for single-buffer and double-buffer controllers.

• when the last fragment of a request completes, for scatter/gather controllers.

The ISR, as implemented in the platform specific layer, must:

• determine which channel the interrupt is for. If the DMA controller uses dedicated interrupt lines per channel, the ASSP/variant interrupt dispatcher will do this. See Interrupt Dispatcher Tutorial.

• determine whether the interrupt was asserted following a successful transfer completion or a failure. If the DMA controller uses different interrupt lines for completion and failure, the ASSP/variant interrupt dispatcher will do this.

• Call TDmac::HandleIsr() in the platform specific layer. This function queues the DFC associated with the relevant channel. It takes care of the case where several interrupts occur before the DFC gets a chance to run.

The DFC updates the state of the channel and, for single and double buffer DMA controllers, configures the next fragment to transfer, if any. When all fragments making up a request have been transferred, the DFC calls the client-supplied callback associated with the completed request. The callback is also called if an error occurs during transfer.

Locking Strategy

For a given device driver, TDmaChannel and DDmaRequest instances can be accessed concurrently from the device driver thread and from a DFC queue thread. To avoid race conditions, each TDmaChannel instance has a fast mutex, the protected data member TDmaChannel::iLock. This lock is acquired when queuing a new request, cancelling requests and executing the DFC.

TDmaChannel and DDmaRequest instances are not protected against concurrent access from several client threads because this is assumed to be an exceptional case. A device driver with such need would have to implement its own locking scheme around calls to TDmaChannel and DDmaRequest member functions.

Each TDmac instance includes a fast mutex, the private member TDmac::iLock to protect descriptor reservation and allocation, because several device drivers may try to reserve or allocate descriptors concurrently.

The DmaChannelMgr static class includes a fast mutex which is used to protect channel opening as several device drivers may compete for the same channel. This lock is also used at channel closing time.