STLinux

STMicroelectronics DMA API

Introduction

The STMicroelectronics DMA API is a kernel-space API that provides access to the Flexible DMA engine (FDMA). It provides two modes:

• a generic mode for standard transfers from one memory location to another, compatible with the original SHDMA-API
• an extended STMicroelectronics specific mode that gives support for paced transfers to and from peripherals and freerunning transfers from one memory location to another. In some cases a list of memory addresses can be provided, to perform scatter-gather transfers, or for more explicit control DMA transfer descriptors can be linked together.

Note: While the STMicroelectronics DMA API is an abstract description of DMA behavior, it is heavily biased towards the behavior and features provided by the FDMA hardware and firmware. For this reason it may help to refer to the FDMA documentation while reading this section.

Note: No support is provided for PES scanning or SPDIF compressed audio formatting that has native support in the firmware of the STB710x series SoCs. Generic SPDIF transfers (PCM) are supported, however.

The FDMA, like most DMA hardware, supports multiple channels. Each channel operates independently, allowing multiple concurrent transfers to be performed. A driver reserves and releases a channel through a request and free mechanism. Once requested, a channel is reserved by the driver until a free call returns it to the available pool. A channel can be selected by number, by the next available, or by its capacity — this is because certain channels in the FDMA firmware are optimized for particular application requirements, such as memory bandwidth and buffer space.

The behaviour of a transfer is described using a transfer descriptor. Transfer descriptors are set up programmatically, describing the transfer type, and specifying details specific to that transfer type, such as addresses or pacing channels. At this point the transfer descriptor is independant of any DMA channel. The transfer is tied to a specific channel only when it is compiled, and this association persists until the entire transfer is completed. For subsequent executions of the transfer, it can be re-associated with the same, or any other channel.

This strategy enables a device driver to initialize a number of transfer descriptors of different configurations and then utilize them as required. The low level FDMA driver allocates memory for the FDMA nodes and associates it with the transfer descriptor when the node is compiled. The memory persists until the user explicitly destroys the transfer descriptor. This means that compiled transfers can be re-compiled (within certain limitations) with new parameters. Parameters such as size and address can be modified, but not those which change the mode of the transfer.

Nodes of heterogeneous types can be linked together in an arbitrary way, providing a more flexible model. For example, it is possible to configure a transfer that scatter-gathers memory from user-space into a kernel buffer, then link that transfer to a paced one that feeds the date to a particular peripheral. Both open ended and circular linked lists are available, although circular lists can only be linked back to the first node in a chain, as only the last node in the chain is capable of linking back.