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_RingMonPrms
	UDMA ring monitor parameters. More...

struct	Udma_RingMonData
	UDMA ring monitor data. More...

struct	Udma_RingHandle
	UDMA ring object. More...

struct	Udma_RingMonHandle
	UDMA ring monitor 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_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...

int32_t	Udma_ringMonAlloc (Udma_DrvHandle drvHandle, Udma_RingMonHandle monHandle, uint16_t ringMonNum)
	UDMA ring monitor allocation API. More...

int32_t	Udma_ringMonFree (Udma_RingMonHandle monHandle)
	UDMA free ring monitor. More...

int32_t	Udma_ringMonConfig (Udma_RingMonHandle monHandle, const Udma_RingMonPrms *monPrms)
	UDMA ring monitor configure API. More...

int32_t	Udma_ringMonGetData (Udma_RingMonHandle monHandle, Udma_RingMonData *monData)
	UDMA ring monitor get data API. More...

uint16_t	Udma_ringMonGetNum (Udma_RingMonHandle monHandle)
	Returns the ring monitor number. More...

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

void	UdmaRingMonPrms_init (Udma_RingMonPrms *monPrms)
	Udma_RingMonPrms 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_MON_INVALID (UDMA_RING_INVALID)
	Macro used to specify that ring monitor ID is invalid. Used in the API Udma_ringMonGetNum. More...

#define	UDMA_RING_MON_ANY (UDMA_RING_ANY)
	Macro used to specify any available ring monitor while requesting one. Used in the API Udma_ringMonAlloc. 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_MON_INVALID

#define UDMA_RING_MON_INVALID (UDMA_RING_INVALID)

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

◆ UDMA_RING_MON_ANY

#define UDMA_RING_MON_ANY (UDMA_RING_ANY)

Macro used to specify any available ring monitor while requesting one. Used in the API Udma_ringMonAlloc.

◆ 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.

Requirement: TODO

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.

Requirement: TODO

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 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 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.
phyDescMem	[IN] Descriptor memory physical pointer to push to 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: 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.

Requirement: TODO

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_ringMonAlloc()

int32_t Udma_ringMonAlloc	(	Udma_DrvHandle	drvHandle,
		Udma_RingMonHandle	monHandle,
		uint16_t	ringMonNum
	)

UDMA ring monitor allocation API.

Requirement: DOX_REQ_TAG(PDK-3584)

Parameters

drvHandle	[IN] UDMA driver handle pointer passed during Udma_init
monHandle	[IN/OUT] UDMA ring monitor 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.
ringMonNum	[IN] Ring monitor number. If set to UDMA_RING_MON_ANY, will allocate from pool. Else will try to allocate the mentioned ring monitor itself.

Returns: Udma_ErrorCodes

◆ Udma_ringMonFree()

int32_t Udma_ringMonFree ( Udma_RingMonHandle monHandle )

UDMA free ring monitor.

Freeup the ring monitor resources.

Requirement: DOX_REQ_TAG(PDK-3584)

Parameters

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

Returns: Udma_ErrorCodes

◆ Udma_ringMonConfig()

int32_t Udma_ringMonConfig	(	Udma_RingMonHandle	monHandle,
		const Udma_RingMonPrms *	monPrms
	)

UDMA ring monitor configure API.

Requirement: DOX_REQ_TAG(PDK-3584)

Parameters

monHandle	[IN] UDMA ring monitor handle. This parameter can't be NULL.
monPrms	[IN] Pointer to Udma_RingMonPrms structure.

Returns: Udma_ErrorCodes

◆ Udma_ringMonGetData()

int32_t Udma_ringMonGetData	(	Udma_RingMonHandle	monHandle,
		Udma_RingMonData *	monData
	)

UDMA ring monitor get data API.

Note: Reading the monitor register clears the read only counters.

Requirement: DOX_REQ_TAG(PDK-3584)

Parameters

monHandle	[IN] UDMA ring monitor handle. This parameter can't be NULL.
monData	[IN] Pointer to Udma_RingMonData structure.

Returns: Udma_ErrorCodes

◆ Udma_ringMonGetNum()

uint16_t Udma_ringMonGetNum ( Udma_RingMonHandle monHandle )

Returns the ring monitor number.

Requirement: DOX_REQ_TAG(PDK-3584)

Parameters

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

Returns: The ring monitor number on success or UDMA_RING_MON_INVALID on error

◆ UdmaRingPrms_init()

void UdmaRingPrms_init ( Udma_RingPrms * ringPrms )

Udma_RingPrms structure init function.

Parameters

ringPrms [IN] Pointer to Udma_RingPrms structure.

◆ UdmaRingMonPrms_init()

void UdmaRingMonPrms_init ( Udma_RingMonPrms * monPrms )

Udma_RingMonPrms structure init function.

Parameters

monPrms [IN] Pointer to Udma_RingMonPrms structure.

Introduction

Files

Data Structures

Functions

Macros

UDMA Ring element size

Macro Definition Documentation

◆ UDMA_RING_INVALID

◆ UDMA_RING_ANY

◆ UDMA_RING_MON_INVALID

◆ UDMA_RING_MON_ANY

◆ 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_ringSetDoorBell()

◆ Udma_ringGetNum()

◆ Udma_ringGetMemPtr()

◆ Udma_ringMonAlloc()

◆ Udma_ringMonFree()

◆ Udma_ringMonConfig()

◆ Udma_ringMonGetData()

◆ Udma_ringMonGetNum()

◆ UdmaRingPrms_init()

◆ UdmaRingMonPrms_init()