dma.h File Reference

#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/system.h"
#include "ultibo/devices.h"

Go to the source code of this file.

Data Structures
struct	_DMA_PROPERTIES
struct	_DMA_HOST
struct	_DMA_REQUEST

Macros
#define	DMA_NAME_PREFIX   "DMA"
	Name prefix for DMA Hosts.
#define	DMA_TYPE_NONE   0
#define	DMA_STATE_DISABLED   0
#define	DMA_STATE_ENABLED   1
#define	DMA_FLAG_NONE   0x00000000
#define	DMA_FLAG_SHARED   0x00000001
	Host requires data buffers in shared memory.
#define	DMA_FLAG_NOCACHE   0x00000002
	Host requires data buffers in non cached memory.
#define	DMA_FLAG_COHERENT   0x00000004
	Data buffers are cache coherent if allocated according to host configuration.
#define	DMA_FLAG_STRIDE   0x00000008
	Host supports 2D stride on source and/or dest address.
#define	DMA_FLAG_DREQ   0x00000010
	Host supports data request gating (DREQ) on source and/or dest address.
#define	DMA_FLAG_NOINCREMENT   0x00000020
	Host supports no increment on source and/or dest address.
#define	DMA_FLAG_NOREAD   0x00000040
	Host supports no read from source address (write to dest address only) (Zero fill the destination).
#define	DMA_FLAG_NOWRITE   0x00000080
	Host supports no write to dest address (read from source address only) (Cache fill from the source).
#define	DMA_FLAG_WIDE   0x00000100
	Host supports wide read and/or write.
#define	DMA_FLAG_BULK   0x00000200
	Host supports bulk transfer.
#define	DMA_FLAG_LITE   0x00000400
	Host supports "lite" transfer.
#define	DMA_FLAG_40BIT   0x00000800
	Host supports 40-bit address transfer.
#define	DMA_REQUEST_FLAG_NONE   0x00000000
#define	DMA_REQUEST_FLAG_RELEASE   0x00000001
	If set then release the request automatically after completion.
#define	DMA_REQUEST_FLAG_CYCLIC   0x00000002
	This is a cyclic request which loops around from tail to head.
#define	DMA_REQUEST_FLAG_COMPATIBLE   0x00000004
	If set then all buffers supplied are host configuration compatible (Sizing, Alignment, Flags).

Typedefs
typedef struct _DMA_PROPERTIES	DMA_PROPERTIES
typedef struct _DMA_HOST	DMA_HOST
typedef struct _DMA_REQUEST	DMA_REQUEST
	Forward declared to satisfy DMAHost.
typedef uint32_t STDCALL(*	dma_enumerate_cb) (DMA_HOST *dma, void *data)
typedef uint32_t STDCALL(*	dma_notification_cb) (DEVICE *device, void *data, uint32_t notification)
typedef uint32_t STDCALL(*	dma_host_start_proc) (DMA_HOST *dma)
typedef uint32_t STDCALL(*	dma_host_stop_proc) (DMA_HOST *dma)
typedef uint32_t STDCALL(*	dma_host_reset_proc) (DMA_HOST *dma)
typedef uint32_t STDCALL(*	dma_host_submit_proc) (DMA_HOST *dma, DMA_REQUEST *request)
typedef uint32_t STDCALL(*	dma_host_cancel_proc) (DMA_HOST *dma, DMA_REQUEST *request)
typedef uint32_t STDCALL(*	dma_host_properties_proc) (DMA_HOST *dma, DMA_PROPERTIES *properties)
typedef void STDCALL(*	dma_request_completed_cb) (DMA_REQUEST *request)

Functions
uint32_t STDCALL	dma_host_start (DMA_HOST *dma)
uint32_t STDCALL	dma_host_stop (DMA_HOST *dma)
uint32_t STDCALL	dma_host_reset (DMA_HOST *dma)
uint32_t STDCALL	dma_host_properties (DMA_HOST *dma, DMA_PROPERTIES *properties)
DMA_HOST *STDCALL	dma_host_create (void)
	Create a new DMA entry.
DMA_HOST *STDCALL	dma_host_create_ex (uint32_t size)
	Create a new DMA entry.
uint32_t STDCALL	dma_host_destroy (DMA_HOST *dma)
	Destroy an existing DMA entry.
uint32_t STDCALL	dma_host_register (DMA_HOST *dma)
	Register a new DMA in the DMA host table.
uint32_t STDCALL	dma_host_deregister (DMA_HOST *dma)
	Deregister a DMA from the DMA host table.
DMA_HOST *STDCALL	dma_host_find (uint32_t dmaid)
uint32_t STDCALL	dma_host_enumerate (dma_enumerate_cb callback, void *data)
uint32_t STDCALL	dma_host_notification (DMA_HOST *dma, dma_notification_cb callback, void *data, uint32_t notification, uint32_t flags)
uint32_t STDCALL	dma_data_count (DMA_DATA *data)
	Return the total number of data blocks in the linked list.
uint32_t STDCALL	dma_data_flags (DMA_DATA *data)
	Return the combined flags of the data blocks in the linked list.
uint32_t STDCALL	dma_data_maximum (DMA_DATA *data)
	Return the size of the largest data block in the linked list.
void *STDCALL	dma_buffer_allocate (DMA_HOST *dma, uint32_t size)
	Allocate a data buffer for a DMA request.
void *STDCALL	dma_buffer_allocate_ex (DMA_HOST *dma, uint32_t *size)
	Allocate a data buffer for a DMA request.
uint32_t STDCALL	dma_buffer_validate (DMA_HOST *dma, void *buffer, uint32_t size)
	Validate a data buffer for a DMA request against the DMA host requirements.
uint32_t STDCALL	dma_buffer_release (void *buffer)
	Release a data buffer from a DMA request.
DMA_REQUEST *STDCALL	dma_request_allocate (DMA_HOST *dma, DMA_DATA *data, dma_request_completed_cb callback, void *driverdata, uint32_t direction, uint32_t peripheral, uint32_t flags)
	Allocate a new DMA request.
uint32_t STDCALL	dma_request_release (DMA_REQUEST *request)
	Release and destroy a DMA request.
uint32_t STDCALL	dma_request_submit (DMA_REQUEST *request)
	Submit a DMA request to a DMA host.
uint32_t STDCALL	dma_request_cancel (DMA_REQUEST *request)
	Cancel a DMA request previously submitted to a DMA host.
void STDCALL	dma_request_complete (DMA_REQUEST *request)
	Called by a DMA host when a DMA request completes.
uint32_t STDCALL	dma_transfer_request (DMA_HOST *dma, DMA_DATA *data, uint32_t direction, uint32_t peripheral, uint32_t flags, uint32_t timeout)
	Perform a DMA transfer request with the supplied data blocks on the supplied host.
uint32_t STDCALL	dma_transfer_request_ex (DMA_HOST *dma, DMA_DATA *data, dma_request_completed_cb callback, void *driverdata, uint32_t direction, uint32_t peripheral, uint32_t flags)
	Perform a DMA transfer request with the supplied data blocks on the supplied host.
void STDCALL	dma_transfer_request_complete (DMA_REQUEST *request)
	Called when a DMA transfer request completes.
uint32_t STDCALL	dma_get_count (void)
	Get the current DMA host count.
DMA_HOST *STDCALL	dma_host_get_default (void)
	Get the current default DMA host.
uint32_t STDCALL	dma_host_set_default (DMA_HOST *dma)
	Set the current default DMA device.
DMA_HOST *STDCALL	dma_host_check (DMA_HOST *dma)
	Check if the supplied DMA is in the DMA host table.
uint32_t STDCALL	dma_type_to_string (uint32_t dmatype, char *string, uint32_t len)
	Convert a DMA type value to a string.
uint32_t STDCALL	dma_state_to_string (uint32_t dmastate, char *string, uint32_t len)
	Convert a DMA state value to a string.

Macro Definition Documentation

DMA_NAME_PREFIX

#define DMA_NAME_PREFIX   "DMA"

Name prefix for DMA Hosts.

DMA specific constants

DMA_TYPE_NONE

#define DMA_TYPE_NONE   0

DMA Host Types

DMA_STATE_DISABLED

#define DMA_STATE_DISABLED   0

DMA Host States

DMA_STATE_ENABLED

#define DMA_STATE_ENABLED   1

DMA_FLAG_NONE

#define DMA_FLAG_NONE   0x00000000

DMA Host Flags

DMA_FLAG_SHARED

#define DMA_FLAG_SHARED   0x00000001

Host requires data buffers in shared memory.

DMA_FLAG_NOCACHE

#define DMA_FLAG_NOCACHE   0x00000002

Host requires data buffers in non cached memory.

DMA_FLAG_COHERENT

#define DMA_FLAG_COHERENT   0x00000004

Data buffers are cache coherent if allocated according to host configuration.

DMA_FLAG_STRIDE

#define DMA_FLAG_STRIDE   0x00000008

Host supports 2D stride on source and/or dest address.

DMA_FLAG_DREQ

#define DMA_FLAG_DREQ   0x00000010

Host supports data request gating (DREQ) on source and/or dest address.

DMA_FLAG_NOINCREMENT

#define DMA_FLAG_NOINCREMENT   0x00000020

Host supports no increment on source and/or dest address.

DMA_FLAG_NOREAD

#define DMA_FLAG_NOREAD   0x00000040

Host supports no read from source address (write to dest address only) (Zero fill the destination).

DMA_FLAG_NOWRITE

#define DMA_FLAG_NOWRITE   0x00000080

Host supports no write to dest address (read from source address only) (Cache fill from the source).

DMA_FLAG_WIDE

#define DMA_FLAG_WIDE   0x00000100

Host supports wide read and/or write.

DMA_FLAG_BULK

#define DMA_FLAG_BULK   0x00000200

Host supports bulk transfer.

DMA_FLAG_LITE

#define DMA_FLAG_LITE   0x00000400

Host supports "lite" transfer.

DMA_FLAG_40BIT

#define DMA_FLAG_40BIT   0x00000800

Host supports 40-bit address transfer.

DMA_REQUEST_FLAG_NONE

#define DMA_REQUEST_FLAG_NONE   0x00000000

DMA Data Flags See: Platform DMA_DATA_FLAG_* DMA Request Flags

DMA_REQUEST_FLAG_RELEASE

#define DMA_REQUEST_FLAG_RELEASE   0x00000001

If set then release the request automatically after completion.

DMA_REQUEST_FLAG_CYCLIC

#define DMA_REQUEST_FLAG_CYCLIC   0x00000002

This is a cyclic request which loops around from tail to head.

DMA_REQUEST_FLAG_COMPATIBLE

#define DMA_REQUEST_FLAG_COMPATIBLE   0x00000004

If set then all buffers supplied are host configuration compatible (Sizing, Alignment, Flags).

Typedef Documentation

DMA_PROPERTIES

typedef struct _DMA_PROPERTIES DMA_PROPERTIES

DMA specific types DMA Properties

DMA_HOST

typedef struct _DMA_HOST DMA_HOST

DMA Host

DMA_REQUEST

typedef struct _DMA_REQUEST DMA_REQUEST

Forward declared to satisfy DMAHost.

dma_enumerate_cb

typedef uint32_t STDCALL(* dma_enumerate_cb) (DMA_HOST *dma, void *data)

DMA Enumeration Callback

dma_notification_cb

typedef uint32_t STDCALL(* dma_notification_cb) (DEVICE *device, void *data, uint32_t notification)

DMA Notification Callback

dma_host_start_proc

typedef uint32_t STDCALL(* dma_host_start_proc) (DMA_HOST *dma)

DMA Host Methods

dma_host_stop_proc

typedef uint32_t STDCALL(* dma_host_stop_proc) (DMA_HOST *dma)

dma_host_reset_proc

typedef uint32_t STDCALL(* dma_host_reset_proc) (DMA_HOST *dma)

dma_host_submit_proc

typedef uint32_t STDCALL(* dma_host_submit_proc) (DMA_HOST *dma, DMA_REQUEST *request)

dma_host_cancel_proc

typedef uint32_t STDCALL(* dma_host_cancel_proc) (DMA_HOST *dma, DMA_REQUEST *request)

dma_host_properties_proc

typedef uint32_t STDCALL(* dma_host_properties_proc) (DMA_HOST *dma, DMA_PROPERTIES *properties)

dma_request_completed_cb

typedef void STDCALL(* dma_request_completed_cb) (DMA_REQUEST *request)

DMA Request DMA Request Methods

Function Documentation

dma_host_start()

uint32_t STDCALL dma_host_start

(

DMA_HOST *

dma

)

DMA Host Functions

dma_host_stop()

uint32_t STDCALL dma_host_stop

(

DMA_HOST *

dma

)

dma_host_reset()

uint32_t STDCALL dma_host_reset

(

DMA_HOST *

dma

)

dma_host_properties()

uint32_t STDCALL dma_host_properties	(	DMA_HOST *	dma,
		DMA_PROPERTIES *	properties )

dma_host_create()

DMA_HOST *STDCALL dma_host_create

(

void

)

Create a new DMA entry.

Returns

Pointer to new DMA entry or nil if DMA could not be created

dma_host_create_ex()

DMA_HOST *STDCALL dma_host_create_ex

(

uint32_t

size

)

Create a new DMA entry.

Parameters

Size	Size in bytes to allocate for new DMA (Including the DMA entry)

Returns

Pointer to new DMA entry or nil if DMA could not be created

dma_host_destroy()

uint32_t STDCALL dma_host_destroy

(

DMA_HOST *

dma

)

Destroy an existing DMA entry.

dma_host_register()

uint32_t STDCALL dma_host_register

(

DMA_HOST *

dma

)

Register a new DMA in the DMA host table.

dma_host_deregister()

uint32_t STDCALL dma_host_deregister

(

DMA_HOST *

dma

)

Deregister a DMA from the DMA host table.

dma_host_find()

DMA_HOST *STDCALL dma_host_find

(

uint32_t

dmaid

)

dma_host_enumerate()

uint32_t STDCALL dma_host_enumerate	(	dma_enumerate_cb	callback,
		void *	data )

dma_host_notification()

uint32_t STDCALL dma_host_notification	(	DMA_HOST *	dma,
		dma_notification_cb	callback,
		void *	data,
		uint32_t	notification,
		uint32_t	flags )

dma_data_count()

uint32_t STDCALL dma_data_count

(

DMA_DATA *

data

)

Return the total number of data blocks in the linked list.

DMA Data Functions

dma_data_flags()

uint32_t STDCALL dma_data_flags

(

DMA_DATA *

data

)

Return the combined flags of the data blocks in the linked list.

dma_data_maximum()

uint32_t STDCALL dma_data_maximum

(

DMA_DATA *

data

)

Return the size of the largest data block in the linked list.

dma_buffer_allocate()

void *STDCALL dma_buffer_allocate	(	DMA_HOST *	dma,
		uint32_t	size )

Allocate a data buffer for a DMA request.

DMA Buffer Functions

Parameters

DMA	The DMA host that the request will be sent to
Size	The size of the data buffer to allocate

Returns

The newly allocated buffer or nil on failure

dma_buffer_allocate_ex()

void *STDCALL dma_buffer_allocate_ex	(	DMA_HOST *	dma,
		uint32_t *	size )

Allocate a data buffer for a DMA request.

Parameters

DMA	The DMA host that the request will be sent to
Size	The size of the data buffer to allocate (Updated on return to actual size)

Returns

The newly allocated buffer or nil on failure

Note

This differs from DMABufferAllocate in that it updates the size value to reflect the actual size of the buffer allocated which may be required for some uses

dma_buffer_validate()

uint32_t STDCALL dma_buffer_validate	(	DMA_HOST *	dma,
		void *	buffer,
		uint32_t	size )

Validate a data buffer for a DMA request against the DMA host requirements.

Parameters

DMA	The DMA host that the request will be sent to
Buffer	The data buffer to validate
Size	The size of the data buffer

Returns

ERROR_SUCCESS on success or another error code on failure (ERROR_NOT_COMPATIBLE if not compatible with host)

Note

Does not check for cache coherency requirements (Shared, Non Cached) only alignment and size. Buffers used as the source of a DMA request do not necessarily need to meet alignment and size requirements, however buffers used as a destination must meet these requirements or the caller must take appropriate actions to prevent undesirable side effects from cache invalidation.

dma_buffer_release()

uint32_t STDCALL dma_buffer_release

(

void *

buffer

)

Release a data buffer from a DMA request.

Parameters

Data	The buffer to be released

Returns

ERROR_SUCCESS on success or another error code on failure

dma_request_allocate()

DMA_REQUEST *STDCALL dma_request_allocate	(	DMA_HOST *	dma,
		DMA_DATA *	data,
		dma_request_completed_cb	callback,
		void *	driverdata,
		uint32_t	direction,
		uint32_t	peripheral,
		uint32_t	flags )

Allocate a new DMA request.

DMA Request Functions

Parameters

DMA	The DMA host this request will be sent to
Data	A linked list of DMA data blocks for the transfer (Optional)
Callback	The callback function to be called on completion of the request
DriverData	Driver private data for the callback (Optional)
Direction	The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
Peripheral	The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
Flags	Additional flags for this request (eg DMA_REQUEST_FLAG_CYCLIC)

Returns

The newly allocated request or nil on failure

dma_request_release()

uint32_t STDCALL dma_request_release

(

DMA_REQUEST *

request

)

Release and destroy a DMA request.

Parameters

Request

The request to be released

Returns

ERROR_SUCCESS on success or another error code on failure

dma_request_submit()

uint32_t STDCALL dma_request_submit

(

DMA_REQUEST *

request

)

Submit a DMA request to a DMA host.

Parameters

Request

The request to be submitted

Returns

ERROR_SUCCESS if completed or another error code on failure

Note

The request will be completed asynchronously by the DMA host and the completion callback will be called when the request has either succeeded or failed

dma_request_cancel()

uint32_t STDCALL dma_request_cancel

(

DMA_REQUEST *

request

)

Cancel a DMA request previously submitted to a DMA host.

Parameters

Request

The request to be cancelled

Returns

ERROR_SUCCESS if completed or another error code on failure

dma_request_complete()

void STDCALL dma_request_complete

(

DMA_REQUEST *

request

)

Called by a DMA host when a DMA request completes.

Parameters

Request

The DMA request which has completed

Note

DMA host drivers may call this on a worker thread

dma_transfer_request()

uint32_t STDCALL dma_transfer_request	(	DMA_HOST *	dma,
		DMA_DATA *	data,
		uint32_t	direction,
		uint32_t	peripheral,
		uint32_t	flags,
		uint32_t	timeout )

Perform a DMA transfer request with the supplied data blocks on the supplied host.

DMA Transfer Functions

Parameters

DMA	The DMA host to execute the request on
Data	A linked list of DMA data blocks for the transfer
Direction	The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
Peripheral	The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
Flags	Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)
Timeout	Milliseconds to wait for request to complete (INFINITE to wait forever)

Note

An internal callback will be specified and the function will wait for the transfer to complete

dma_transfer_request_ex()

uint32_t STDCALL dma_transfer_request_ex	(	DMA_HOST *	dma,
		DMA_DATA *	data,
		dma_request_completed_cb	callback,
		void *	driverdata,
		uint32_t	direction,
		uint32_t	peripheral,
		uint32_t	flags )

Perform a DMA transfer request with the supplied data blocks on the supplied host.

Parameters

DMA	The DMA host to execute the request on
Data	A linked list of DMA data blocks for the transfer
Callback	The callback function to be called on completion of the request
DriverData	Driver private data for the callback (Optional)
Direction	The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
Peripheral	The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
Flags	Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)

Note

The request will be passed to the callback with the DriverData field set to the DriverData passed to this function. On completion of the callback the request will automatically be released by the internal callback handler

dma_transfer_request_complete()

void STDCALL dma_transfer_request_complete

(

DMA_REQUEST *

request

)

Called when a DMA transfer request completes.

Parameters

Request

The DMA request which has completed

Note

This is the internal callback for DMATransferRequest

dma_get_count()

uint32_t STDCALL dma_get_count

(

void

)

Get the current DMA host count.

DMA Helper Functions

dma_host_get_default()

DMA_HOST *STDCALL dma_host_get_default

(

void

)

Get the current default DMA host.

dma_host_set_default()

uint32_t STDCALL dma_host_set_default

(

DMA_HOST *

dma

)

Set the current default DMA device.

dma_host_check()

DMA_HOST *STDCALL dma_host_check

(

DMA_HOST *

dma

)

Check if the supplied DMA is in the DMA host table.

dma_type_to_string()

uint32_t STDCALL dma_type_to_string	(	uint32_t	dmatype,
		char *	string,
		uint32_t	len )

Convert a DMA type value to a string.

dma_state_to_string()

uint32_t STDCALL dma_state_to_string	(	uint32_t	dmastate,
		char *	string,
		uint32_t	len )

Convert a DMA state value to a string.