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/SYSFW 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... | |
#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.
#define UDMA_RING_ANY ((uint16_t) 0xFFFEU) |
Macro used to specify any available free ring while requesting one. Used in the API Udma_ringAlloc.
#define UDMA_RING_VIRTID_INVALID ((uint16_t) 0xFFFFU) |
Macro used to specify that ring virt ID is invalid. Used in the API Udma_ringAlloc.
#define UDMA_RING_SIZE_CHECK_SKIP (0xABDCABCDU) |
Macro used to skip the ring size check by driver.
#define UDMA_RING_ORDERID_MAX (0x0FU) |
Macro used to specificy the maximum ring order id value.
#define UDMA_RING_ES_4BYTES ((uint8_t) 0x00U) |
4 bytes Element size
#define UDMA_RING_ES_8BYTES ((uint8_t) 0x01U) |
8 bytes Element size
#define UDMA_RING_ES_16BYTES ((uint8_t) 0x02U) |
16 bytes Element size
#define UDMA_RING_ES_32BYTES ((uint8_t) 0x03U) |
32 bytes Element size
#define UDMA_RING_ES_64BYTES ((uint8_t) 0x04U) |
64 bytes Element size
#define UDMA_RING_ES_128BYTES ((uint8_t) 0x05U) |
128 bytes Element size
#define UDMA_RING_ES_256BYTES ((uint8_t) 0x06U) |
256 bytes Element size
int32_t Udma_ringAlloc | ( | Udma_DrvHandle | drvHandle, |
Udma_RingHandle | ringHandle, | ||
uint16_t | ringNum, | ||
const Udma_RingPrms * | ringPrms | ||
) |
UDMA ring allocation and configuration API.
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. |
int32_t Udma_ringFree | ( | Udma_RingHandle | ringHandle | ) |
UDMA free ring.
Freeup the ring resources.
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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/SYSFW 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)
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 SYSFW board config. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
phyDescMem | [IN] Descriptor memory physical pointer to push to the ring. |
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)
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. |
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)
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. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
phyDescMem | [IN] Descriptor memory physical pointer to push to the ring. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
phyDescMem | [IN] Descriptor memory physical pointer to pop from the ring. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
count | [IN] Number of count to commit. |
uint16_t Udma_ringGetNum | ( | Udma_RingHandle | ringHandle | ) |
Returns the ring number allocated for this ring.
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
void* Udma_ringGetMemPtr | ( | Udma_RingHandle | ringHandle | ) |
Returns the ring memory pointer which is passed during ring alloc.
Requirement: DOX_REQ_TAG(PDK-3668)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
uint32_t Udma_ringGetMode | ( | Udma_RingHandle | ringHandle | ) |
Returns the ring mode which is configured during ring alloc.
Requirement: DOX_REQ_TAG(PDK-5665)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
uint32_t Udma_ringGetElementCnt | ( | Udma_RingHandle | ringHandle | ) |
Returns the ring element count which is passed during ring alloc.
Requirement: DOX_REQ_TAG(PDK-5665)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
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)
ringHandle | [IN] UDMA ring handle. This parameter can't be NULL. |
void UdmaRingPrms_init | ( | Udma_RingPrms * | ringPrms | ) |
Udma_RingPrms structure init function.
ringPrms | [IN] Pointer to Udma_RingPrms structure. |