DMAN3

Functions
Int	DMAN3_grantDmaChannels (Int groupId, IALG_Handle algHandle[], IDMA3_Fxns *dmaFxns[], Int numAlgs)
	Add one or several algorithms to the DMA Manager. The DMA Manager will grant DMA resources to the algorithms as a result. This function is called when initializing XDAIS algorithm instances.
Void	DMAN3_exit (Void)
	Finalization method of the DMAN module.
Int	DMAN3_createChannels (Int groupId, IDMA3_ChannelRec dmaTab[], Int numChans)
	Allocate and initialize memory for one or several channel handles.
Void	DMAN3_init (Void)
	Initialization method of the DMAN3 module. DMAN3_init() uses externally configured and provided DMAN3_PARAMS to initialize DMAN3 resources (QDMA channel map, memory heap...)
Int	DMAN3_releaseDmaChannels (IALG_Handle algHandle[], IDMA3_Fxns *dmaFxns[], Int numAlgs)
	Remove logical channel resources from one or several algorithm instances.
Int	DMAN3_freeChannels (IDMA3_Handle channelTab[], Int numChans)
	Free memory for array of channel handles.
Defines
#define	DMAN3_MODNAME   "ti.sdo.fc.dman3"
	Name to pass to Diags_setMask() to enable logging for DMAN3 functions. For example, Diags_setMask(DMAN3_MODNAME"+EX1234567"); turns on all Log statements in this module. Diags_setMask() must be called after initialization to take effect.
#define	DMAN3_GTNAME   "ti.sdo.fc.dman3"
#define	DMAN3_MAXGROUPS   20
Data Structures
struct	DMAN3_Params
	The module configuration structure for DMAN3 implementation. It is set at design time by the system integrator to ensure optimal sharing of DMA resources for the execution environment. More...
Typedefs
typedef Bool(*	DMAN3_ScratchAllocFxn )(IALG_Handle alg, Int mutexId, IALG_MemRec *memTab, Int numRecs)
	Function prototype for allocating IDMA3 Object's env from shared scratch memory. Algorithms might specify a particular IDMA3 protocol that provides custom DMA services. This protocol might require extra memory for the IDMA3 object's environment. DMAN3_ScratchAllocFxn might be used to allocate this memory. If this is NULL, then the env will be allocated from persistent memory.
typedef Void(*	DMAN3_ScratchFreeFxn )(Int mutexId, Void *addr, Uns size)
	Function prototype for freeing IDMA3 Object's env from shared scratch memory. If this is NULL then env will be freed from persistent memory.
typedef struct DMAN3_Params	DMAN3_Params
	The module configuration structure for DMAN3 implementation. It is set at design time by the system integrator to ensure optimal sharing of DMA resources for the execution environment.
Variables
DMAN3_Params	DMAN3_PARAMS
	Default module configuration structure (defined in dman3.c).
Uns	ti_sdo_fc_dman3_DMAN3_numQdmaGroup [20+1]
	Array containing the number of Qdma channels that will be assigned to the algorithm groups for sharing.
Bool	ti_sdo_fc_dman3_DMAN3_useCustomDma
	Flag indicating if custom DMA library is being used.
Defines: DMAN3 Status Codes
#define	DMAN3_SOK   0
#define	DMAN3_EOUTOFMEMORY   -1
#define	DMAN3_EFAIL   -2
#define	DMAN3_EFREE   -3
#define	DMAN3_EOUTOFTCCS   -4
#define	DMAN3_EOUTOFPARAMS   -5
#define	DMAN3_ETCCCONFIG   -6
#define	DMAN3_EPARAMCONFIG   -7

---

Detailed Description

DMAN3 is an application interface to the 3rd generation DMA Manager. It provides routines for granting and reclaiming DMA resources used by algorithms or other non-algorithm users. This module is used by frameworks or applications which have XDAIS algorithms that implement the IDMA3 interface.

Remarks:

For additional information, please refer to the "C64+ DMA Framework Design and Reference Guide" document.

---

Function Documentation

Int DMAN3_grantDmaChannels	(	Int	groupId,
		IALG_Handle	algHandle[],
		IDMA3_Fxns *	dmaFxns[],
		Int	numAlgs
	)

Add one or several algorithms to the DMA Manager. The DMA Manager will grant DMA resources to the algorithms as a result. This function is called when initializing XDAIS algorithm instances.

Parameters:

[in]	groupId	Group number for sharing TCCs and PaRAMs. Channels created with the same group number in a previous or subsequent call to this function will share the same TCCs and PaRam, as the channels created in this call, so they must be used simultaneously. The channels created in this function call, will not share TCCs and PaRam with eachother, even though they use the same group Id. When granting DMA resources for several algorithms (i.e. when numAlgs is greater than 1) these algorithms do not share TCCs and PaRAMs. If two algorithms can share TCCs and PaRAMs, two calls to DMAN3_grantDmaChannels() are needed.
[in]	algHandle[]	Array of algorithm handles.
[in]	dmaFxns[]	Array of IDMA3 Interfaces associated with each algorithm handle.
[in]	numAlgs	Number of algorithms in algHandle array.

Return values:

DMAN3_SOK	Success.
DMAN3_EOUTOFMEMORY	Failed to allocate logical handle.
DMAN3_EFAIL	Failed to initialize handle or dmaFxns dmaInit() failed.
DMAN3_EOUTOFTCCS	Not enough TCCs available for channels.
DMAN3_EOUTOFPARAMS	Not enough PaRams available for channels.

Precondition:

groupId < DMAN3_MAXGROUPS.

Valid IALG_Handle.

Valid IDMA3_Fxns pointer.

IALG_Handle->fxns->implementationId == IDMA3_Fxns->implementationId

numberOfChannels returned by algorithm's dmaGetChannelCnt and dmaGetChannels is not greater than total number of Tccs allocated.

Postcondition:

DMAN3_SOK on successful allocation of IDMA3 logical handles.

Void DMAN3_exit

(

Void

)

Finalization method of the DMAN module.

Int DMAN3_createChannels	(	Int	groupId,
		IDMA3_ChannelRec	dmaTab[],
		Int	numChans
	)

Allocate and initialize memory for one or several channel handles.

Parameters:

[in]	groupId	Group number for sharing TCCs and PaRAMs. Channels created with the same group number in a previous or subsequent call to this function will share the same TCCs and PaRam, as the channels created in this call, so they must be used simultaneously. The channels created in this function call, will not share TCCs and PaRam with eachother, even though they use the same group Id. If two channels can share TCCs and PaRAMS then two calls to DMAN3_createChannels() are needed.
[in]	dmaTab	Array of IDMA3 channel resource descriptors containing the parameters of the requested channels.
[in]	numChans	Number of entries in dmaTab (ie, number of channels to create).
[out]	dmaTab	On success assign valid and initialized IDMA3 logical DMA handle and environment (env, envSize) fields.

Return values:

DMAN3_SOK	Success.
DMAN3_EOUTOFMEMORY	Failed to allocate logical handle.
DMAN3_EFAIL	Failed to initialize handle or dmaFxns dmaInit() failed.
DMAN3_EOUTOFTCCS	Not enough TCCs available for channels.
DMAN3_EOUTOFPARAMS	Not enough PaRams available for channels.

Precondition:

Valid dmaTab structure.

numChans >= 0.

groupId < DMAN3_MAXGROUPS.

Postcondition:

On success, each handle in dmaTab[] will be set to a valid IDMA3_Handle. The 'env' field of the IDMA3_Handle will be set to newly allocated memory whose size is determined by the IDMA3_InitFxns passed in the dmaTab entry. On failure, the handle of each dmaTab[] entry will be NULL.

Void DMAN3_init

(

Void

)

Initialization method of the DMAN3 module. DMAN3_init() uses externally configured and provided DMAN3_PARAMS to initialize DMAN3 resources (QDMA channel map, memory heap...)

Precondition:

DMAN3_PARAMS must be initialized

Int DMAN3_releaseDmaChannels	(	IALG_Handle	algHandle[],
		IDMA3_Fxns *	dmaFxns[],
		Int	numAlgs
	)

Remove logical channel resources from one or several algorithm instances.

Parameters:

[in]	algHandle[]	Array of algorithm handles.
[in]	dmaFxns[]	Array of IDMA3 Interfaces associated with the algorithm handles.
[in]	numAlgs	Number of algorithm handles in algHandle[].

Precondition:

algHandle is an array of valid IALG_Handle

dmaFxns is an array of valid IDMA3_Fxns pointer

IALG_Handle->fxns->implementationId == IDMA2_Fxns->implementationId

numberOfChannels returned by algorithm's dmaGetChannelCnt and dmaGetChannels is >= 0 and not greater than number of Tccs allocated

Postcondition:

Handle and environment memory and allocated resources are freed/released.

Int DMAN3_freeChannels	(	IDMA3_Handle	channelTab[],
		Int	numChans
	)

Free memory for array of channel handles.

Parameters:

[in]	channelTab	Array of IDMA3 handles representing logical dma channel state.
[in]	numChans	Number of entries in channelTab (ie, number of channels to free).

Return values:

DMAN3_SOK

Success.

Precondition:

numChans >= 0.

Valid IDMA3 logical channel handles or numChans == 0.

Postcondition:

'handle' and 'env' memory freed for each channel.

---

Define Documentation

#define DMAN3_MODNAME   "ti.sdo.fc.dman3"

Name to pass to Diags_setMask() to enable logging for DMAN3 functions. For example, Diags_setMask(DMAN3_MODNAME"+EX1234567"); turns on all Log statements in this module. Diags_setMask() must be called after initialization to take effect.

#define DMAN3_GTNAME   "ti.sdo.fc.dman3"

Name to identify the GT module

#define DMAN3_MAXGROUPS   20

Maximum number of groups for sharing TCCs and parameter RAM.

#define DMAN3_SOK   0

DMAN3 Status Code: Successful.

#define DMAN3_EOUTOFMEMORY   -1

DMAN3 Status Code: Failed to allocate memory for the handle.

#define DMAN3_EFAIL   -2

DMAN3 Status Code: Unspecified error.

#define DMAN3_EFREE   -3

DMAN3 Status Code: Failed to free memory.

#define DMAN3_EOUTOFTCCS   -4

DMAN3 Status Code: Insufficient number of TCCs available to create channels.

#define DMAN3_EOUTOFPARAMS   -5

DMAN3 Status Code: Insufficient number of PaRams available to create channels.

#define DMAN3_ETCCCONFIG   -6

DMAN3 Status Code: The number of TCCs configured for the scratchId is not enough to create the channels. This error can only be returned if allowUnshared is set to FALSE.

#define DMAN3_EPARAMCONFIG   -7

DMAN3 Status Code: The number of PaRams configured for the scratchId is not enough to create the channels. This error can only be returned if allowUnshared is set to FALSE.

---

Typedef Documentation

typedef Bool(* DMAN3_ScratchAllocFxn)(IALG_Handle alg, Int mutexId, IALG_MemRec *memTab, Int numRecs)

Function prototype for allocating IDMA3 Object's env from shared scratch memory. Algorithms might specify a particular IDMA3 protocol that provides custom DMA services. This protocol might require extra memory for the IDMA3 object's environment. DMAN3_ScratchAllocFxn might be used to allocate this memory. If this is NULL, then the env will be allocated from persistent memory.

typedef Void(* DMAN3_ScratchFreeFxn)(Int mutexId, Void *addr, Uns size)

Function prototype for freeing IDMA3 Object's env from shared scratch memory. If this is NULL then env will be freed from persistent memory.

typedef struct DMAN3_Params DMAN3_Params

The module configuration structure for DMAN3 implementation. It is set at design time by the system integrator to ensure optimal sharing of DMA resources for the execution environment.

Remarks:

Typically, system integrators configure these settings using XDC config scripts. System integrators that use that method of configuration can ignore this structure definition. It's auto-generated during the config step by the XDC Tools.

---

Variable Documentation

DMAN3_Params DMAN3_PARAMS

Default module configuration structure (defined in dman3.c).

Uns ti_sdo_fc_dman3_DMAN3_numQdmaGroup[20+1]

Array containing the number of Qdma channels that will be assigned to the algorithm groups for sharing.

Bool ti_sdo_fc_dman3_DMAN3_useCustomDma

Flag indicating if custom DMA library is being used.