PSDK QNX API Guide
UDMA Driver Ring 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...
 

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

Variables

void * Udma_RingPrms::ringMem
 
uint32_t Udma_RingPrms::ringMemSize
 
uint8_t Udma_RingPrms::mode
 
uint16_t Udma_RingPrms::virtId
 
uint32_t Udma_RingPrms::elemCnt
 
uint8_t Udma_RingPrms::elemSize
 
uint8_t Udma_RingPrms::orderId
 
uint8_t Udma_RingPrms::asel
 
uint32_t Udma_RingPrms::mappedRingGrp
 
uint32_t Udma_RingPrms::mappedChNum
 
uint8_t Udma_RingMonPrms::source
 
uint8_t Udma_RingMonPrms::mode
 
uint16_t Udma_RingMonPrms::ringNum
 
uint32_t Udma_RingMonPrms::data0
 
uint32_t Udma_RingMonPrms::data1
 
uint32_t Udma_RingMonData::data0
 
uint32_t Udma_RingMonData::data1
 
Udma_DrvHandle Udma_RingHandle::drvHandle
 
uint16_t Udma_RingHandle::ringNum
 
uint32_t Udma_RingHandle::ringInitDone
 
uint32_t Udma_RingHandle::mappedRingGrp
 
uint32_t Udma_RingHandle::mappedChNum
 
Udma_DrvHandle Udma_RingMonHandle::drvHandle
 
uint16_t Udma_RingMonHandle::ringMonNum
 
uint32_t Udma_RingMonHandle::ringMonInitDone
 

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.

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...
 
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...
 
int32_t UdmaRingPrms_init (Udma_RingPrms *ringPrms)
 Udma_RingPrms structure init function. More...
 
int32_t UdmaRingMonPrms_init (Udma_RingMonPrms *monPrms)
 Udma_RingMonPrms structure init function. More...
 
int32_t Udma_ringProxyQueueRaw (Udma_RingHandle ringHandle, Udma_DrvHandle drvHandle, uint64_t phyDescMem)
 
int32_t Udma_ringProxyDequeueRaw (Udma_RingHandle ringHandle, Udma_DrvHandle drvHandle, uint64_t *phyDescMem)
 
#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...
 

Detailed Description

This is UDMA driver ring related configuration parameters and API

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

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

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_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

◆ Udma_ringMonAlloc()

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

UDMA ring monitor allocation API.

Note: In case of devices like AM64x where there is no ring monitor, this API is not supported and will return error.

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.

Note: In case of devices like AM64x where there is no ring monitor, this API is not supported and will return error.

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.

Note: In case of devices like AM64x where there is no ring monitor, this API is not supported and will return error.

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.

Note: In case of devices like AM64x where there is no ring monitor, this API is not supported and will return error.

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)

Note: In case of devices like AM64x where there is no ring monitor, this API is will always return UDMA_RING_MON_INVALID.

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

int32_t UdmaRingPrms_init ( Udma_RingPrms ringPrms)

Udma_RingPrms structure init function.

Parameters
ringPrms[IN] Pointer to Udma_RingPrms structure.
Returns
UDMA_SOK on success or UDMA_EINVALID_PARAMS on error

◆ UdmaRingMonPrms_init()

int32_t UdmaRingMonPrms_init ( Udma_RingMonPrms monPrms)

Udma_RingMonPrms structure init function.

Parameters
monPrms[IN] Pointer to Udma_RingMonPrms structure.
Returns
UDMA_SOK on success or UDMA_EINVALID_PARAMS on error

◆ Udma_ringProxyQueueRaw()

int32_t Udma_ringProxyQueueRaw ( Udma_RingHandle  ringHandle,
Udma_DrvHandle  drvHandle,
uint64_t  phyDescMem 
)

◆ Udma_ringProxyDequeueRaw()

int32_t Udma_ringProxyDequeueRaw ( Udma_RingHandle  ringHandle,
Udma_DrvHandle  drvHandle,
uint64_t *  phyDescMem 
)

Variable Documentation

◆ ringMem

void* Udma_RingPrms::ringMem

Pointer to ring memory. Incase of FQ and CQ rings, this cannot be NULL except for DRU direct TR mode where the rings are not used. Incase of TD CQ, this can be NULL when TD response is supressed via supressTdCqPkt channel parameter. Note: This is a virtual pointer.

◆ ringMemSize

uint32_t Udma_RingPrms::ringMemSize

Size of the memory in bytes allocated. This is used by the driver to validate the allocated memory is sufficient or not.

Note: By default this parameter will be set to UDMA_RING_SIZE_CHECK_SKIP by UdmaRingPrms_init API to enable backward combatibility when this is not set rightly by the caller

◆ mode [1/2]

uint8_t Udma_RingPrms::mode

Ring mode. Refer tisci_msg_rm_ring_cfg_req::mode

◆ virtId

uint16_t Udma_RingPrms::virtId

Ring virt ID. Refer tisci_msg_rm_ring_cfg_req::virtid

◆ elemCnt

uint32_t Udma_RingPrms::elemCnt

Ring element count. Set to queue depth of the ring. Set to 0 for DRU direct TR mode.

◆ elemSize

uint8_t Udma_RingPrms::elemSize

Ring element size. Refer Udma_RingElemSize for supported values.

◆ orderId

uint8_t Udma_RingPrms::orderId

Ring bus order ID value to be programmed into the orderid field of the ring's RING_ORDERID register.

◆ asel

uint8_t Udma_RingPrms::asel

Ring ASEL (address select) value to be set into the ASEL field of the ring's RING_BA_HI register. Refer Udma_RingAccAselEndpointSoc for supported values. This field is not supported on some SoCs.
On SoCs that do not support this field the input is quietly ignored. Note: By default this parameter will be set to #UDMA_RINGACC_ASEL_ENDPOINT_PHYSADDR by UdmaRingPrms_init API

◆ mappedRingGrp [1/2]

uint32_t Udma_RingPrms::mappedRingGrp

The Mapped ring group to use when channel type is UDMA_CH_TYPE_TX_MAPPED or UDMA_CH_TYPE_RX_MAPPED.

Refer Udma_MappedTxGrpSoc macro for details about mapped TX ring groups or Udma_MappedRxGrpSoc macro for details about mapped RX ring groups.

For unmapped case, set to UDMA_MAPPED_GROUP_INVALID

◆ mappedChNum [1/2]

uint32_t Udma_RingPrms::mappedChNum

The assigned mapped channel number when channel type is UDMA_CH_TYPE_TX_MAPPED or UDMA_CH_TYPE_RX_MAPPED.

This is used to allocate the corresponding mapped ring for the particular channel. RM will derive an intersecting pool based on the rings reserved for the core (in rmcfg) and the permissible range for the given channel(rings reserved for specific channels) such that the allocated ring will be from this intersecting pool.

For example, If the rings idx reserved for the core are 10 to 20 and the rings for the channel are 15 to 25. Then the intersecting pool of ring idx will be 15 - 20 and rm will allocate from this range.

◆ source

uint8_t Udma_RingMonPrms::source

Ring monitor source. Refer tisci_msg_rm_ring_mon_cfg_req::source

◆ mode [2/2]

uint8_t Udma_RingMonPrms::mode

Ring monitor mode. Refer tisci_msg_rm_ring_mon_cfg_req::mode

◆ ringNum [1/2]

uint16_t Udma_RingMonPrms::ringNum

Ring or queue to monitor.

◆ data0 [1/2]

uint32_t Udma_RingMonPrms::data0

When mode is TISCI_MSG_VALUE_RM_MON_MODE_PUSH_POP, this is read-only and represents number of pushes. When mode is TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD, this is read-write and represents the low threshold value which should be programmed to generate the RM event when the threshold is crossed (goes below). When mode is TISCI_MSG_VALUE_RM_MON_MODE_WATERMARK, this is read only and represents the low watermark. When mode is TISCI_MSG_VALUE_RM_MON_MODE_STARVATION, this is read only and represents the starvation count

◆ data1 [1/2]

uint32_t Udma_RingMonPrms::data1

When mode is TISCI_MSG_VALUE_RM_MON_MODE_PUSH_POP, this is read-only and represents number of pops. When mode is TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD, this is read-write and represents the high threshold value which should be programmed to generate the RM event when the threshold is crossed (goes above). When mode is TISCI_MSG_VALUE_RM_MON_MODE_WATERMARK, this is read only and represents the high watermark. When mode is TISCI_MSG_VALUE_RM_MON_MODE_STARVATION, this is not applicable

◆ data0 [2/2]

uint32_t Udma_RingMonData::data0

When mode is TISCI_MSG_VALUE_RM_MON_MODE_PUSH_POP, this is read-only and represents number of pushes. When mode is TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD, this is read-write and represents the low threshold value which should be programmed to generate the RM event when the threshold is crossed (goes below). When mode is TISCI_MSG_VALUE_RM_MON_MODE_WATERMARK, this is read only and represents the low watermark. When mode is TISCI_MSG_VALUE_RM_MON_MODE_STARVATION, this is read only and represents the starvation count

◆ data1 [2/2]

uint32_t Udma_RingMonData::data1

When mode is TISCI_MSG_VALUE_RM_MON_MODE_PUSH_POP, this is read-only and represents number of pops. When mode is TISCI_MSG_VALUE_RM_MON_MODE_THRESHOLD, this is read-write and represents the high threshold value which should be programmed to generate the RM event when the threshold is crossed (goes above). When mode is TISCI_MSG_VALUE_RM_MON_MODE_WATERMARK, this is read only and represents the high watermark. When mode is TISCI_MSG_VALUE_RM_MON_MODE_STARVATION, this is not applicable

◆ drvHandle [1/2]

Udma_DrvHandle Udma_RingHandle::drvHandle

Pointer to global driver handle.

◆ ringNum [2/2]

uint16_t Udma_RingHandle::ringNum

Ring number

◆ ringInitDone

uint32_t Udma_RingHandle::ringInitDone

Flag to set the ring object is init.

◆ mappedRingGrp [2/2]

uint32_t Udma_RingHandle::mappedRingGrp

The allocated mapped ring group when channel type is UDMA_CH_TYPE_TX_MAPPED or UDMA_CH_TYPE_RX_MAPPED.

This is needed to free the mapped ring.

Refer Udma_MappedTxGrpSoc macro for details about mapped TX ring groups or Udma_MappedRxGrpSoc macro for details about mapped RX ring groups.

For unmapped case, this will be UDMA_MAPPED_GROUP_INVALID

◆ mappedChNum [2/2]

uint32_t Udma_RingHandle::mappedChNum

The assigned mapped channel number when channel type is UDMA_CH_TYPE_TX_MAPPED or UDMA_CH_TYPE_RX_MAPPED.

This is needed to free the mapped ring.

For unmapped case, this will be UDMA_DMA_CH_INVALID.

◆ drvHandle [2/2]

Udma_DrvHandle Udma_RingMonHandle::drvHandle

Pointer to global driver handle.

◆ ringMonNum

uint16_t Udma_RingMonHandle::ringMonNum

Ring number

◆ ringMonInitDone

uint32_t Udma_RingMonHandle::ringMonInitDone

Flag to set the ring monitor object is init.