EDMA3 Resource Manager Basic APIs
[EDMA3 Resource Manager APIs]

Functions
EDMA3_RM_Result	EDMA3_RM_registerTccCb (EDMA3_RM_Handle hEdmaResMgr, const EDMA3_RM_ResDesc *channelObj, uint32_t tcc, EDMA3_RM_TccCallback tccCb, void *cbData)
	Registers a transfer completion handler for a specific DMA/QDMA channel.
EDMA3_RM_Result	EDMA3_RM_unregisterTccCb (EDMA3_RM_Handle hEdmaResMgr, const EDMA3_RM_ResDesc *channelObj)
	Unregister the previously registered callback function against a DMA/QDMA channel.
EDMA3_RM_Result	EDMA3_RM_allocResource (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *resObj)
	This API is used to allocate specified EDMA3 Resources like DMA/QDMA channel, PaRAM Set or TCC.
EDMA3_RM_Result	EDMA3_RM_freeResource (EDMA3_RM_Handle hEdmaResMgr, const EDMA3_RM_ResDesc *resObj)
	This API is used to free previously allocated EDMA3 Resources like DMA/QDMA channel, PaRAM Set or TCC.
EDMA3_RM_Result	EDMA3_RM_allocContiguousResource (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *firstResIdObj, uint32_t numResources)
	Allocate a contiguous region of specified EDMA3 Resource like DMA channel, QDMA channel, PaRAM Set or TCC.
EDMA3_RM_Result	EDMA3_RM_freeContiguousResource (EDMA3_RM_Handle hEdmaResMgr, EDMA3_RM_ResDesc *firstResIdObj, uint32_t numResources)
	Free a contiguous region of specified EDMA3 Resource like DMA channel, QDMA channel, PaRAM Set or TCC, previously allocated.

---

Function Documentation

EDMA3_RM_Result EDMA3_RM_registerTccCb	(	EDMA3_RM_Handle	hEdmaResMgr,
		const EDMA3_RM_ResDesc *	channelObj,
		uint32_t	tcc,
		EDMA3_RM_TccCallback	tccCb,
		void *	cbData
	)

Registers a transfer completion handler for a specific DMA/QDMA channel.

This function registers a non-NULL callback function for a specific DMA or QDMA channel and enables the completion interrupt for the TCC associated with the underlying channel in the IER/IERH register. It also sets the DRAE/DRAEH register for the TCC associated with the specified DMA/QDMA channel. If user enables the transfer completion interrupts (intermediate or final) in the OPT field of the associated PaRAM Set, the registered callback function will be called by the EDMA3 Resource Manager.

If a call-back function is already registered for the channel, the API fails with the error code EDMA3_RM_E_CALLBACK_ALREADY_REGISTERED.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened EDMA3 Resource Manager Instance
	channelObj	[IN] Channel ID and type (DMA or QDMA Channel), allocated earlier, and corresponding to which a callback function needs to be registered against the associated TCC.
	tcc	[IN] TCC against which the handler needs to be registered.
	tccCb	[IN] The Callback function to be registered against the TCC.
	cbData	[IN] Callback data to be passed while calling the callback function.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

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

EDMA3_RM_Result EDMA3_RM_unregisterTccCb	(	EDMA3_RM_Handle	hEdmaResMgr,
		const EDMA3_RM_ResDesc *	channelObj
	)

Unregister the previously registered callback function against a DMA/QDMA channel.

This function un-registers the previously registered callback function for the DMA/QDMA channel by removing any stored callback function. Moreover, it clears the: Interrupt Enable Register (IER/IERH) by writing to the IECR/IECRH register, for the TCC associated with that particular channel, DRA/DRAEH register for the TCC associated with the specified DMA/QDMA channel

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened EDMA3 Resource Manager Instance
	channelObj	[IN] Channel ID and type, allocated earlier (DMA or QDMA Channel ONLY), and corresponding to which a TCC is there. Against that TCC, the callback needs to be un-registered.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code.

Note:

This function is re-entrant for unique (channelObj->type + channelObj->resId) combination. It is non-re-entrant for same channelObj Resource.

EDMA3_RM_Result EDMA3_RM_allocResource	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	resObj
	)

This API is used to allocate specified EDMA3 Resources like DMA/QDMA channel, PaRAM Set or TCC.

Note: To free the resources allocated by this API, user should call EDMA3_RM_freeResource () ONLY to de-allocate all the allocated resources.

User can either request a specific resource by passing the resource id in 'resObj->resId' OR request ANY available resource of the type 'resObj->type'.

ANY types of resources are those resources when user doesn't care about the actual resource allocated; user just wants a resource of the type specified. One use-case is to perform memory-to-memory data transfer operation. This operation can be performed using any available DMA or QDMA channel. User doesn't need any specific channel for the same.

To allocate a specific resource, first this API checks whether that resource is OWNED by the Resource Manager instance. Then it checks the current availability of that resource.

To allocate ANY available resource, this API tries to allocate a resource from the pool of (owned && non_reserved && available_right_now) resources.

After allocating a DMA/QDMA channel, the same resource is enabled in the shadow region specific register (DRAE/DRAEH/QRAE). DRAE/DRAEH register for a TCC is updated only when user registers a callback function against that TCC using EDMA3_RM_registerTccCb().

Allocated PaRAM Set is initialized to NULL before this API returns if user has requested for one.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	resObj	[IN/OUT] Handle to the resource descriptor object, which needs to be allocated. In case user passes a specific resource Id, resObj value is left unchanged. In case user requests ANY available resource, the allocated resource id is returned in resObj.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function acquires a RM Instance specific semaphore to prevent simultaneous access to the global pool of resources. It is re-entrant, but should not be called from the user callback function (ISR context).

EDMA3_RM_Result EDMA3_RM_freeResource	(	EDMA3_RM_Handle	hEdmaResMgr,
		const EDMA3_RM_ResDesc *	resObj
	)

This API is used to free previously allocated EDMA3 Resources like DMA/QDMA channel, PaRAM Set or TCC.

To free a specific resource, first this API checks whether that resource is OWNED by the Resource Manager Instance. Then it checks whether that resource has been allocated by the Resource Manager instance or not.

After freeing a DMA/QDMA channel, the same resource is disabled in the shadow region specific register (DRAE/DRAEH/QRAE). This operation is performed for TCC while unregistering the callback function.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	resObj	[IN] Handle to the resource descriptor object, which needs to be freed.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function disables the global interrupts to prevent simultaneous access to the global pool of resources. It is re-entrant.

EDMA3_RM_Result EDMA3_RM_allocContiguousResource	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	firstResIdObj,
		uint32_t	numResources
	)

Allocate a contiguous region of specified EDMA3 Resource like DMA channel, QDMA channel, PaRAM Set or TCC.

This API is used to allocate a contiguous region of specified EDMA3 Resources like DMA channel, QDMA channel, PaRAM Set or TCC.

User can specify a particular resource Id to start with and go up to the number of resources requested. The specific resource id to start from could be passed in 'firstResIdObject->resId' and the number of resources requested in 'numResources'.

User can also request ANY available resource(s) of the type 'firstResIdObject->type' by specifying 'firstResIdObject->resId' as EDMA3_RM_RES_ANY.

ANY types of resources are those resources when user doesn't care about the actual resource allocated; user just wants a resource of the type specified. One use-case is to perform memory-to-memory data transfer operation. This operation can be performed using any available DMA or QDMA channel. User doesn't need any specific channel for the same.

To allocate specific contiguous resources, first this API checks whether those requested resources are OWNED by the Resource Manager instance. Then it checks the current availability of those resources.

To allocate ANY available contiguous resources, this API tries to allocate resources from the pool of (owned && non_reserved && available_right_now) resources.

After allocating DMA/QDMA channels, the same resources are enabled in the shadow region specific register (DRAE/DRAEH/QRAE). DRAE/DRAEH register for a TCC is updated only when user registers a callback function against that TCC using EDMA3_RM_registerTccCb(). Allocated PaRAM Sets are initialized to NULL before this API returns.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	firstResIdObj	[IN] Handle to the first resource descriptor object, which needs to be allocated. firstResIdObject->resId could be a valid resource id in case user wants to allocate specific resources OR it could be EDMA3_RM_RES_ANY in case user wants only the required number of resources and doesn't care about which resources were allocated.
	numResources	[IN] Number of contiguous resources user wants to allocate.

Returns:

EDMA3_RM_SOK or EDMA3_RM Error Code

Note:

This function acquires a RM Instance specific semaphore to prevent simultaneous access to the global pool of resources. It is re-entrant, but should not be called from the user callback function (ISR context).

EDMA3_RM_Result EDMA3_RM_freeContiguousResource	(	EDMA3_RM_Handle	hEdmaResMgr,
		EDMA3_RM_ResDesc *	firstResIdObj,
		uint32_t	numResources
	)

Free a contiguous region of specified EDMA3 Resource like DMA channel, QDMA channel, PaRAM Set or TCC, previously allocated.

This API frees a contiguous region of specified EDMA3 Resources like DMA channel, QDMA channel, PaRAM Set or TCC, which have been previously allocated. In case of an error during the freeing of any specific resource, user can check the 'firstResIdObj' object to know the last resource id whose freeing has failed. In case of success, there is no need to check this object.

Parameters:

	hEdmaResMgr	[IN] Handle to the previously opened Resource Manager Instance.
	firstResIdObj	[IN/OUT] Handle to the first resource descriptor object, which needs to be freed. In case of an error while freeing any particular resource, the last resource id whose freeing has failed is returned in this resource descriptor object.
	numResources	[IN] Number of contiguous resources allocated previously which user wants to release

Note:

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