dma.h File Reference

Interface to the dma peripheral. More...

#include <stdint.h>
#include <stdlib.h>
#include "../memoryManagement/cacheCoherentMemoryProvider.h"

Go to the source code of this file.

Data Structures
struct	ControlBlock_struct
	Describes a control block, contorl blocks are needed to load the registers of the DMA engine and start a transfer. More...

Macros
#define	TI_NO_WIDE_BURSTS_OFF   26
	Transfer Info register: No 2 beat bursts, missing in channels over 6.
#define	TI_NO_WIDE_BURSTS_MASK   (1<<TI_NO_WIDE_BURSTS_OFF)
	Transfer Info register: No 2 beat bursts, missing in channels over 6.
#define	TI_WAITS_OFF   21
	Transfer Info register: number of dummy writes after read or write.
#define	TI_WAITS_MASK   (31<<TI_WAITS_OFF)
	Transfer Info register: number of dummy writes after read or write.
#define	TI_PERMAP_OFF   16
	Transfer Info register: selects the peripheral from wich reading the DREQ.
#define	TI_PERMAP_MASK   (31<<TI_PERMAP_OFF)
	Transfer Info register: selects the peripheral from wich reading the DREQ.
#define	TI_BURST_LEN_OFF   12
	Transfer Info register: Burst length.
#define	TI_BURST_LEN_MASK   (0xf<<TI_BURST_LEN_OFF)
	Transfer Info register: Burst length.
#define	TI_SRC_IGNORE_OFF   11
	Transfer Info register: Write only zeroes.
#define	TI_SRC_IGNORE_MASK   (1<<TI_SRC_IGNORE_OFF)
	Transfer Info register: Write only zeroes.
#define	TI_SRC_DREQ_OFF   10
	Transfer Info register: Control src reads with dreq.
#define	TI_SRC_DREQ_MASK   (1<<TI_SRC_DREQ_OFF)
	Transfer Info register: Control src reads with dreq.
#define	TI_SRC_WIDTH_OFF   9
	Transfer Info register: source transfer width: 1=128bit 0=32bit.
#define	TI_SRC_WIDTH_MASK   (1<<TI_SRC_WIDTH_OFF)
	Transfer Info register: source transfer width: 1=128bit 0=32bit.
#define	TI_SRC_INC_OFF   8
	Transfer Info register: 1=increment src_addr after each read.
#define	TI_SRC_INC_MASK   (1<<TI_SRC_INC_OFF)
	Transfer Info register: 1=increment src_addr after each read.
#define	TI_DEST_IGNORE_OFF   7
	Transfer Info register: don't write to destination.
#define	TI_DEST_IGNORE_MASK   (1<<TI_DEST_IGNORE_OFF)
	Transfer Info register: don't write to destination.
#define	TI_DEST_DREQ_OFF   6
	Transfer Info register: Control writes with dreq.
#define	TI_DEST_DREQ_MASK   (1<<TI_DEST_DREQ_OFF)
	Transfer Info register: Control writes with dreq.
#define	TI_DEST_WIDTH_OFF   5
	Transfer Info register: destination transfer width: 1=128bit 0=32bit.
#define	TI_DEST_WIDTH_MASK   (1<<TI_DEST_WIDTH_OFF)
	Transfer Info register: destination transfer width: 1=128bit 0=32bit.
#define	TI_DEST_INC_OFF   4
	Transfer Info register: Increment dest address after each write.
#define	TI_DEST_INC_MASK   (1<<TI_DEST_INC_OFF)
	Transfer Info register: Increment dest address after each write.
#define	TI_WAIT_RESP_OFF   3
	Transfer Info register: wait write response.
#define	TI_WAIT_RESP_MASK   (1<<TI_WAIT_RESP_OFF)
	Transfer Info register: wait write response.
#define	TI_2DMODE_OFF   1
	Transfer Info register: 2D stride mode, missing in channels over 6.
#define	TI_2DMODE_MASK   (1<<TI_2DMODE_OFF)
	Transfer Info register: 2D stride mode, missing in channels over 6.
#define	TI_INTEN_OFF   (0)
	Transfer Info register: generate interrupt after the transfer of this block.
#define	TI_INTEN_MASK   (1)
	Transfer Info register: generate interrupt after the transfer of this block.
#define	DREQ_ALWAYS_ON   0
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_DSI   1
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_PCM_TX   2
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_PCM_RX   3
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_SMI   4
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_PWM   5
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_SPI_TX   6
	Transfer Info register: Peripherals ids for the permap field.
#define	DREQ_SPI_RX   7
	Transfer Info register: Peripherals ids for the permap field.
#define	TL_Y_LEN_OFF   16
	Transfer Length register: To be used only in 2D stride mode: y length in bytes.
#define	TL_Y_LEN_MASK   (0x3fff<<TL_Y_LEN_OFF)
	Transfer Length register: To be used only in 2D stride mode: y length in bytes.
#define	TL_X_LEN_OFF   0
	Transfer Length register: To be used only in 2D stride mode: x length in bytes.
#define	TL_X_LEN_MASK   (0xffff)
	Transfer Length register: To be used only in 2D stride mode: x length in bytes.
#define	TL_LEN_OFF   0
	Transfer Length register: To be used only in normal mode (not 2D stride): transfer length in bytes.
#define	TL_LEN_MASK   (0x3fffffff)
	Transfer Length register: To be used only in normal mode (not 2D stride): transfer length in bytes.
#define	REG_2D_STRIDE_DST_STRIDE_OFF   16
	Signed increment to apply to the destination address after each row.
#define	REG_2D_STRIDE_DST_STRIDE_MASK   (0xffff<<REG_2D_STRIDE_DST_STRIDE_OFF)
	Signed increment to apply to the destination address after each row.
#define	REG_2D_STRIDE_SRC_STRIDE_OFF   0
	Signed increment to apply to the source address after each row.
#define	REG_2D_STRIDE_SRC_STRIDE_MASK   (0xffff)
	Signed increment to apply to the source address after each row.

Typedefs
typedef volatile struct ControlBlock_struct	ControlBlock
	Describes a control block, contorl blocks are needed to load the registers of the DMA engine and start a transfer.

Functions
int	dma_init ()
	Initializes the interface, to be called before any other function in this file. More...
int	dma_isInit ()
	Says if dma_init has been called with success. More...
int	dma_channelResetInitDefault (int channel)
	Resets the channel and sets it to default values. More...
int	dma_setControlBlockAddr (int channel, uint32_t controlBlockAddrPhys)
	Sets the address of the control block to be loaded in the dma engine, to start the transfer you then have to set the active bit. More...
int	dma_writeControlBlock (ControlBlock *cb, uintptr_t srcAddrPhys, uintptr_t dstAddrPhys, size_t transferLength, uintptr_t nextControlBlockPhys, uint32_t transferInfo, uint32_t _2DStrideModeInfo, size_t _2DStrideTransferLenX, size_t _2DStrideTransferLenY)
int	dma_allocControlBlockPhys (uintptr_t srcAddrPhys, uintptr_t dstAddrPhys, size_t transferLength, uintptr_t nextControlBlockPhys, uint32_t transferInfo, uint32_t _2DStrideModeInfo, size_t _2DStrideTransferLenX, size_t _2DStrideTransferLenY, Ccmb_desc *area)
	Builds a control block with the specified characteristics. More...
int	dma_dumpRegisters (int channel, char *s)
	For debug purposes: writes the register's contents on the provided string. More...
int	dma_printRegisters (int channel)
	For debug purposes: prints the registers' contents to standard output. More...
int	dma_printControlBlock (ControlBlock *cb)
	For debug purposes: prints the control block's contents on standard output. More...
int	dma_controlBlockToString (ControlBlock *cb, char *s)
	For debug purposes: writes the control block's contents on a string. More...
int	dma_setChannelActive (int channel, int value)
	Sets the channel active bit, this is automatically cleared at the end of each control block chain. More...
int	dma_setChannelGlobalEnable (int channel, int value)
	Set the global enable status for the specified channel. More...
uint32_t	dma_getUsableChannels ()
	Returns a bit mask indicating the usable channels with 1. More...
int	dma_isChannelActive (int channel)
	Gets the channel active bit, this is automatically cleared at the end of each control block chain. More...
int	dma_dumpRegistersDense (int channel, char *s)
	For debug purposes: writes the register's contents on the provided string, in a single line. More...

Detailed Description

Interface to the dma peripheral.

The dma peripheral is able to perform transfers in the memory indipendently from the CPU.
It uses the bus addressing and it's not connected on the same cache level of the CPU, so it's preferable to use the cacheCoherentMemory provider for source and destionation memory areas and also for the Control Blocks.
See the documentation at "BCM2835 ARM Peripherals" page 38

Function Documentation

int dma_allocControlBlockPhys	(	uintptr_t	srcAddrPhys,
		uintptr_t	dstAddrPhys,
		size_t	transferLength,
		uintptr_t	nextControlBlockPhys,
		uint32_t	transferInfo,
		uint32_t	_2DStrideModeInfo,
		size_t	_2DStrideTransferLenX,
		size_t	_2DStrideTransferLenY,
		Ccmb_desc *	area
	)

Builds a control block with the specified characteristics.

Parameters

srcAddrPhys	Source adddress
dstAddrPhys	Destination address
transferLength	Number of bytes to copy
nextControlBlockPhys	The next control block to process
transferInfo	Use the TI_* macros
_2DStrideModeInfo	See bcm2835 datasheet
_2DStrideTransferLenX	See bcm2835 datasheet
_2DStrideTransferLenY	See bcm2835 datasheet
area	The cacheCoherentMemoryProvider descriptor will be returned here, you'll have to free it using ccmp_free(area). You can get the bus and virtual address of the control block from here

Returns

negative in case of error

int dma_channelResetInitDefault

(

int

channel

)

Resets the channel and sets it to default values.

Parameters

channel

The channel

int dma_controlBlockToString	(	ControlBlock *	cb,
		char *	s
	)

For debug purposes: writes the control block's contents on a string.

Parameters

cb	The control block
s	The control block's will be written on this string (300 is an appropriate length)

int dma_dumpRegisters	(	int	channel,
		char *	s
	)

For debug purposes: writes the register's contents on the provided string.

Parameters

channel	The channel
s	The registers' contents will be written on this string (550 is an appropriate length)

int dma_dumpRegistersDense	(	int	channel,
		char *	s
	)

For debug purposes: writes the register's contents on the provided string, in a single line.

Parameters

channel	The channel
s	The registers' contents will be written on this string (550 is an appropriate length)

uint32_t dma_getUsableChannels

(

)

Returns a bit mask indicating the usable channels with 1.

Returns

the bit mask, 0xf0000000 in case of error

int dma_init

(

)

Initializes the interface, to be called before any other function in this file.

Returns

negative in case of error

int dma_isChannelActive

(

int

channel

)

Gets the channel active bit, this is automatically cleared at the end of each control block chain.

Parameters

channel

The channel

Returns

negative in case of error

int dma_isInit

(

)

Says if dma_init has been called with success.

Returns

true if dma_init has been called with success

int dma_printControlBlock

(

ControlBlock *

cb

)

For debug purposes: prints the control block's contents on standard output.

Parameters

cb	The control block

int dma_printRegisters

(

int

channel

)

For debug purposes: prints the registers' contents to standard output.

Parameters

channel

The channel

Returns

negative in case of error

int dma_setChannelActive	(	int	channel,
		int	value
	)

Sets the channel active bit, this is automatically cleared at the end of each control block chain.

Parameters

channel	The affected channel
value	0=disabled; anything else= enabled

Returns

negative in case of error

int dma_setChannelGlobalEnable	(	int	channel,
		int	value
	)

Set the global enable status for the specified channel.

Parameters

channel	The affected channel
value	0=disabled; anything else= enabled

Returns

negative in case of error

int dma_setControlBlockAddr	(	int	channel,
		uint32_t	controlBlockAddrPhys
	)

Sets the address of the control block to be loaded in the dma engine, to start the transfer you then have to set the active bit.

Parameters

channel	The channel
controlBlockAddrPhys	The physical address of the control block

Returns

negative in case of error

int dma_writeControlBlock	(	ControlBlock *	cb,
		uintptr_t	srcAddrPhys,
		uintptr_t	dstAddrPhys,
		size_t	transferLength,
		uintptr_t	nextControlBlockPhys,
		uint32_t	transferInfo,
		uint32_t	_2DStrideModeInfo,
		size_t	_2DStrideTransferLenX,
		size_t	_2DStrideTransferLenY
	)

Writes the provided values to the provided control block

Parameters

cb	The contorl block (virtual) address
srcAddrPhys	Source adddress
dstAddrPhys	Destination address
transferLength	Number of bytes to copy
nextControlBlockPhys	The next control block to process
transferInfo	Use the TI_* macros
_2DStrideModeInfo	See bcm2835 datasheet
_2DStrideTransferLenX	See bcm2835 datasheet
_2DStrideTransferLenY	See bcm2835 datasheet

Returns

Negative in case of error