The HAL provides support for access to the EDMA3 DMA
controllers. This support is not intended to expose the full
functionality of these devices and is strictly limited to
supporting peripheral DMA, in particular SPI and MMC/SD.
The user is referred to the TI EDMA3 documentation for a full
description of the EDMA3 devices, and to the sources of the MMC
and SPI drivers for examples of the use of this API. This
documentation only gives a brief description of the functions
available.
Each device transfer direction is described by a controller number
(0 or 1) and an event numbers (0 to 31). These values are usually
defined by the peripheral being accessed. The macro
CYGHWR_HAL_L1XX_EDMA_CHANNEL( controller,
event) combines these into a descriptor that may be
used to initialize the channel. A channel is controlled by a
hal_edma_channel object that must be allocated by
the client. To initialize a channel,
hal_edma_channel_init() is called, passing
the channel object, the descriptor and an optional callback
function and user-defined value. After use the channel can be
deleted with hal_edma_channel_delete().
Before starting a transfer, the channel must be initialized with
the source, destination and size of the transfer to be
done. hal_edma_channel_source() and
hal_edma_channel_dest() describe the source
and destination buffers. A memory buffer is described by its
address plus the increments, or indexes, to step the read or write
pointer through it. The sizes of these indexes depend on the size
of the transfers that the peripheral is programmed to make, and
its synchronisation mode. One of the source or destination will be
the peripheral itself; the address should be the address of the
peripheral's input or output data register, and the indexes should
be zero to prevent the pointer incrementing.
hal_edma_channel_size() supplies the total
transfer size in bytes.
hal_edma_channel_burstsize() describes the A
and B burst sizes for AB synchronized transfers and must be called
before hal_edma_channel_size(). If
hal_edma_channel_burstsize() is not called
then A synchronization is assumed. The values set by
hal_edma_channel_burstsize() remain set in
the channel, and another call to this function is needed to reset
them.
A transfer is started by calling
hal_edma_channel_start(). The
opt argument contains bits that will be
merged with the PaRAM options field. When a transfer is complete,
then hal_edma_channel_stop() should be
called. This function may also be called to abort a transfer.
If a callback was passed to
hal_edma_channel_init() then when the
transfer finishes or encounters and error, the callback will be
called from DSR context. The callback will be passed a pointer to
the channel object, an event code and the user-defined value that
was passed to hal_edma_channel_init(). There
are two possible event codes:
CYGHWR_HAL_L1XX_EDMA_COMPLETE indicates that
the transfer finished successfully, and
CYGHWR_HAL_L1XX_EDMA_ERROR indicates that an
error condition was encountered.
In kernel configurations the DMA system will use interrupts to
detect transfer completion or errors. In non-kernel configurations
it will use polling. For the polling to happen, client code must
call hal_edma_poll() on a regular basis. On
DMA completion the callback function will be called, as before.
