SDMA Manager

Data Structures
struct	SDMA_transferState
	State structure shared between SDMAK and SDMA user layers. More...
union	SDMA_requestDmaParams
	SDMAK ioctl input/output parameters. More...
struct	SDMA_ChannelDescriptor
	Descriptor for a channel granted with a SDMA_IOCREQUESTDMA ioctl(). More...
Defines
#define	SDMA_VERSION   0x01010000U
#define	SDMA_IOCMAGIC   0x0000fb00
	SDMAK ioctl() commands.
#define	SDMA_IOCCMDMASK   0x000000ff
#define	SDMA_IOCREQUESTDMA   1
#define	SDMA_IOCRELEASEDMA   2
#define	SDMA_IOCWAITFORCOMPLETION   3
#define	SDMA_IOCGETVERSION   4
Typedefs
typedef struct SDMA_ChannelDescriptor	SDMA_ChannelDescriptor
	Descriptor for a channel granted with a SDMA_IOCREQUESTDMA ioctl().
typedef enum SDMA_Status	SDMA_Status
	Status codes for SDMA API return values.
Enumerations
enum	SDMA_Status {   SDMA_OK = 0,   SDMA_EFAIL,   SDMA_ENOCHANNEL,   SDMA_ENOINIT }
	Status codes for SDMA API return values. More...
Functions
int	SDMA_init (void)
	SDMA initialization API.
int	SDMA_exit (void)
	SDMA finalization API.
SDMA_Status	SDMA_getChannels (int numChannels, SDMA_ChannelDescriptor chanArray[])
	Returns available logical channels.
SDMA_Status	SDMA_freeChannels (int numChannels, SDMA_ChannelDescriptor chanArray[])
	Frees previously requested logical channels.
SDMA_Status	SDMA_wait (SDMA_ChannelDescriptor *channel)
	Waits for the transfer corresponding to this descriptor to complete.
SDMA_Status	SDMA_check (SDMA_ChannelDescriptor *channel, int *pcompleted)
	Checks the status of the transfer corresponding to this descriptor and returns it in the *pcompleted field.
int	SDMA_getVersion (void)
	Retrieve version from SDMA driver.

---

Detailed Description

This is the API for the SDMA Manager.

---

Define Documentation

#define SDMA_VERSION   0x01010000U

#define SDMA_IOCMAGIC   0x0000fb00

SDMAK ioctl() commands.

#define SDMA_IOCCMDMASK   0x000000ff

#define SDMA_IOCREQUESTDMA   1

#define SDMA_IOCRELEASEDMA   2

#define SDMA_IOCWAITFORCOMPLETION   3

#define SDMA_IOCGETVERSION   4

---

Typedef Documentation

typedef struct SDMA_ChannelDescriptor SDMA_ChannelDescriptor

Descriptor for a channel granted with a SDMA_IOCREQUESTDMA ioctl().

Remarks:

The address of the transferState member is passed down to the SDMAK module during the SDMA_IOCREQUESTDMA ioctl(). The SDMAK module maps this address and queries and writes to it during the completion ISR activity. It is therefore vital that the address of the descriptor passed to SDMA_getChannels() is in persistent memory that is live for the duration of SDMA channel usage.

See also:

SDMA_getChannels()

SDMA_freeChannels()

SDMA_wait()

SDMA_check()

typedef enum SDMA_Status SDMA_Status

Status codes for SDMA API return values.

---

Enumeration Type Documentation

enum SDMA_Status

Status codes for SDMA API return values.

Enumerator:

SDMA_OK	OK
SDMA_EFAIL	general failure
SDMA_ENOCHANNEL	no channels available
SDMA_ENOINIT	SDMA_init() not called

---

Function Documentation

int SDMA_init

(

void

)

SDMA initialization API.

int SDMA_exit

(

void

)

SDMA finalization API.

SDMA_Status SDMA_getChannels	(	int	numChannels,
		SDMA_ChannelDescriptor	chanArray[]
	)

Returns available logical channels.

Parameters:

numChannels	number of requested channels.
chanArray	pointer to SDMA_ChannelDescriptor storage of sufficient size to hold numChannels descriptors. All structure array fields are filled by this API (in other words, no fields need to be filled by the caller prior to the call).

Remarks:

chanArray must be allocated from memory that persists over the life of the channel's usage, since the address of the chanArray will be used by the SDMA kernel driver. This implies that the contents of the passed chanArray should not be copied to another SDMA_ChannelDescriptor that is then used for the subsequent operations.

Fails if the requested number of channels is not available.

See also:

SDMA_freeChannels()

SDMA_Status SDMA_freeChannels	(	int	numChannels,
		SDMA_ChannelDescriptor	chanArray[]
	)

Frees previously requested logical channels.

Parameters:

numChannels	number of requested channels.
chanArray	pointer to SDMA_ChannelDescriptor storage of sufficient size to hold numChannels descriptors. This will typically be the same pointer passed to SDMA_getChannels().

See also:

SDMA_getChannels()

SDMA_Status SDMA_wait

(

SDMA_ChannelDescriptor *

channel )

Waits for the transfer corresponding to this descriptor to complete.

Parameters:

channel

pointer to the single channel for which to wait.

Remarks:

SDMA_wait() first checks the transferComplete flag of the struct SDMA_transferState in channel. This flag is directly written by the SDMAK module's completion ISR. If this flag is not set to 1, SDMA_wait() will issue a SDMA_IOCWAITFORCOMPLETION ioctl(), which will block inside the SDMAK module and become unblocked by the completion ISR.

See also:

SDMA_check()

SDMA_Status SDMA_check	(	SDMA_ChannelDescriptor *	channel,
		int *	pcompleted
	)

Checks the status of the transfer corresponding to this descriptor and returns it in the *pcompleted field.

Parameters:

channel	pointer to single channel to check.
pcompleted	pointer to completion status.

Remarks:

copies the contents of the transferComplete flag of the struct SDMA_transferState in channel into *pcompleted (does not issue any ioctl()).

See also:

SDMA_wait()

int SDMA_getVersion

(

void

)

Retrieve version from SDMA driver.

Returns:

Installed SDMA driver's version number.

Precondition:

Must have called SDMA_init()