DMA Controller API

API to use the SH4's DMA Controller More...

Data Structures
struct	dma_config_t
	DMA transfer configuration. More...

Typedefs
typedef void(*	dma_callback_t) (void *data)
	DMA callback type.
typedef uint32_t	dma_addr_t
	DMA address.

Enumerations
enum	dma_channel_t { DMA_CHANNEL_0 , DMA_CHANNEL_1 , DMA_CHANNEL_2 , DMA_CHANNEL_3 }
	DMA channel enum. More...
enum	dma_request_t {   DMA_REQUEST_EXTERNAL_MEM_TO_MEM = 0 , DMA_REQUEST_EXTERNAL_MEM_TO_DEV = 2 , DMA_REQUEST_EXTERNAL_DEV_TO_MEM = 3 , DMA_REQUEST_AUTO_MEM_TO_MEM = 4 ,   DMA_REQUEST_AUTO_MEM_TO_DEV = 5 , DMA_REQUEST_AUTO_DEV_TO_MEM = 6 , DMA_REQUEST_SCI_TRANSMIT = 8 , DMA_REQUEST_SCI_RECEIVE = 9 ,   DMA_REQUEST_SCIF_TRANSMIT = 10 , DMA_REQUEST_SCIF_RECEIVE = 11 , DMA_REQUEST_TMU2_MEM_TO_MEM = 12 , DMA_REQUEST_TMU2_MEM_TO_DEV = 13 ,   DMA_REQUEST_TMU2_DEV_TO_MEM = 14 }
	DMA request. More...
enum	dma_unitsize_t {   DMA_UNITSIZE_64BIT , DMA_UNITSIZE_8BIT , DMA_UNITSIZE_16BIT , DMA_UNITSIZE_32BIT ,   DMA_UNITSIZE_32BYTE }
	DMA unit size. More...
enum	dma_addrmode_t { DMA_ADDRMODE_FIXED , DMA_ADDRMODE_INCREMENT , DMA_ADDRMODE_DECREMENT }
	DMA address mode. More...
enum	dma_transmitmode_t { DMA_TRANSMITMODE_CYCLE_STEAL , DMA_TRANSMITMODE_BURST }
	DMA transmit mode. More...

Functions
dma_addr_t	hw_to_dma_addr (uintptr_t hw_addr)
	Convert a hardware address to a DMA address.
dma_addr_t	dma_map_src (const void *ptr, size_t len)
	Prepare a source memory buffer for a DMA transfer.
dma_addr_t	dma_map_dst (void *ptr, size_t len)
	Prepare a destination memory buffer for a DMA transfer.
int	dma_transfer (const dma_config_t *cfg, dma_addr_t dst, dma_addr_t src, size_t len, void *cb_data)
	Program a DMA transfer.
void	dma_wait_complete (dma_channel_t channel)
	Wait for a DMA transfer to complete.
size_t	dma_transfer_get_remaining (dma_channel_t channel)
	Get the remaining size of a DMA transfer.

Detailed Description

API to use the SH4's DMA Controller

This API can be used to program DMA transfers from memory to memory, from hardware to memory or from memory to hardware.

Typedef Documentation

dma_addr_t

typedef uint32_t dma_addr_t

DMA address.

This type represents an address that can be used for DMA transfers.

dma_callback_t

typedef void(* dma_callback_t) (void *data)

DMA callback type.

Function type for DMA callbacks. Those registered callbacks will be called when a DMA transfer completes. They will be called in an interrupt context, so don't try anything funny.

Enumeration Type Documentation

dma_addrmode_t

enum dma_addrmode_t

DMA address mode.

The "address mode" specifies how the source or destination address of a DMA transfer is modified as the transfer goes on. It is only valid when the DMA transfer is configured as pointing to memory for that source or destination.

Enumerator
DMA_ADDRMODE_FIXED	The source/destination address is not modified.
DMA_ADDRMODE_INCREMENT	The source/destination address is incremented.
DMA_ADDRMODE_DECREMENT	The source/destination address is decremented.

dma_channel_t

enum dma_channel_t

DMA channel enum.

Represents one of the 4 DMA channels available on the SH4.

Enumerator
DMA_CHANNEL_0	Channel #0: On Dreamcast, reserved for hardware.
DMA_CHANNEL_1	Channel #1: External, hardware or mem-to-mem requests.
DMA_CHANNEL_2	Channel #2: on Dreamcast, reserved for PVR use.
DMA_CHANNEL_3	Channel #3: mem-to-mem requests only.

dma_request_t

enum dma_request_t

DMA request.

List of the possible DMA requests.

"Auto" requests are started as soon as the DMA transfer is programmed to the DMA controller. On the other hand, SCI/SCIF/TMU2 requests are only started when the given hardware event occurs.

"External" requests are controlled by external pins of the SH4 CPU. These can be wired to other parts of the mother board.

Enumerator
DMA_REQUEST_EXTERNAL_MEM_TO_MEM
DMA_REQUEST_EXTERNAL_MEM_TO_DEV
DMA_REQUEST_EXTERNAL_DEV_TO_MEM
DMA_REQUEST_AUTO_MEM_TO_MEM
DMA_REQUEST_AUTO_MEM_TO_DEV
DMA_REQUEST_AUTO_DEV_TO_MEM
DMA_REQUEST_SCI_TRANSMIT
DMA_REQUEST_SCI_RECEIVE
DMA_REQUEST_SCIF_TRANSMIT
DMA_REQUEST_SCIF_RECEIVE
DMA_REQUEST_TMU2_MEM_TO_MEM
DMA_REQUEST_TMU2_MEM_TO_DEV
DMA_REQUEST_TMU2_DEV_TO_MEM

dma_transmitmode_t

enum dma_transmitmode_t

DMA transmit mode.

In "Cycle steal" mode, the DMA controller will release the bus at the end of each transfer unit (configured by the unit size). This allows the CPU to access the bus if it needs to.

In "Burst" mode, the DMA controller will hold the bus until the DMA transfer completes.

Enumerator
DMA_TRANSMITMODE_CYCLE_STEAL
DMA_TRANSMITMODE_BURST

dma_unitsize_t

enum dma_unitsize_t

DMA unit size.

The unit size controls the granularity at which the DMA will transfer data. For instance, copying data to a 16-bit bus will require a 16-bit unit size.

For memory-to-memory transfers, it is recommended to use 32-byte transfers for the maximum speed.

Enumerator
DMA_UNITSIZE_64BIT
DMA_UNITSIZE_8BIT
DMA_UNITSIZE_16BIT
DMA_UNITSIZE_32BIT
DMA_UNITSIZE_32BYTE

Function Documentation

dma_map_dst()

dma_addr_t dma_map_dst	(	void *	ptr,
		size_t	len )

Prepare a destination memory buffer for a DMA transfer.

This function will invalidate the data cache for the memory area covered by the buffer to ensure memory coherency, and return an address suitable for use with the DMA controller.

Parameters

ptr	A pointer to the destination buffer.
len	The size in bytes of the destination buffer.

Returns

The converted DMA address.

See also

dma_map_src()

dma_map_src()

dma_addr_t dma_map_src	(	const void *	ptr,
		size_t	len )

Prepare a source memory buffer for a DMA transfer.

This function will flush the data cache for the memory area covered by the buffer to ensure memory coherency, and return an address suitable for use with the DMA controller.

Parameters

ptr	A pointer to the source buffer.
len	The size in bytes of the source buffer.

Returns

The converted DMA address.

See also

dma_map_dst()

dma_transfer()

int dma_transfer	(	const dma_config_t *	cfg,
		dma_addr_t	dst,
		dma_addr_t	src,
		size_t	len,
		void *	cb_data )

Program a DMA transfer.

This function will program a DMA transfer using the specified configuration, source/destination addresses and transfer length.

It will return as soon as the DMA transfer is programmed, which means that it will not work for the DMA transfer to complete before returning.

Parameters

cfg	A pointer to the configuration structure.
dst	The destination address, if targetting memory; can be 0 otherwise.
src	The source address, if targetting memory; can be 0 otherwise.
len	The size in bytes of the DMA transfer.
cb_data	The parameter that will be passed to the end-of-transfer callback, if a callback has been specified in the configuration structure.

Return values

0	On success.
-1	On error.

See also

dma_wait_complete()

dma_transfer_get_remaining()

size_t dma_transfer_get_remaining

(

dma_channel_t

channel

)

Get the remaining size of a DMA transfer.

This function will return the number of bytes remaining to transfer, if a transfer was previously programmed.

Parameters

channel

The DMA channel to wait for.

Returns

The number of bytes remaining to transfer, or zero if the previous transfer completed.

dma_wait_complete()

void dma_wait_complete

(

dma_channel_t

channel

)

Wait for a DMA transfer to complete.

This function will block until any previously programmed DMA transfer for the given DMA channel has completed.

Parameters

channel

The DMA channel to wait for.

hw_to_dma_addr()

dma_addr_t hw_to_dma_addr

(

uintptr_t

hw_addr

)

Convert a hardware address to a DMA address.

This function will convert a hardware address (pointing to a device's FIFO, or to one of the various mapped memories) to an address suitable for use with the DMA controller.

Parameters

hw_addr

The hardware address.

Returns

The converted DMA address.