Description

The HAL provides support for access to the DMA channels. This support is not intended to expose the full functionality of these devices and is mainly limited to supporting peripheral DMA. The API is therefore mainly oriented for use by device drivers rather than applications. The user is referred to the BCM2835 documentation for full details of the DMA channels, and to the SDHOST driver for an example of this API in use.

The DMA hardware consist of sixteen independent channels. DMA is initiated by attaching a chain of control blocks to a channel and starting it running. Each control block contains source and destination addresses, size, transfer direction and a number of other parameters. Of the sixteen channels available, some are reserved for use by the GPU. Also, the channels are divided into full function channels and lite channels that lack some functionality and have lower bandwidth. Full details are available in the BCM2835 documentation.

A DMA channel is represented by a hal_dma_channel object that the client must allocate. Control blocks are similarly represented by a hal_dma_cb object, which again must be allocated by the client. DMA control blocks must be aligned on a 32 byte boundary. The type definition in bcm283x_dma.h has an alignment attribute so that static allocations should be correctly aligned by default; however care should be taken to align dynamic allocations.

A DMA channel is initialized by calling hal_dma_channel_init, the parameters are as follows:

If the initialization is successful the routine will return 1. The current implementation of the DMA API permanently allocates a physical channel when this routine is called. In the future the allocation of physical channels may be more dynamic, so the client should not assume that the channel in use is constant.

The hal_dma_channel_delete function deletes the given channel, releasing any resources and making them available for reuse.

The hal_dma_channel_set_polled function marks a channel for polled operation only. Otherwise the channel will enable interrupts and wait for an interrupt to complete. If a channel is marked polled then it will only be completed and its callback called during calls to hal_dma_poll. Note that channels not marked polled may also be completed during this call if their interrupt has not yet fired.

A transfer control block is initialized by calling hal_dma_cb_init. The parameters are as follows:

Once initialized a control block may be added to a channel by calling hal_dma_cb_add. Control blocks will be chained together on the channel in the order in which they are added. The DMA engines operate on addresses in the GPU address space, not the physical address space visible the the ARM CPUs or the virtual address space set up by the MMU. During initialization the source and destination addresses will be translated into GPU addresses, and after it is added, the dma_next field of the control block will be translated to a GPU address. So, care should be taken when inspecting an active control block and it should not be changed.

Once a channel had been initialized and any control blocks have been added the transfers may be started by calling hal_dma_channel_start. For channels not marked polled, interrupts will fire and the callback will be called from a DSR when the control block chain has been completed. For polled channel, it will be necessary to call hal_dma_poll until all channels have completed.

An ongoing transfer may be halted by calling hal_dma_channel_stop. This function should also be called as a matter of course when a transfer has completed normally.