XDMAC — eCos Support for the Atmel XDMAC Controller
ch = atmel_dmac_chan_alloc(
This package provides access to the Atmel XDMAC (Extended DMA Controller) devices. This support is not intended to expose the full functionality of these devices. It is mainly limited to supporting peripheral DMA (e.g. USART, SPI, etc.). It is currently limited to single DMA transfers.
There is currently no cross-platform/variant standardised eCos DMA I/O interface package, since DMA features and functionality vary greatly between architectures, and event within variants of an architecture. This stand-alone device package allows common DMA support to be shared between devices that implement Atmel DMA Controllers.
The user is directed towards the relevant Atmel documentation for a full description of the XDMAC devices, and to the variant device drivers for examples of the use of this API. This documentation only gives a brief description of the functions available.
The API of this controller is designed to be compatible with that for the Atmel DMAC controller and is a drop-in replacement for it. Thus the API refers to the DMAC in its naming, not the XDMAC.
A XDMAC instance is defined by a controller number (0 or 1), and each controller has support for a number of (variant defined) channels. The API uses a simple 32-bit encoding to describe how a specific DMA channel should be used, with this package providing helper macros to combine the necessary information into a unique descriptor. These descriptors may be stored with a device driver as required.
The following are examples of how definitions can be made:
// USART0 TX on controller 0, 8-bit mem-to-peripheral transfers using default memory interfaces #define AT91_SERIAL0_DMA_TX CYGHWR_ATMEL_DMA_M2P(0,USART0_TX,8) // USART0 RX on controller 0, 8-bit peripheral-to-mem transfers using default memory interfaces #define AT91_SERIAL0_DMA_RX CYGHWR_ATMEL_DMA_P2M(0,USART0_RX,8)
Before DMA transfers can be performed, a DMA channel must be
claimed. This is done by
argument describes the majority of the DMA transfer configuration that
will be used. As shown in the examples above the passed descriptor not
only encodes the source and destination interfaces, but also the
transfer sizes. Also, depending on the descriptor construction macros
used, it is possible to control the direction and modification of
addresses during transfers. The
cb argument is
used to register a client function that will be called when a
requested transfer completes. The
is a client specified value that will be passed to the callback
function, and can be used to reference client driver specific data.
atmel_dmac_chan_config() function is
present for compatibility with the DMAC driver. It is not
currently needed, but device drivers that may use both drivers
may call this with not effect.
Most drivers will allocate a DMA channel object and keep it active
throughout the system lifetime. However, if it is necessary to share a
channel, or otherwise disable the use of a stream, the driver may
atmel_dmac_chan_free() to return a channel
to an unused state. It will be necessary to
atmel_dmac_chan_alloc() before specific DMA
descriptor operations can be performed again.
The register callback function has the following prototype:
typedef void atmel_dmac_callback( atmel_dmac_channel *ch, cyg_uint32 cbid, cyg_uint32 count, CYG_ADDRWORD data );
ch is the channel structure describing the
cbid argument is a completion
Table 114.1. Completion Codes
A valid transfer completion. The |
||This code indicates that the DMA Controller has detected an AHB read or write access error. This may indicate invalid memory addresses have been passed, or invalid AHB_IF mappings have been used.|
||For configurations where Descriptor Integrity Check support is available, and enabled, then if an error is detected in a referenced memory-based transfer structure this result will be raised.|
count argument is the number of data items
successfully transferred. The
data argument is
the client private data registered for the callback.
A transfer is configured and started by
argument describes the DMA channel, with the descriptor used when
allocating the channel defining how the other arguments are
src argument defines the peripheral
or memory address from which the transfer will be
dst argument supplies the peripheral
or memory address to which the transfer will
size argument defines the number of
data items to be transferred. Once this function call completes the
channel is operational and will transfer data once the relevant
peripheral starts triggering transfers.
When the transfer completes the registered callback is called from DSR mode.
|2023-08-15||Open Publication License|