Introduction

This is UDMA driver ring related configuration parameters and API

Files
file	udma_ring.h
	UDMA ring related parameters and API.

Data Structures
struct	Udma_RingPrms
	UDMA ring parameters. More...

struct	Udma_RingObject
	Opaque UDMA ring object. More...

Functions
int32_t	Udma_ringAlloc (Udma_DrvHandle drvHandle, Udma_RingHandle ringHandle, uint16_t ringNum, const Udma_RingPrms *ringPrms)
	UDMA ring allocation and configuration API. More...

int32_t	Udma_ringFree (Udma_RingHandle ringHandle)
	UDMA free ring. More...

int32_t	Udma_ringAttach (Udma_DrvHandle drvHandle, Udma_RingHandle ringHandle, uint16_t ringNum)
	UDMA ring attach API. This API is used to attach to an already allocated and configured ring. This API differs from ring alloc API in this aspect - it doesn't allocate resource from RM and doesn't configure the ring through sciclient/DMSC API. More...

int32_t	Udma_ringDetach (Udma_RingHandle ringHandle)
	UDMA detach ring API. More...

int32_t	Udma_ringQueueRaw (Udma_RingHandle ringHandle, uint64_t phyDescMem)
	UDMA queue descriptor to a ring - raw version (Takes all physical pointers) More...

int32_t	Udma_ringDequeueRaw (Udma_RingHandle ringHandle, uint64_t *phyDescMem)
	UDMA dequeue descriptor from a ring - raw version (Takes all physical pointers). More...

int32_t	Udma_ringFlushRaw (Udma_RingHandle ringHandle, uint64_t *phyDescMem)
	UDMA dequeue descriptor from a ring when UDMA channel is disabled - raw version (Takes all physical pointers). More...

void	Udma_ringPrime (Udma_RingHandle ringHandle, uint64_t phyDescMem)
	UDMA prime descriptor to a exposed/"RING" mode ring - raw version (Takes all physical pointers). This will write the descriptor to the ring memory without setting the doorbell (doesn't commit the push). More...

void	Udma_ringPrimeRead (Udma_RingHandle ringHandle, uint64_t *phyDescMem)
	UDMA read descriptor from a exposed/"RING" mode ring - raw version (Reads physical pointers). This will read the descriptor address from the ring memory without setting the doorbell (doesn't commit the pop). More...

void	Udma_ringSetDoorBell (Udma_RingHandle ringHandle, int32_t count)
	UDMA ring API to set the doorbell in exposed/"RING" mode ring. This will commit the previously primed operation using Udma_ringPrime API. More...

uint16_t	Udma_ringGetNum (Udma_RingHandle ringHandle)
	Returns the ring number allocated for this ring. More...

void *	Udma_ringGetMemPtr (Udma_RingHandle ringHandle)
	Returns the ring memory pointer which is passed during ring alloc. More...

uint32_t	Udma_ringGetMode (Udma_RingHandle ringHandle)
	Returns the ring mode which is configured during ring alloc. More...

uint32_t	Udma_ringGetElementCnt (Udma_RingHandle ringHandle)
	Returns the ring element count which is passed during ring alloc. More...

uint32_t	Udma_ringGetForwardRingOcc (Udma_RingHandle ringHandle)
	Returns the forward ring occupancy. More...

uint32_t	Udma_ringGetReverseRingOcc (Udma_RingHandle ringHandle)
	Returns the reverse ring occupancy. More...

uint32_t	Udma_ringGetWrIdx (Udma_RingHandle ringHandle)
	Returns the ring write index value. More...

uint32_t	Udma_ringGetRdIdx (Udma_RingHandle ringHandle)
	Returns the ring read index value. More...

void	UdmaRingPrms_init (Udma_RingPrms *ringPrms)
	Udma_RingPrms structure init function. More...

Macros
#define	UDMA_RING_INVALID ((uint16_t) TISCI_MSG_VALUE_RM_NULL_RING_TYPE)
	Macro used to specify that ring ID is invalid. Used in the API Udma_ringGetNum. More...

#define	UDMA_RING_ANY ((uint16_t) 0xFFFEU)
	Macro used to specify any available free ring while requesting one. Used in the API Udma_ringAlloc. More...

#define	UDMA_RING_VIRTID_INVALID ((uint16_t) 0xFFFFU)
	Macro used to specify that ring virt ID is invalid. Used in the API Udma_ringAlloc. More...

#define	UDMA_RING_SIZE_CHECK_SKIP (0xABDCABCDU)
	Macro used to skip the ring size check by driver. More...

#define	UDMA_RING_ORDERID_MAX (0x0FU)
	Macro used to specificy the maximum ring order id value. More...

UDMA Ring element size
Encoded ring element size to be programmed into the elsize field of the ring's RING_SIZE register. To calculate the encoded size use the formula (log2(size_bytes) - 2), where "size_bytes" cannot be greater than 256 bytes. This calculation is already taken care in below macro.
#define	UDMA_RING_ES_4BYTES ((uint8_t) 0x00U)
	4 bytes Element size More...

#define	UDMA_RING_ES_8BYTES ((uint8_t) 0x01U)
	8 bytes Element size More...

#define	UDMA_RING_ES_16BYTES ((uint8_t) 0x02U)
	16 bytes Element size More...

#define	UDMA_RING_ES_32BYTES ((uint8_t) 0x03U)
	32 bytes Element size More...

#define	UDMA_RING_ES_64BYTES ((uint8_t) 0x04U)
	64 bytes Element size More...

#define	UDMA_RING_ES_128BYTES ((uint8_t) 0x05U)
	128 bytes Element size More...

#define	UDMA_RING_ES_256BYTES ((uint8_t) 0x06U)
	256 bytes Element size More...

Macro Definition Documentation

◆ UDMA_RING_INVALID

#define UDMA_RING_INVALID ((uint16_t) TISCI_MSG_VALUE_RM_NULL_RING_TYPE)

Macro used to specify that ring ID is invalid. Used in the API Udma_ringGetNum.

◆ UDMA_RING_ANY

#define UDMA_RING_ANY ((uint16_t) 0xFFFEU)

Macro used to specify any available free ring while requesting one. Used in the API Udma_ringAlloc.

◆ UDMA_RING_VIRTID_INVALID

#define UDMA_RING_VIRTID_INVALID ((uint16_t) 0xFFFFU)

Macro used to specify that ring virt ID is invalid. Used in the API Udma_ringAlloc.

◆ UDMA_RING_SIZE_CHECK_SKIP

#define UDMA_RING_SIZE_CHECK_SKIP (0xABDCABCDU)

Macro used to skip the ring size check by driver.

◆ UDMA_RING_ORDERID_MAX

#define UDMA_RING_ORDERID_MAX (0x0FU)

Macro used to specificy the maximum ring order id value.

◆ UDMA_RING_ES_4BYTES

#define UDMA_RING_ES_4BYTES ((uint8_t) 0x00U)

4 bytes Element size

◆ UDMA_RING_ES_8BYTES

#define UDMA_RING_ES_8BYTES ((uint8_t) 0x01U)

8 bytes Element size

◆ UDMA_RING_ES_16BYTES

#define UDMA_RING_ES_16BYTES ((uint8_t) 0x02U)

16 bytes Element size

◆ UDMA_RING_ES_32BYTES

#define UDMA_RING_ES_32BYTES ((uint8_t) 0x03U)

32 bytes Element size

◆ UDMA_RING_ES_64BYTES

#define UDMA_RING_ES_64BYTES ((uint8_t) 0x04U)

64 bytes Element size

◆ UDMA_RING_ES_128BYTES

#define UDMA_RING_ES_128BYTES ((uint8_t) 0x05U)

128 bytes Element size

◆ UDMA_RING_ES_256BYTES

#define UDMA_RING_ES_256BYTES ((uint8_t) 0x06U)

256 bytes Element size

Function Documentation

◆ Udma_ringAlloc()

int32_t Udma_ringAlloc	(	Udma_DrvHandle	drvHandle,
		Udma_RingHandle	ringHandle,
		uint16_t	ringNum,
		const Udma_RingPrms *	ringPrms
	)

UDMA ring allocation and configuration API.

Parameters

drvHandle	[IN] UDMA driver handle pointer passed during Udma_init
ringHandle	[IN/OUT] UDMA ring handle. The caller need to allocate memory for this object and pass this pointer to all further APIs. The caller should not change any parameters as this is owned and maintained by the driver.
ringNum	[IN] Ring number. If set to UDMA_RING_ANY, will allocate from free ring pool. Else will try to allocate the mentioned ring itself.
ringPrms	[IN] UDMA ring parameters. This parameter can't be NULL.

Returns: Udma_ErrorCodes

◆ Udma_ringFree()

int32_t Udma_ringFree ( Udma_RingHandle ringHandle )

UDMA free ring.

Freeup the ring resources.

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Udma_ErrorCodes

◆ Udma_ringAttach()

int32_t Udma_ringAttach	(	Udma_DrvHandle	drvHandle,
		Udma_RingHandle	ringHandle,
		uint16_t	ringNum
	)

UDMA ring attach API. This API is used to attach to an already allocated and configured ring. This API differs from ring alloc API in this aspect - it doesn't allocate resource from RM and doesn't configure the ring through sciclient/DMSC API.

Post this attach operation, other standard ring operations can be performed. This API is provided for usecases where a ring is configured by a remote entity and needs to be used for runtime operation from another entity.

Requirement: DOX_REQ_TAG(PDK-3419)

Parameters

drvHandle	[IN] UDMA driver handle pointer passed during Udma_init
ringHandle	[IN/OUT] UDMA ring handle. The caller need to allocate memory for this object and pass this pointer to all further APIs. The caller should not change any parameters as this is owned and maintained by the driver.
ringNum	[IN] Ring number to attach with. This paramter should be a valid ring number allowed to be used by a core. The driver doesn't check the validity of this field at the time of attach. But the runtime ring API may fail if wrong ring index is used or when the core does ring operation when it doesn't own the ring based on credential and DMSC board config.

Returns: Udma_ErrorCodes

◆ Udma_ringDetach()

int32_t Udma_ringDetach ( Udma_RingHandle ringHandle )

UDMA detach ring API.

Since no allocation is done in attach, this API just clears up the ring handle.

Requirement: DOX_REQ_TAG(PDK-3419)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Udma_ErrorCodes

◆ Udma_ringQueueRaw()

int32_t Udma_ringQueueRaw	(	Udma_RingHandle	ringHandle,
		uint64_t	phyDescMem
	)

UDMA queue descriptor to a ring - raw version (Takes all physical pointers)

This function will push the descriptor to the ring as identified by the ring handle.

Incase of exposed/"RING" mode, this will use the ring door bell mechanism. For other modes, this will push the descriptor to the ring through the proxy allocated to the driver handle.

Writing through a proxy is required for ring push operation when the ring is not in "RING" mode and when the host/core cannot perform a 64-bit atomic write operation.

This API is thread safe for a ring instance and can be called from interrupt or task context and also from multiple threads.

Requirement: DOX_REQ_TAG(PDK-2587) Requirement: DOX_REQ_TAG(PDK-2633)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
phyDescMem	[IN] Descriptor memory physical pointer to push to the ring.

Returns: Udma_ErrorCodes

◆ Udma_ringDequeueRaw()

int32_t Udma_ringDequeueRaw	(	Udma_RingHandle	ringHandle,
		uint64_t *	phyDescMem
	)

UDMA dequeue descriptor from a ring - raw version (Takes all physical pointers).

This function will pop the descriptor from the ring as identified by the ring handle.

Incase of exposed/"RING" mode, this will use the ring door bell mechanism. For other modes, this will pop the descriptor from the ring through the proxy allocated to the driver handle.

Reading through a proxy is required for ring pop operation when the ring is not in "RING" mode and when the host/core cannot perform a 64-bit atomic read operation.

This API is thread safe for a ring instance and can be called from interrupt or task context and also from multiple threads.

This is non-blocking and will return timeout error UDMA_ETIMEOUT when the queue is empty.

Caution: Dequeuing from a ring (free queue) to which the UDMA reads should be performed only when the channel is disabled and using Udma_ringFlushRaw API.

Requirement: DOX_REQ_TAG(PDK-2588) Requirement: DOX_REQ_TAG(PDK-2633)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
phyDescMem	[OUT] Descriptor memory physical pointer read from the ring. This will be NULL if there is nothing to pop from the ring.

Returns: Udma_ErrorCodes

◆ Udma_ringFlushRaw()

int32_t Udma_ringFlushRaw	(	Udma_RingHandle	ringHandle,
		uint64_t *	phyDescMem
	)

UDMA dequeue descriptor from a ring when UDMA channel is disabled - raw version (Takes all physical pointers).

This function will pop the unprocessed descriptor from the the ring (say the free ring which is used by UDMA channel).

This is non-blocking and will return timeout error UDMA_ETIMEOUT when the queue is empty.

Caution: Dequeuing from a ring (free queue) to which the UDMA reads should be performed only when the channel is disabled.

Requirement: DOX_REQ_TAG(PDK-3238)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
phyDescMem	[OUT] Descriptor memory physical pointer read from the ring. This will be NULL if there is nothing to pop from the ring.

Returns: Udma_ErrorCodes

◆ Udma_ringPrime()

void Udma_ringPrime	(	Udma_RingHandle	ringHandle,
		uint64_t	phyDescMem
	)

UDMA prime descriptor to a exposed/"RING" mode ring - raw version (Takes all physical pointers). This will write the descriptor to the ring memory without setting the doorbell (doesn't commit the push).

This API can be used to prime multiple request to the free queue ring and then set the doorbell using Udma_ringSetDoorBell API.

Also no cache operation is performed to let the caller do the cache ops once for the entire ring after priming multiple elements. This will yeild better performance instead of doing cache ops for each ring push.

Note: No error check is performed by this API to minimize the CPU cycles. The caller should ensure that the ring is in exposed/"RING" mode and there are enough room in the ring and the ring pointer is non-null.

This API is thread safe for a ring instance and can be called from interrupt or task context and also from multiple threads.

Requirement: DOX_REQ_TAG(PDK-3669)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
phyDescMem	[IN] Descriptor memory physical pointer to push to the ring.

◆ Udma_ringPrimeRead()

void Udma_ringPrimeRead	(	Udma_RingHandle	ringHandle,
		uint64_t *	phyDescMem
	)

UDMA read descriptor from a exposed/"RING" mode ring - raw version (Reads physical pointers). This will read the descriptor address from the ring memory without setting the doorbell (doesn't commit the pop).

This API can be used to read multiple descriptor addresses from the completion queue ring and then set the doorbell using Udma_ringSetDoorBell API.

Also no cache operation is performed to let the caller do the cache ops once for the entire ring after reading multiple elements. This will yeild better performance instead of doing cache ops for each ring pop.

Note: No error check is performed by this API to minimize the CPU cycles. The caller should ensure that the ring is in exposed/"RING" mode and descriptor addresses are in the ring and the ring pointer is non-null. Also make sure that its not reading more than the what Udma_ringGetReverseRingOcc returns.

This API is thread safe for a ring instance and can be called from interrupt or task context and also from multiple threads.

Requirement: DOX_REQ_TAG(PDK-3669)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
phyDescMem	[IN] Descriptor memory physical pointer to pop from the ring.

◆ Udma_ringSetDoorBell()

void Udma_ringSetDoorBell	(	Udma_RingHandle	ringHandle,
		int32_t	count
	)

UDMA ring API to set the doorbell in exposed/"RING" mode ring. This will commit the previously primed operation using Udma_ringPrime API.

Note: The count will be positive when ring elements are queued into the ring and count will be negative when ring elements are dequeued from the ring. In case of devices like AM64x with LCDMA ring accelerator, when the count is positive, it sets the forward doorbell of the common ring and when the count is negative, it sets the reverse doorbell of the common ring. For other devices with normal ring accelerator, these sets the doorbell of the ring. Here its meaningful to pass the ringHandle of Free Queue Ring when the count is positive and pass the ringHandle of Completion Queue Ring when the count is negative.

Note: No error check is performed by this API to minimize the CPU cycles. The caller should ensure that the ring is in exposed/"RING" mode and there are enough room in te ring and the ring pointer is non-null.

This API is thread safe for a ring instance and can be called from interrupt or task context and also from multiple threads.

Requirement: DOX_REQ_TAG(PDK-3669)

Parameters

ringHandle	[IN] UDMA ring handle. This parameter can't be NULL.
count	[IN] Number of count to commit.

◆ Udma_ringGetNum()

uint16_t Udma_ringGetNum ( Udma_RingHandle ringHandle )

Returns the ring number allocated for this ring.

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: The ring number on success or UDMA_RING_INVALID on error

◆ Udma_ringGetMemPtr()

void* Udma_ringGetMemPtr ( Udma_RingHandle ringHandle )

Returns the ring memory pointer which is passed during ring alloc.

Requirement: DOX_REQ_TAG(PDK-3668)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring memory pointer on success or NULL on error

◆ Udma_ringGetMode()

uint32_t Udma_ringGetMode ( Udma_RingHandle ringHandle )

Returns the ring mode which is configured during ring alloc.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring mode on success or CSL_RINGACC_RING_MODE_INVALID on error

◆ Udma_ringGetElementCnt()

uint32_t Udma_ringGetElementCnt ( Udma_RingHandle ringHandle )

Returns the ring element count which is passed during ring alloc.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring element count on success or zero on error

◆ Udma_ringGetForwardRingOcc()

uint32_t Udma_ringGetForwardRingOcc ( Udma_RingHandle ringHandle )

Returns the forward ring occupancy.

Note: In case of devices like AM64x with LCDMA ring accelerator, this returns the forward ring occupancy count of the common ring. For other devices with normal ring accelerator, this returns the the occupancy count of the ring. Here its meaningful to pass the ringHandle of Free Queue Ring.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring occupancy value from the register

◆ Udma_ringGetReverseRingOcc()

uint32_t Udma_ringGetReverseRingOcc ( Udma_RingHandle ringHandle )

Returns the reverse ring occupancy.

Note: In case of devices like AM64x with LCDMA ring accelerator, this returns the reverse ring occupancy count of the common ring. For other devices with normal ring accelerator, this returns the the occupancy count of the ring. Here its meaningful to pass the ringHandle of Completion Queue Ring.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring occupancy value from the register

◆ Udma_ringGetWrIdx()

uint32_t Udma_ringGetWrIdx ( Udma_RingHandle ringHandle )

Returns the ring write index value.

Note: In case of devices like AM64x with LCDMA ring accelerator, this returns the write index value of the common ring. For other devices with normal ring accelerator, this returns the the read/write index value of the ring. Here its meaningful to pass the ringHandle of Free Queue Ring.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring read/write index value

◆ Udma_ringGetRdIdx()

uint32_t Udma_ringGetRdIdx ( Udma_RingHandle ringHandle )

Returns the ring read index value.

Note: In case of devices like AM64x with LCDMA ring accelerator, this returns the read index value of the common ring. For other devices with normal ring accelerator, this returns the the read/write index value of the ring. Here its meaningful to pass the ringHandle of Completion Queue Ring.

Requirement: DOX_REQ_TAG(PDK-5665)

Parameters

ringHandle [IN] UDMA ring handle. This parameter can't be NULL.

Returns: Ring read/write index value

◆ UdmaRingPrms_init()

void UdmaRingPrms_init ( Udma_RingPrms * ringPrms )

Udma_RingPrms structure init function.

Parameters

ringPrms [IN] Pointer to Udma_RingPrms structure.

Introduction

Files

Data Structures

Functions

Macros

UDMA Ring element size

Macro Definition Documentation

◆ UDMA_RING_INVALID

◆ UDMA_RING_ANY

◆ UDMA_RING_VIRTID_INVALID

◆ UDMA_RING_SIZE_CHECK_SKIP

◆ UDMA_RING_ORDERID_MAX

◆ UDMA_RING_ES_4BYTES

◆ UDMA_RING_ES_8BYTES

◆ UDMA_RING_ES_16BYTES

◆ UDMA_RING_ES_32BYTES

◆ UDMA_RING_ES_64BYTES

◆ UDMA_RING_ES_128BYTES

◆ UDMA_RING_ES_256BYTES

Function Documentation

◆ Udma_ringAlloc()

◆ Udma_ringFree()

◆ Udma_ringAttach()

◆ Udma_ringDetach()

◆ Udma_ringQueueRaw()

◆ Udma_ringDequeueRaw()

◆ Udma_ringFlushRaw()

◆ Udma_ringPrime()

◆ Udma_ringPrimeRead()

◆ Udma_ringSetDoorBell()

◆ Udma_ringGetNum()

◆ Udma_ringGetMemPtr()

◆ Udma_ringGetMode()

◆ Udma_ringGetElementCnt()

◆ Udma_ringGetForwardRingOcc()

◆ Udma_ringGetReverseRingOcc()

◆ Udma_ringGetWrIdx()

◆ Udma_ringGetRdIdx()

◆ UdmaRingPrms_init()