EDMA3 Resource Manager Advanced APIs
[EDMA3 Resource Manager APIs]

Data Structures
struct	EDMA3_RM_GblXbarToChanConfigParams
	Init-time Configuration structure for EDMA3 controller, to provide Global SoC specific Information. More...
Typedefs
typedef EDMA3_RM_Result(*	EDMA3_RM_mapXbarEvtToChan )(uint32_t eventNum, uint32_t *chanNum, const EDMA3_RM_GblXbarToChanConfigParams *edmaGblXbarConfig)
	Associates cross bar mapped event to channel.
typedef EDMA3_RM_Result(*	EDMA3_RM_xbarConfigScr )(uint32_t eventNum, uint32_t chanNum)
	Writes to the cross bar mapped event to channel to system configuration register.
Functions
EDMA3_RM_Result	EDMA3_RM_allocLogicalChannel (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *lChObj, uint32_t *pParam, uint32_t *pTcc)
	Request a DMA/QDMA/Link channel.
EDMA3_RM_Result	EDMA3_RM_freeLogicalChannel (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *lChObj)
	This API is used to free the specified channel (DMA/QDMA/Link) and its associated resources (PaRAM Set, TCC etc).
EDMA3_RM_Result	EDMA3_RM_mapEdmaChannel (EDMA3_RM_Handle hEdmaResMgr, uint32_t channelId, uint32_t paRAMId)
	Bind the resources DMA Channel and PaRAM Set. Both the DMA channel and the PaRAM set should be previously allocated. If they are not, this API will result in error.
EDMA3_RM_Result	EDMA3_RM_mapQdmaChannel (EDMA3_RM_Handle hEdmaResMgr, uint32_t channelId, uint32_t paRAMId, EDMA3_RM_QdmaTrigWord trigWord)
	Bind the resources QDMA Channel and PaRAM Set. Also, Set the trigger word for the QDMA channel. Both the QDMA channel and the PaRAM set should be previously allocated. If they are not, this API will result in error.
EDMA3_RM_Result	EDMA3_RM_setCCRegister (EDMA3_RM_Handle hEdmaResMgr, uint32_t regOffset, uint32_t newRegValue)
	Set the Channel Controller (CC) Register value.
EDMA3_RM_Result	EDMA3_RM_getCCRegister (EDMA3_RM_Handle hEdmaResMgr, uint32_t regOffset, uint32_t *regValue)
	Get the Channel Controller (CC) Register value.
EDMA3_RM_Result	EDMA3_RM_waitAndClearTcc (EDMA3_RM_Handle hEdmaResMgr, uint32_t tccNo)
	Wait for a transfer completion interrupt to occur and clear it.
EDMA3_RM_Result	EDMA3_RM_checkAndClearTcc (EDMA3_RM_Handle hEdmaResMgr, uint32_t tccNo, uint16_t *tccStatus)
	Returns the status of a previously initiated transfer.
EDMA3_RM_Result	EDMA3_RM_setPaRAM (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *lChObj, const EDMA3_RM_PaRAMRegs *newPaRAM)
	Copy the user specified PaRAM Set onto the PaRAM Set associated with the logical channel (DMA/QDMA/Link).
EDMA3_RM_Result	EDMA3_RM_getPaRAM (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *lChObj, EDMA3_RM_PaRAMRegs *currPaRAM)
	Retrieve existing PaRAM set associated with specified logical channel (DMA/QDMA/Link).
EDMA3_RM_Result	EDMA3_RM_getPaRAMPhyAddr (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *lChObj, uint32_t *paramPhyAddr)
	Get the PaRAM Set Physical Address associated with a logical channel.
EDMA3_RM_Result	EDMA3_RM_getBaseAddress (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_Cntrlr_PhyAddr controllerId, uint32_t *phyAddress)
	Get the Channel Controller or Transfer Controller (n) Physical Address.
EDMA3_RM_Result	EDMA3_RM_getGblConfigParams (uint32_t phyCtrllerInstId, EDMA3_RM_GblConfigParams *gblCfgParams)
	Get the SoC specific configuration structure for the EDMA3 Hardware.
EDMA3_RM_Result	EDMA3_RM_getInstanceInitCfg (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_InstanceInitConfig *instanceInitConfig)
	Get the RM Instance specific configuration structure for different EDMA3 resources' usage (owned resources, reserved resources etc).
EDMA3_RM_Result	EDMA3_RM_Ioctl (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_IoctlCmd cmd, void *cmdArg, void *param)
	EDMA3 Resource Manager IOCTL.
EDMA3_RM_Result	EDMA3_RM_initXbarEventMap (EDMA3_RM_Handle hEdma, const EDMA3_RM_GblXbarToChanConfigParams *edmaGblXbarConfig, EDMA3_RM_mapXbarEvtToChan mapXbarEvtFunc, EDMA3_RM_xbarConfigScr configXbarScr)
	Initialize the cross bar mapped event to channel function.

---

Typedef Documentation

typedef EDMA3_RM_Result(* EDMA3_RM_mapXbarEvtToChan)(uint32_t eventNum, uint32_t *chanNum, const EDMA3_RM_GblXbarToChanConfigParams *edmaGblXbarConfig)

Associates cross bar mapped event to channel.

This function have to be defined in the configuration file. This function will be called only if the channel requested for is beyond the maximum number of channels. This function should read from the global cross bar mapped configuration data structure and return the mapped channel number to this event.

Parameters:

	eventNum	[IN] Event number
	chanNum	[IN/OUT]Return the channel number to which the request event is mapped to.
	edmaGblXbarConfig	[IN] This is the configuration data structure for mapping the events to the channel

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for unique event values. It is non-re-entrant for same event values.

typedef EDMA3_RM_Result(* EDMA3_RM_xbarConfigScr)(uint32_t eventNum, uint32_t chanNum)

Writes to the cross bar mapped event to channel to system configuration register.

This function have to be defined in the configuration file. This function will be called only if the event number requested for is beyond the maximum number of channels and if any channel is allocated to this event. This function should read the cross bar mapped event number and write the allocated channel number in Control Config Event Mux registers.

Parameters:

	eventNum	[IN] Event number
	chanNum	[IN/OUT]Return the channel number to which the request event is mapped to.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for unique event values. It is non-re-entrant for same event values.

---

Function Documentation

EDMA3_RM_Result EDMA3_RM_allocLogicalChannel	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	lChObj,
		uint32_t *	pParam,
		uint32_t *	pTcc
	)

Request a DMA/QDMA/Link channel.

This API is used to allocate a logical channel (DMA/QDMA/Link) along with the associated resources. For DMA and QDMA channels, TCC and PaRAM Set are also allocated along with the requested channel. For Link channel, ONLY a PaRAM Set is allocated.

Note: To free the logical channel allocated by this API, user should call EDMA3_RM_freeLogicalChannel () ONLY to de-allocate all the allocated resources and remove certain mappings.

User can request a specific logical channel by passing the channel id in 'lChObj->resId' and channel type in 'lChObj->type'. Note that the channel id is the same as the actual resource id. For e.g. in the case of QDMA channels, valid channel ids are from 0 to 7 only.

User can also request ANY available logical channel of the type 'lChObj->type' by specifying 'lChObj->resId' as: a) EDMA3_RM_DMA_CHANNEL_ANY: For DMA channels b) EDMA3_RM_QDMA_CHANNEL_ANY: For QDMA channels, and c) EDMA3_RM_PARAM_ANY: For Link channels. Normally user should use this value to request link channels (PaRAM Sets used for linking purpose only), unless he wants to use some specific link channels (PaRAM Sets) which is also allowed.

This API internally uses EDMA3_RM_allocResource () to allocate the desired resources (DMA/QDMA channel, PaRAM Set and TCC).

For DMA/QDMA channels, after allocating all the EDMA3 resources, this API sets the TCC field of the OPT PaRAM Word with the allocated TCC.

For DMA channel, it also sets the DCHMAP register, if required.

For QDMA channel, it sets the QCHMAP register and CCNT as trigger word and enables the QDMA channel by writing to the QEESR register.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	lChObj	[IN/OUT] Handle to the requested logical channel object, which needs to be allocated. It could be a specific logical channel or ANY available logical channel of the requested type. In case user passes a specific resource Id, lChObj value is left unchanged. In case user requests ANY available resource, the allocated resource id is returned in lChObj->resId.
	pParam	[IN/OUT] PaRAM Set for a particular logical (DMA/QDMA) channel. Not used if user requested for a Link channel. In case user passes a specific PaRAM Set value, pParam value is left unchanged. In case user requests ANY available PaRAM Set by passing 'EDMA3_RM_PARAM_ANY' in pParam, the allocated one is returned in pParam.
	pTcc	[IN/OUT] TCC for a particular logical (DMA/QDMA) channel. Not used if user requested for a Link channel. In case user passes a specific TCC value, pTcc value is left unchanged. In case user requests ANY available TCC by passing 'EDMA3_RM_TCC_ANY' in pTcc, the allocated one is returned in pTcc.

Returns:

EDMA3_RM_SOK or EDMA_RM Error Code

Note:

This function internally calls EDMA3_RM_allocResource (), which acquires a RM Instance specific semaphore to prevent simultaneous access to the global pool of resources. It is re-entrant for unique logical channel values, but SHOULD NOT be called from the user callback function (ISR context).

EDMA3_RM_Result EDMA3_RM_freeLogicalChannel	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	lChObj
	)

This API is used to free the specified channel (DMA/QDMA/Link) and its associated resources (PaRAM Set, TCC etc).

This API internally uses EDMA3_RM_freeResource () to free the desired resources.

For DMA/QDMA channels, it also clears the DCHMAP/QCHMAP registers

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	lChObj	[IN] Handle to the logical channel object, which needs to be freed

Returns:

EDMA3_RM_SOK or EDMA_RM Error Code

Note:

This is a re-entrant function which internally calls EDMA3_RM_freeResource () for resource de-allocation.

EDMA3_RM_Result EDMA3_RM_mapEdmaChannel	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	channelId,
		uint32_t	paRAMId
	)

Bind the resources DMA Channel and PaRAM Set. Both the DMA channel and the PaRAM set should be previously allocated. If they are not, this API will result in error.

This API sets the DCHMAP register for a specific DMA channel. This register is used to specify the PaRAM Set associated with that particular DMA Channel.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	channelId	[IN] Previously allocated DMA Channel on which Transfer will occur.
	paRAMId	[IN] Previously allocated PaRAM Set which needs to be associated with the dma channel.

Returns:

EDMA3_RM_SOK or EDMA_RM Error Code

Note:

This API is useful only for the EDMA3 Controllers which have a register for mapping a DMA Channel to a particular PaRAM Set (DCHMAP register). On platforms where this feature is not supported, this API returns error code: EDMA3_RM_E_FEATURE_UNSUPPORTED. This function is re-entrant for unique channelId. It is non-re-entrant for same channelId values.

EDMA3_RM_Result EDMA3_RM_mapQdmaChannel	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	channelId,
		uint32_t	paRAMId,
		EDMA3_RM_QdmaTrigWord	trigWord
	)

Bind the resources QDMA Channel and PaRAM Set. Also, Set the trigger word for the QDMA channel. Both the QDMA channel and the PaRAM set should be previously allocated. If they are not, this API will result in error.

This API sets the QCHMAP register for a specific QDMA channel. This register is used to specify the PaRAM Set associated with that particular QDMA Channel along with the trigger word.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	channelId	[IN] Previously allocated QDMA Channel on which Transfer will occur.
	paRAMId	[IN] Previously allocated PaRAM Set, which needs to be associated with channelId
	trigWord	[IN] The Trigger Word for the channel. Trigger Word is the word in the PaRAM Register Set which - when written to by CPU -will start the QDMA transfer automatically

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for unique channelId. It is non-re-entrant for same channelId values.

EDMA3_RM_Result EDMA3_RM_setCCRegister	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	regOffset,
		uint32_t	newRegValue
	)

Set the Channel Controller (CC) Register value.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	regOffset	[IN] CC Register offset whose value needs to be set. It should be word-aligned.
	newRegValue	[IN] New CC Register Value

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is non re-entrant for users using the same Resource Manager handle. Before modifying a register, it tries to acquire a semaphore (RM instance specific), to protect simultaneous modification of the same register by two different users. After the successful change, it releases the semaphore. For users using different RM handles, this function is re-entrant.

EDMA3_RM_Result EDMA3_RM_getCCRegister	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	regOffset,
		uint32_t *	regValue
	)

Get the Channel Controller (CC) Register value.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	regOffset	[IN] CC Register offset whose value is needed. It should be word-aligned.
	regValue	[IN/OUT] Fetched CC Register Value

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_waitAndClearTcc	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	tccNo
	)

Wait for a transfer completion interrupt to occur and clear it.

This is a blocking function that returns when the IPR/IPRH bit corresponding to the tccNo specified, is SET. It clears the corresponding bit while returning also.

This function waits for the specific bit indefinitely in a tight loop, with out any delay in between. USE IT CAUTIOUSLY.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	tccNo	[IN] TCC, specific to which the function waits on a IPR/IPRH bit.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for different tccNo.

EDMA3_RM_Result EDMA3_RM_checkAndClearTcc	(	EDMA3_RM_Handle	hEdmaResMgr,
		uint32_t	tccNo,
		uint16_t *	tccStatus
	)

Returns the status of a previously initiated transfer.

This is a non-blocking function that returns the status of a previously initiated transfer, based on the IPR/IPRH bit. This bit corresponds to the tccNo specified by the user. It clears the corresponding bit, if SET, while returning also.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	tccNo	[IN] TCC, specific to which the function checks the status of the IPR/IPRH bit.
	tccStatus	[IN/OUT] Status of the transfer is returned here. Returns "TRUE" if the transfer has completed (IPR/IPRH bit SET), "FALSE" if the transfer has not completed successfully (IPR/IPRH bit NOT SET).

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for different tccNo.

EDMA3_RM_Result EDMA3_RM_setPaRAM	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	lChObj,
		const EDMA3_RM_PaRAMRegs *	newPaRAM
	)

Copy the user specified PaRAM Set onto the PaRAM Set associated with the logical channel (DMA/QDMA/Link).

This API takes a PaRAM Set as input and copies it onto the actual PaRAM Set associated with the logical channel. OPT field of the PaRAM Set is written first and the CCNT field is written last.

Caution: It should be used carefully when programming the QDMA channels whose trigger words are not CCNT field.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	lChObj	[IN] Logical Channel object for which new PaRAM set is specified. User should pass the resource type and id in this object.
	newPaRAM	[IN] PaRAM set to be copied onto existing one

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant for unique lChObj values. It is non- re-entrant for same lChObj value.

EDMA3_RM_Result EDMA3_RM_getPaRAM	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	lChObj,
		EDMA3_RM_PaRAMRegs *	currPaRAM
	)

Retrieve existing PaRAM set associated with specified logical channel (DMA/QDMA/Link).

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	lChObj	[IN] Logical Channel object for which the PaRAM set is requested. User should pass the resource type and id in this object.
	currPaRAM	[IN/OUT] User gets the existing PaRAM here.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_getPaRAMPhyAddr	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	lChObj,
		uint32_t *	paramPhyAddr
	)

Get the PaRAM Set Physical Address associated with a logical channel.

This function returns the PaRAM Set Phy Address (unsigned 32 bits). The returned address could be used by the advanced users to program the PaRAM Set directly without using any APIs.

Least significant 16 bits of this address could be used to program the LINK field in the PaRAM Set. Users which program the LINK field directly SHOULD use this API to get the associated PaRAM Set address with the LINK channel.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	lChObj	[IN] Logical Channel object for which the PaRAM set physical address is required. User should pass the resource type and id in this object.
	paramPhyAddr	[IN/OUT] PaRAM Set physical address is returned here.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_getBaseAddress	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_Cntrlr_PhyAddr	controllerId,
		uint32_t *	phyAddress
	)

Get the Channel Controller or Transfer Controller (n) Physical Address.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	controllerId	[IN] Channel Controller or Transfer Controller (n) for which the physical address is required.
	phyAddress	[IN/OUT] Physical address is returned here.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_getGblConfigParams	(	uint32_t	phyCtrllerInstId,
		EDMA3_RM_GblConfigParams *	gblCfgParams
	)

Get the SoC specific configuration structure for the EDMA3 Hardware.

This API is used to fetch the global SoC specific configuration structure for the EDMA3 Hardware. It is useful for the user who has not passed this information during EDMA3_RM_create() and taken the default configuration coming along with the package.

Parameters:

	phyCtrllerInstId	[IN] EDMA3 Controller Instance Id (Hardware instance id, starting from 0).
	gblCfgParams	[IN/OUT] SoC specific configuration structure for the EDMA3 Hardware will be returned here.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_getInstanceInitCfg	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_InstanceInitConfig *	instanceInitConfig
	)

Get the RM Instance specific configuration structure for different EDMA3 resources' usage (owned resources, reserved resources etc).

This API is used to fetch the Resource Manager Instance specific configuration structure, for a specific shadow region. It is useful for the user who has not passed this information during EDMA3_RM_opn() and taken the default configuration coming along with the package. EDMA3 resources, owned and reserved by this RM instance, will be returned from this API.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	instanceInitConfig	[IN/OUT] RM Instance specific configuration structure will be returned here.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function is re-entrant.

EDMA3_RM_Result EDMA3_RM_Ioctl	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_IoctlCmd	cmd,
		void *	cmdArg,
		void *	param
	)

EDMA3 Resource Manager IOCTL.

This function provides IOCTL functionality for EDMA3 Resource Manager

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	cmd	[IN] IOCTL command to be performed
	cmdArg	[IN/OUT] IOCTL command argument (if any)
	param	[IN/OUT] Device/Cmd specific argument.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

For 'EDMA3_RM_IOCTL_GET_PARAM_CLEAR_OPTION', this function is re-entrant. For 'EDMA3_RM_IOCTL_SET_PARAM_CLEAR_OPTION', this function is re-entrant for different Resource Manager Instances (handles).

EDMA3_RM_Result EDMA3_RM_initXbarEventMap	(	EDMA3_RM_Handle	hEdma,
		const EDMA3_RM_GblXbarToChanConfigParams *	edmaGblXbarConfig,
		EDMA3_RM_mapXbarEvtToChan	mapXbarEvtFunc,
		EDMA3_RM_xbarConfigScr	configXbarScr
	)

Initialize the cross bar mapped event to channel function.

This API provides interface to associate the cross bar mapped event to edma channel in the driver. This function will called by the application during initilization. User could pass the application specific configuration structure during init-time. In case user doesn't provide it, this information could be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c, in case it is available.

Parameters:

	hEdma	[IN] Handle to the EDMA Driver Instance.
	edmaGblXbarConfig	[IN] This is the configuration data structure for mapping the events to the channel
	mapXbarEvtFunc	[IN] This is the user defined function for mapping the cross bar event to channel.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function disables the global interrupts (by calling API edma3OsProtectEntry with protection level EDMA3_OS_PROTECT_INTERRUPT) while modifying the global data structures, to make it re-entrant.