UDMA

The UDMA driver provides API to program the DMA module of the DMSS subsystem to setup and initiate DMA transfers.

Features Supported 

Supports both BCDMA and Packet DMA instances

Supports all DMA operations from both instances from all the cores in the SOC except M4F core

UDMA block copy for memory to memory transfer
PDMA module to initiate transfers to/from PDMA peripherals like UART, McASP, McSPI, ADC, MCAN
DMA transfer to/from from native PSIL peripherals like CPSW, SA2UL

Event and interrupt management like DMA completion, channel chaining, interrupt sharing using Interrupt Aggregator (IA)
Resources management across instances and cores for DMA channels, RX flow, Interrupt Aggregator (IA), Interrupt Routers (IR), Global events, Ring Accelerator (RA)
Interaction with DMSC RM module via SCICLIENT for all non-RealTime (NRT) configuration

Supports direct TR mode for DRU

It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

Selection of UDMA instances - BCDMA, PKTDMA
Option to skip default global event registration done as part of Udma_init API
Option to provide user function for virtual to physical and physical to virtual address translation
Ability of add and configure BCDMA block copy channels
- Ability to enable interrupt mode for the channel
- Ability to specify the number of ring entries for the channel
- Based on above parameters, the SysConfig generated code does below as part of Drivers_open and Drivers_close functions
  - Channel open/close - the handle can be retrieved by the application using g<User_Config_Name>BlkCopyChHandle global variable
  - Set default channel configuration
  - Allocates required ring memories and pass them to channel configuration
  - Register user specified callback when interrupt mode is enabled

Features NOT Supported 

UDMA driver is not supported for M4F core as the DMSS is present only in the main domain

LEVI and MCMAP features are not supported in UDMA driver.

UDMA driver does not support UDMA-C channel type for DRU

Failure Prevention Guidelines for Applications 

Application developer must take care of the following guidelines to avoid failures:

The application developer need to ensure proper configuration of transfer request parameters to prevent invalid memory access, data inconsistencies, and unexpected system behaviour.
The application developer need to ensure that the proper descriptor type is configured in the transfer request (TR) parameters before initiating a UDMA data transfer.
The application developer needs to make sure that the source and destination buffers are cache line aligned and cache operations are performed to maintain coherency.
The application developer must carefully configure ICNT parameters (ICNT0/ICNT1/ICNT2) to match data block size. Ensure proper alignment of source and destination buffers and validate ICNT values across channels.
The application developer needs to ensure that the source/destination PSIL thread configured corresponds to the peripheral they want to transfer the data.

Important Usage Guidelines 

UDMA driver doesn’t manage/allocate the descriptor and RA memory. The caller need to allocate and provide the required memory.
UDMA driver doesn’t use any global variables. All the required object memory like channel, driver instance, event etc should be allocated by the caller

DMSS Overview 

The primary goal of the Data Movement Subsystem (DMSS) is to ensure that data can be efficiently transferred from a producer to a consumer so that the real time requirements of the system can be met. The Data Movement architecture aims to facilitate Direct Memory Access (DMA) and to provide a consistent Application Programming Interface (API) to the host software. Data movement tasks are commonly offloaded from the host processor to peripheral hardware to increase system performance. Significant performance gains may result from careful design of the interface between the host software and the underlying acceleration hardware. In networking applications packet transmission and reception are critical tasks. In general purpose compute, ping pong buffer pre-fetch and store are critical tasks as are general misaligned block copy operations.

The block diagram provides a high level picture of not only the 2 different interconnect fabrics but also some key standard data movement components that have been defined and placed in the various parts of the low cost compliant SoC. Packet DMA (PKTDMA) and Block Copy DMA (BCDMA) which are the two instances of the DMSS specification serving different use cases. DMSS Block Diagram

Packet DMA (PKTDMA)

The PKTDMA is intended to perform similar functions as the packet oriented DMA. The PKTDMA module supports the transmission and reception of various packet types. The PKTDMA is architected to facilitate the segmentation and reassembly of DMA data structure compliant packets to/from smaller data blocks that are natively compatible with the specific requirements of each connected peripheral. Multiple TX and RX channels are provided within the DMA which allow multiple segmentation or reassembly operations to be ongoing. The DMA controller maintains state information for each of the channels which allows packet segmentation and reassembly operations to be time division multiplexed between channels in order to share the underlying DMA hardware. An internal DMA scheduler is used to control the ordering and rate at which this multiplexing occurs for Transmit operations. The ordering and rate of Receive operations is indirectly controlled by the order in which blocks are pushed into the DMA on the RX PSI-L interface. Packet DMA Block Diagram

Block Copy DMA (BCDMA)

The Block Copy DMA is intended to perform similar functions as the EDMA or the UDMA-P/UTC. The BCDMA module moves data from a memory mapped source address set to a corresponding memory mapped address set. The BCDMA maintains state information for each of the channels which allows data copy operations to be time division multiplexed between channels in order to share the underlying DMA hardware. An internal DMA scheduler is used to control the ordering and rate at which this multiplexing occurs. Block Copy DMA Block Diagram

DMSS Transfer Overciew 

Below section describes the high level flow of the driver for the data transfer

Transfer Request (TR) Record 

Transfer configuration is specified in the TR record. Size of TR is variable from 16 bytes to 64 bytes. Specified via TR Type in FLAGS field TR record fields

Below table summarizes different TR types and the transfer type for which they are used

TR Type	Descriptrion
Type 0	1D (word0-3)
Type 1	2D (word0-4)
Type 2	3D (word0-6)
Type 3	4D (word0-8)
Type 5	Cache warm (word0-15) (MSMC DRU ONLY)
Type 8	4D Block Copy (word0-15)
Type 9	4D Block Copy with reformatting (word0-15) (MSMC DRU ONLY)
Type 10	2D Block Copy (word0-15)
Type 11	2D Block Copy with reformatting (word0-15) (MSMC DRU ONLY)
Type 15	4D Block Copy with reformatting and indirection (word0-15) (MSMC DRU ONLY)

UDMA Setup/Flow 

Below diagram shows the high level flow for the transfer requests from application and driver UDMA setup TRPD flow

Below diagram shows the UDMA transfer API flow UDMA API flow

Timeout 

The UDMA driver provides configurable timeout for channel disable and uses SystemP_WAIT_FOREVER for internal resource management.

Configurable Timeout 

The channel disable timeout is configurable via the timeout parameter of Udma_chDisable, as shown below:

/* Disable channel with a 1000 OS tick timeout */
retVal = Udma_chDisable(chHandle, 1000U);

/* Disable channel with no timeout (wait forever) */
retVal = Udma_chDisable(chHandle, SystemP_WAIT_FOREVER);

When to change: Set a finite timeout when disabling a channel as part of error recovery or cleanup. If a DMA transfer is stalled due to a bus hang or misconfigured descriptor, SystemP_WAIT_FOREVER will block the calling task indefinitely.

Non-Configurable Timeouts 

The following operations always use SystemP_WAIT_FOREVER and cannot be overridden by the application:

Resource manager locks — Mutexes protecting channel and ring resource allocation. These wait forever if another task is currently allocating or freeing UDMA resources.
SciClient communications — TISCI messages to the DMSS firmware always use SystemP_WAIT_FOREVER.

Example Usage 

Include the below file to access the APIs 

#include <stdio.h>
#include <drivers/udma.h>

Channel Open Example 

    int32_t         retVal;
    Udma_ChHandle   chHandle = (Udma_ChHandle) &gUdmaChObj;
    uint32_t        chType;
    Udma_ChPrms     chPrms;
    Udma_ChTxPrms   txPrms;
    Udma_ChRxPrms   rxPrms;

    chType = UDMA_CH_TYPE_TR_BLK_COPY;
    UdmaChPrms_init(&chPrms, chType);
    chPrms.fqRingPrms.ringMem       = &gTxRingMem[0U];
    chPrms.fqRingPrms.elemCnt       = 1;
    chPrms.fqRingPrms.ringMemSize   = chPrms.fqRingPrms.elemCnt * sizeof(uint64_t);
    retVal = Udma_chOpen(drvHandle, chHandle, chType, &chPrms);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA channel open failed!!\r\n");
    }

    /* Config TX channel */
    UdmaChTxPrms_init(&txPrms, chType);
    retVal = Udma_chConfigTx(chHandle, &txPrms);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA TX channel config failed!!\r\n");
    }

    /* Config RX channel - which is implicitly paired to TX channel in
     * block copy mode */
    UdmaChRxPrms_init(&rxPrms, chType);
    retVal = Udma_chConfigRx(chHandle, &rxPrms);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA RX channel config failed!!\r\n");
    }

    /* Channel enable */
    retVal = Udma_chEnable(chHandle);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA channel enable failed!!\r\n");
    }

Channel Close Example 

    int32_t         retVal;
    Udma_ChHandle   chHandle = (Udma_ChHandle) &gUdmaChObj;

    retVal = Udma_chDisable(chHandle, UDMA_DEFAULT_CH_DISABLE_TIMEOUT);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA channel disable failed!!\r\n");
    }

    retVal = Udma_chClose(chHandle);
    if(UDMA_SOK != retVal)
    {
        printf("[Error] UDMA channel close failed!!\r\n");
    }

API Reference 

UDMA Driver API/interface file.

Requirement: DOX_REQ_TAG(PDK-2494)

Typedefs

typedef uint64_t (*Udma_VirtToPhyFxn)(const void *virtAddr, uint32_t chNum, void *appData)

UDMA Virtual to Physical address translation callback function.

This function is used by the driver to convert virtual address to physical address.

Param virtAddr:: [IN] Virtual address
Param chNum:: [IN] Channel number passed during channel open
Param appData:: [IN] Callback pointer passed during channel open
Return:: Corresponding physical address

typedef void *(*Udma_PhyToVirtFxn)(uint64_t phyAddr, uint32_t chNum, void *appData)

UDMA Physical to Virtual address translation callback function.

This function is used by the driver to convert physical address to virtual address.

Param phyAddr:: [IN] Physical address
Param chNum:: [IN] Channel number passed during channel open
Param appData:: [IN] Callback pointer passed during channel open
Return:: Corresponding virtual address

Functions

int32_t Udma_init(Udma_DrvHandle drvHandle, const Udma_InitPrms *initPrms)

UDMA init function.

Initializes the UDMA drivers. This function should be called before calling any of driver API’s and should be called only once.

Requirement: DOX_REQ_TAG(PDK-2576)

Parameters:

drvHandle – [IN] UDMA driver handle - static memory needs to allocated by caller. This is used by the driver to maintain the driver states. This cannot be NULL.
initPrms – [IN] UDMA Initialization parameters. If NULL is passed, the default parameters will be assumed - address translation disabled.

Returns:

Udma_ErrorCodes

int32_t Udma_deinit(Udma_DrvHandle drvHandle)

UDMA deinit function.

Uninitializes the drivers and the hardware and should be called during system shutdown. Should not be called if Udma_init() is not called.

Requirement: DOX_REQ_TAG(PDK-2577)

Parameters:: drvHandle – [IN] UDMA driver handle pointer passed during Udma_init
Returns:: Udma_ErrorCodes

int32_t UdmaInitPrms_init(uint32_t instId, Udma_InitPrms *initPrms)

Udma_InitPrms structure init function.

Note: API returns error when there is a failure in intilaizing RM parameters. This can be due to the following reasons:

Wrong entry for resources in Default Board Cfg (Sciclient_defaultBoardCfg_rm.c)
Number of resources reserved in Default Board Cfg is less than the ‘minumum requirement’ specified as per UDMA RM Shared resource parameters ref Udma_RmSharedResPrms. In this case, user should reserve more resources in Default Board Cfg OR override the default UDMA RM Shared resource parameters. (Use ref Udma_rmGetSharedResPrms API to get default UDMA RM Shared resource parameters)
Total number of resources requested for each instance as per UDMA RM Shared resource parameters is greater than the number of resorurces reserved in Default Board Cfg. In this case, user should reduce the requested share for each instance in UDMA RM Shared resource parameters.
In case of devices like AM62L sciclient/Boardcfg is not used and resources are managed by the driver.

Parameters:

instId – [IN] Udma_InstanceIdSoc
initPrms – [IN] Pointer to Udma_InitPrms structure.

Returns:

Udma_ErrorCodes

uint64_t Udma_defaultVirtToPhyFxn(const void *virtAddr, uint32_t chNum, void *appData)

Default virtual to physical translation function.

Parameters:

virtAddr – [IN] Virtual address
chNum – [IN] Channel number passed during channel open. Note: When called for functions which is not channel dependent (like ring alloc), this parameter will be set to UDMA_DMA_CH_INVALID.
appData – [IN] Callback pointer passed during channel open. Note: When called for functions which is not channel dependent (like ring alloc), this parameter will be set to NULL.

Returns:

Corresponding physical address

void *Udma_defaultPhyToVirtFxn(uint64_t phyAddr, uint32_t chNum, void *appData)

Default physical to virtual translation function.

Parameters:

phyAddr – [IN] Physical address
chNum – [IN] Channel number passed during channel open. Note: When called for functions which is not channel dependent (like ring alloc), this parameter will be set to UDMA_DMA_CH_INVALID.
appData – [IN] Callback pointer passed during channel open. Note: When called for functions which is not channel dependent (like ring alloc), this parameter will be set to NULL.

Returns:

Corresponding virtual address

struct Udma_InitPrms

#include <udma.h>

UDMA initialization parameters.

Requirement: DOX_REQ_TAG(PDK-2631)

Public Members

uint32_t instId: [IN] Udma_InstanceIdSoc

Udma_RmInitPrms rmInitPrms: RM init parameters

uint8_t enableUtc: Flag to indicate UTC being used

uint32_t skipGlobalEventReg: Skips the global event registeration for the handle. By default this is set to FALSE and application can use this common handle to set the master event to limit the number of IA/IR registration per core This can be set to TRUE to skip this registration as in the case of having multiple handles per core in usecases

Udma_VirtToPhyFxn virtToPhyFxn: If not NULL, this function will be called to convert virtual address to physical address to be provided to UDMA. If NULL, the driver will assume a one-one mapping.

Udma_PhyToVirtFxn phyToVirtFxn

If not NULL, this function will be called to convert physical address to virtual address to access the pointer returned by the UDMA. If NULL, the driver will assume a one-one mapping.

Note: The init fxn will initialize this to the default one-one map function Udma_defaultPhyToVirtFxn

struct Udma_DrvObject

#include <udma.h>

Opaque UDMA driver object.

Public Members

uintptr_t rsv[635U]: reserved, should NOT be modified by end users

UDMA Low Level Driver API/interface data types file.

UDMA Error Codes

Error codes returned by UDMA APIs

UDMA_SOK: API call successful.

UDMA_EFAIL: API call returned with error as failed. Used for generic error. It may be some hardware failure and/or software failure.

UDMA_EBADARGS: API call returned with error as bad arguments. Typically, NULL pointer passed to the API where its not expected.

UDMA_EINVALID_PARAMS: API call returned with error as invalid parameters. Typically when parameters passed are not valid or out of range.

UDMA_ETIMEOUT: API call returned with error as timed out. Typically API is waiting for some condition and returned as condition not happened in the timeout period.

UDMA_EALLOC: API call returned with error as allocation failed.

UDMA Instance ID

This represents the various Instances in an SOC. The actual Instances present in the chip is SOC dependent. Refer soc file for the actual instance present. Kindly use Udma_InstanceIdSoc macros for SOC specific name.

UDMA_INST_ID_0

UDMA_INST_ID_1

UDMA_INST_ID_2

UDMA_INST_ID_3

UDMA_INST_ID_4

UDMA_INST_ID_5

UDMA_INST_ID_6

UDMA UTC ID

This represents the various UTC IP in the SOC. The actual UTC present in the chip is SOC dependent. Refer soc file for the actual instance present.

UDMA_UTC_ID0

UDMA_UTC_ID1

UDMA_UTC_ID2

UDMA_UTC_ID3

UDMA_UTC_ID4

UDMA_UTC_ID5

UDMA_UTC_ID6

UDMA_UTC_ID7

UDMA_UTC_ID8

UDMA_UTC_ID9

UDMA Mapped Group

This represents the various Mapped TX & RX Channels/Rings in the SOC. The actual Mapped TX & RX groups present in the chip is SOC dependent. Refer soc file for the actual instance present. Kindly use Udma_MappedTxGrpSoc macros for Mapped TX SOC specific name and Udma_MappedRxGrpSoc macros for Mapped RX SOC specific name.

UDMA_MAPPED_GROUP0

UDMA_MAPPED_GROUP1

UDMA_MAPPED_GROUP2

UDMA_MAPPED_GROUP3

UDMA_MAPPED_GROUP4

UDMA_MAPPED_GROUP5

UDMA_MAPPED_GROUP6

UDMA_MAPPED_GROUP7

Defines

UDMA_CACHELINE_ALIGNMENT: Cache line size for alignment of descriptor and buffers.

UDMA_ALIGN_SIZE(x): Macro to align the size in bytes to UDMA cache line alignment.

UDMA_DEFAULT_CH_DISABLE_TIMEOUT: Default UDMA channel disable timeout.

Typedefs

typedef void *Udma_DrvHandle: UDMA driver handle.

typedef void *Udma_ChHandle: UDMA channel handle.

typedef void *Udma_EventHandle: UDMA event handle.

typedef void *Udma_RingHandle: UDMA ring handle.

typedef void *Udma_FlowHandle: UDMA flow handle.

UDMA Channel related parameters and API.

UDMA Channel Flag

UDMA channel flags bit field used to form the channel type.

UDMA_CH_FLAG_TX: TX channel flag.

UDMA_CH_FLAG_RX: RX channel flag.

UDMA_CH_FLAG_BLK_COPY: Block copy mode channel flag.

UDMA_CH_FLAG_PDMA: PDMA channel flag.

UDMA_CH_FLAG_PSIL: PSIL channel flag meant for periperals like Ethernet, SA2UL.

UDMA_CH_FLAG_UTC: UTC channel flag.

UDMA_CH_FLAG_HC: High capacity channel flag.

UDMA_CH_FLAG_UHC: Ultra high capacity channel flag.

UDMA_CH_FLAG_MAPPED: Mapped TX/RX channel flag.

UDMA_CH_FLAG_TR: TR mode channel flag.

UDMA Channel Type

UDMA channel type formed based on channel flags.

UDMA_CH_TYPE_TR_BLK_COPY: TR block copy type - TX/RX pair.

UDMA_CH_TYPE_TR_BLK_COPY_HC: High capacity TR block copy type - TX/RX pair.

UDMA_CH_TYPE_TR_BLK_COPY_UHC: Ultra high capacity TR block copy type - TX/RX pair.

UDMA_CH_TYPE_TX: TX channel type.

UDMA_CH_TYPE_TX_HC: High capacity TX channel type.

UDMA_CH_TYPE_TX_UHC: Ultra high capacity TX channel type.

UDMA_CH_TYPE_RX: RX channel type.

UDMA_CH_TYPE_RX_HC: High capacity RX channel type.

UDMA_CH_TYPE_RX_UHC: Ultra high capacity RX channel type.

UDMA_CH_TYPE_PDMA_TX: PDMA TX channel type.

UDMA_CH_TYPE_PDMA_TX_HC: High capacity PDMA TX channel type.

UDMA_CH_TYPE_PDMA_TX_UHC: Ultra high capacity PDMA TX channel type.

UDMA_CH_TYPE_PDMA_RX: PDMA RX channel type.

UDMA_CH_TYPE_PDMA_RX_HC: High capacity PDMA RX channel type.

UDMA_CH_TYPE_PDMA_RX_UHC: Ultra high capacity PDMA RX channel type.

UDMA_CH_TYPE_TX_TR: TX channel type.

UDMA_CH_TYPE_TX_HC_TR: High capacity TX channel type.

UDMA_CH_TYPE_TX_UHC_TR: Ultra high capacity TX channel type.

UDMA_CH_TYPE_RX_TR: RX channel type.

UDMA_CH_TYPE_RX_HC_TR: High capacity RX channel type.

UDMA_CH_TYPE_RX_UHC_TR: Ultra high capacity RX channel type.

UDMA_CH_TYPE_PDMA_TX_TR: PDMA TX channel type.

UDMA_CH_TYPE_PDMA_TX_HC_TR: High capacity PDMA TX channel type.

UDMA_CH_TYPE_PDMA_TX_UHC_TR: Ultra high capacity PDMA TX channel type.

UDMA_CH_TYPE_PDMA_RX_TR: PDMA RX channel type.

UDMA_CH_TYPE_PDMA_RX_HC_TR: High capacity PDMA RX channel type.

UDMA_CH_TYPE_PDMA_RX_UHC_TR: Ultra high capacity PDMA RX channel type.

UDMA_CH_TYPE_TX_MAPPED: Mapped TX channel. This could be different type of mapped TX channels. See Udma_MappedTxGrpSoc for differnt types of SOC specific mapped TX channels.

UDMA_CH_TYPE_RX_MAPPED: Mapped RX channel. This could be different type of mapped RX channels. See Udma_MappedRxGrpSoc for differnt types of SOC specific mapped RX channels.

UDMA_CH_TYPE_UTC

UTC channel. This could be.

UTC with descriptor posted through UDMA external channel like VPAC/DMPAC
DRU channel with direct mode with descriptor posted through direct DRU register writes or with indirect mode through External channel

UDMA PDMA element size

UDMA_PDMA_ES_8BITS

UDMA_PDMA_ES_16BITS

UDMA_PDMA_ES_24BITS

UDMA_PDMA_ES_32BITS

UDMA_PDMA_ES_64BITS

UDMA_PDMA_ES_DONTCARE: Set this for MCAN element size - not applicable.

Defines

UDMA_DMA_CH_INVALID: Macro used to specify that DMA Channel ID is invalid. Used in the API Udma_chOpen.

UDMA_DMA_CH_ANY: Macro used to specify any available DMA Channel while requesting one. Used in the API Udma_chOpen.

UDMA_DMA_CH_NA: Macro used to specify that the DMA Channel is not applicable for a particular mode.

UDMA_UTC_ID_INVALID: Macro used to specify that the UTC ID is invalid.

UDMA_MAPPED_GROUP_INVALID: Macro used to specify that the Mapped Channel Group is invalid.

UDMA_SYSFW_EXTENDED_CH_TYPE_BCDMA_BLK_CPY: SYSFW Extended Channel Type Flag for BCDMA Block Copy.

UDMA_SYSFW_EXTENDED_CH_TYPE_BCDMA_SPLIT_TR_TX: SYSFW Extended Channel Type Flag for BCDMA split TR TX channels.

UDMA_DRV_CH_OBJ_SIZE

Functions

int32_t Udma_chOpen(Udma_DrvHandle drvHandle, Udma_ChHandle chHandle, uint32_t chType, const Udma_ChPrms *chPrms)

UDMA open channel.

Opens the UDMA channel based on the channel parameters. This also does the PSILCFG pairing based on the peer thread ID provided.

Requirement: DOX_REQ_TAG(PDK-2578)

Parameters:

drvHandle – [IN] UDMA driver handle pointer passed during Udma_init
chHandle – [IN/OUT] UDMA channel 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. This parameter can’t be NULL.
chType – [IN] UDMA channel type. Refer Udma_ChType.
chPrms – [IN] UDMA channel parameters. This parameter can’t be NULL.

Returns:

Udma_ErrorCodes

int32_t Udma_chClose(Udma_ChHandle chHandle)

UDMA close channel.

Closes the UDMA channel and frees all associated resources.

Requirement: DOX_REQ_TAG(PDK-2579)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Udma_ErrorCodes

int32_t Udma_chConfigTx(Udma_ChHandle chHandle, const Udma_ChTxPrms *txPrms)

UDMA configure TX channel.

Configures the TX channel parameters. Note: This is applicable only when the channel type is TX

Note: This API can’t be called after channel enable.

Requirement: DOX_REQ_TAG(PDK-2580)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
txPrms – [IN] UDMA TX channel parameter. Refer Udma_ChTxPrms.

Returns:

Udma_ErrorCodes

int32_t Udma_chConfigRx(Udma_ChHandle chHandle, const Udma_ChRxPrms *rxPrms)

UDMA configure RX channel.

Configures the RX channel parameters. Note: This is applicable only when the channel type is RX In case of BCDMA Block Copy, there is no need to configure RX Channel. Therfore the function returns gracefully, without doing anything.

Note: This API can’t be called after channel enable.

Requirement: DOX_REQ_TAG(PDK-2581)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
rxPrms – [IN] UDMA RX channel parameter. Refer Udma_ChRxPrms.

Returns:

Udma_ErrorCodes

int32_t Udma_chConfigUtc(Udma_ChHandle chHandle, const Udma_ChUtcPrms *utcPrms)

UDMA configure UTC channel.

Configures the UTC channel parameters. Note: This is applicable only when the channel type is UTC

Note: This API can’t be called after channel enable.

Requirement: DOX_REQ_TAG(PDK-2582)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
utcPrms – [IN] UDMA UTC channel parameter. Refer Udma_ChUtcPrms.

Returns:

Udma_ErrorCodes

int32_t Udma_chConfigPdma(Udma_ChHandle chHandle, const Udma_ChPdmaPrms *pdmaPrms)

UDMA configure PDMA channel (peerChNum as part of Udma_ChPrms) paired with the UDMAP channel.

This configures the PDMA channel static X,Y,Z parameters.

Requirement: DOX_REQ_TAG(PDK-2583)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
pdmaPrms – [IN] UDMA RX channel parameter. Refer Udma_ChPdmaPrms.

Returns:

Udma_ErrorCodes

int32_t Udma_chEnable(Udma_ChHandle chHandle)

UDMA channel enable API.

This function will enable the UDMA channel.

Requirement: DOX_REQ_TAG(PDK-2584)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Udma_ErrorCodes

int32_t Udma_chDisable(Udma_ChHandle chHandle, uint32_t timeout)

UDMA channel teardown and disable API.

This function will perform the channel teardown and eventually disables the UDMA channel. This initiates the force teardown sequence based on the channel type and wait for teardown to complete gracefully. If the teardown doesn’t complete within the timeout provided, then this will initiate a force teardown sequence.

Caution: This API is blocking. Hence cannot be called from ISR context!!

Requirement: DOX_REQ_TAG(PDK-2585)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
timeout – [IN] Timeout in ms. Use SystemP_WAIT_FOREVER to wait forever.

Returns:

Udma_ErrorCodes

int32_t Udma_chPause(Udma_ChHandle chHandle)

UDMA channel pause API.

This function will pause the UDMA channel by setting the pause bit of the UDMAP runtime register.

Requirement: DOX_REQ_TAG(PDK-2977)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Udma_ErrorCodes

int32_t Udma_chResume(Udma_ChHandle chHandle)

UDMA channel resume API.

This function will resume the UDMA channel by clearing the pause bit of the UDMAP runtime register.

Requirement: DOX_REQ_TAG(PDK-2977)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Udma_ErrorCodes

uint32_t Udma_chGetNum(Udma_ChHandle chHandle)

Returns the channel number offset with in a channel type - TX, RX and External (UTC) channel types.

In case of UTC type, this returns the relative offset from the start of UTC it belongs to (and not from the external channel start).

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Channel number. Returns UDMA_DMA_CH_INVALID for error.

Udma_RingHandle Udma_chGetFqRingHandle(Udma_ChHandle chHandle)

Returns the default free ring handle of the channel.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Free ring handle. Returns NULL for error.

Udma_RingHandle Udma_chGetCqRingHandle(Udma_ChHandle chHandle)

Returns the default completion ring handle of the channel.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Completion ring handle. Returns NULL for error.

Udma_RingHandle Udma_chGetTdCqRingHandle(Udma_ChHandle chHandle)

Returns the teardown completion ring handle of the channel.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Teardown completion ring handle. Returns NULL for error.

uint16_t Udma_chGetFqRingNum(Udma_ChHandle chHandle)

Returns the default free ring number to be programmed in descriptor.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Free ring number. Returns UDMA_RING_INVALID for error.

uint16_t Udma_chGetCqRingNum(Udma_ChHandle chHandle)

Returns the default completion ring number to be programmed in descriptor.

Requirement: DOX_REQ_TAG(PDK-2586)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Completion ring number. Returns UDMA_RING_INVALID for error.

Udma_FlowHandle Udma_chGetDefaultFlowHandle(Udma_ChHandle chHandle)

Returns the default flow handle of the RX channel.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Default flow handle. Returns NULL for error.

uint32_t Udma_chGetTriggerEvent(Udma_ChHandle chHandle, uint32_t trigger)

Returns the global trigger event for the channel.

This function will return the appropriate global 0/1 trigger event for the channel.

Notes: Trigger is not supported for external channels and the function will return UDMA_EVENT_INVALID.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
trigger – [IN] Global0 or Global 1 Trigger - refer CSL_UdmapTrFlagsTrigger

Returns:

Global trigger event

void *Udma_chGetSwTriggerRegister(Udma_ChHandle chHandle)

Returns the software trigger register address for the channel.

This function will return the appropriate SW trigger register. Incase of UDMAP channels, it returns the 32-bit TX SWTRIG register address. Incase of DRU channels, it returns the 64-bit DRU CHRT_SWTRIG register address.

Notes: SW trigger is not supported for RX channels. Incase of TX channels, only global trigger 0 is supported. Incase of DRU channels, global trigger 0/1 and local events are supported.

Requirement: DOX_REQ_TAG(PDK-2594)

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: SW trigger register address

int32_t Udma_chSetSwTrigger(Udma_ChHandle chHandle, uint32_t trigger)

Sets the software trigger register based on the trigger mode provided.

This function will set the appropriate SW trigger register. Incase of UDMAP channels, it will set in the TX SWTRIG register. Incase of DRU channels, it will set in the DRU CHRT_SWTRIG register.

Notes: SW trigger is not supported for RX channels. Incase of TX channels, only global trigger 0 is supported. Incase of DRU channels, global trigger 0/1 and local events are supported.

Requirement: DOX_REQ_TAG(PDK-2594)

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
trigger – [IN] Global0 or Global 1 Trigger - refer CSL_UdmapTrFlagsTrigger

Returns:

Udma_ErrorCodes

int32_t Udma_chSetChaining(Udma_ChHandle triggerChHandle, Udma_ChHandle chainedChHandle, uint32_t trigger)

Chains the trigger channel with the chained channel.

This programs the trigger channel TR event register (OES) to the global trigger (0 or 1) event of the chained channel.

Once this is done, the application should set the TR trigger (0 or 1) of the trigger channel while submitting TR to the trigger channel. Based on the trigger type (full, ICNT0, INCT1, ICNT3), the trigger channel will trigger the “chained” channel through the channel OES.

Note: Only global0 and global1 triggers are supported.

Parameters:

triggerChHandle – [IN] UDMA channel handle which triggers the chain. This parameter can’t be NULL.
chainedChHandle – [IN] UDMA channel handle which gets triggered. This parameter can’t be NULL.
trigger – [IN] Global0 or Global 1 Trigger - refer CSL_UdmapTrFlagsTrigger

Returns:

Udma_ErrorCodes

int32_t Udma_chBreakChaining(Udma_ChHandle triggerChHandle, Udma_ChHandle chainedChHandle)

Breaks the chaining by resetting the trigger channel’s OES.

Note: Only global0 and global1 triggers are supported.

Parameters:

triggerChHandle – [IN] UDMA channel handle which triggers the chain. This parameter can’t be NULL.
chainedChHandle – [IN] UDMA channel handle which gets triggered. This parameter can’t be NULL.

Returns:

Udma_ErrorCodes

void UdmaChPrms_init(Udma_ChPrms *chPrms, uint32_t chType)

Udma_ChPrms structure init function.

Parameters:

chPrms – [IN] Pointer to Udma_ChPrms structure.
chType – [IN] UDMA channel type. Refer Udma_ChType.

void UdmaChTxPrms_init(Udma_ChTxPrms *txPrms, uint32_t chType)

Udma_ChTxPrms structure init function.

Parameters:

txPrms – [IN] Pointer to Udma_ChTxPrms structure.
chType – [IN] UDMA channel type. Refer Udma_ChType.

void UdmaChRxPrms_init(Udma_ChRxPrms *rxPrms, uint32_t chType)

Udma_ChRxPrms structure init function.

Parameters:

rxPrms – [IN] Pointer to Udma_ChRxPrms structure.
chType – [IN] UDMA channel type. Refer Udma_ChType.

void UdmaChUtcPrms_init(Udma_ChUtcPrms *utcPrms)

Udma_ChUtcPrms structure init function.

Parameters:: utcPrms – [IN] Pointer to Udma_ChUtcPrms structure.

int32_t Udma_chRingQueueRaw(Udma_ChHandle chHandle, uint8_t *phyDescMem, uint64_t noEleCnt)

Queue TR into channels ring.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
phyDescMem – [IN] Pointer to transfer descriptor memory This parameter can’t be NULL.
noEleCnt – [IN] No of elements to be queued

Returns:

Udma_ErrorCodes

int32_t Udma_chRingRingDbRaw(Udma_ChHandle chHandle, uint64_t noOfEntries)

Ring Forward door bell.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
noOfEntries – [IN] No of valid entries queued in the ring

Returns:

Udma_ErrorCodes

int32_t Udma_chRingDeQueueRaw(Udma_ChHandle chHandle, uint64_t noElem, uint64_t *eleInRing)

De Queue elements from the ring.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
noElem – [IN] No of elements to be de queued
eleInRing – [OUT] Elements that are de queued

Returns:

Udma_ErrorCodes

int32_t Udma_chRingRingRvrDbRaw(Udma_ChHandle chHandle, uint64_t noOfEntries)

Ring Forward door bell.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
noOfEntries – [IN] No of valid entries queued in the ring

Returns:

Udma_ErrorCodes

void UdmaChPdmaPrms_init(Udma_ChPdmaPrms *pdmaPrms)

Udma_ChPdmaPrms structure init function.

Parameters:: pdmaPrms – [IN] Pointer to Udma_ChPdmaPrms structure.

int32_t Udma_chGetStats(Udma_ChHandle chHandle, Udma_ChStats *chStats)

Get real-time channel statistics.

Requirement: PRSDK-5609

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
chStats – [IN] Pointer to Udma_ChStats. This parameter can’t be NULL.

Returns:

Udma_ErrorCodes

int32_t Udma_chDecStats(Udma_ChHandle chHandle, Udma_ChStats *chStats)

Decrement real-time channel statistics.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
chStats – [IN] Pointer to Udma_ChStats. This parameter can’t be NULL.

Returns:

Udma_ErrorCodes

int32_t Udma_getPeerData(Udma_ChHandle chHandle, uint32_t *peerData)

Get real-time peer data which contains number of bytes written.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
peerData – [INOUT] Pointer to peer data.

Returns:

Udma_ErrorCodes

int32_t Udma_clearPeerData(Udma_ChHandle chHandle, uint32_t peerData)

Clear real-time peer data which contains number of bytes written.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
peerData – [IN] Peer data.

Returns:

Udma_ErrorCodes

int32_t Udma_chReset(Udma_ChHandle chHandle)

Hard reset the channel if teardown fails.

Parameters:: chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
Returns:: Udma_ErrorCodes

int32_t Udma_chGetChanEnStatus(Udma_ChHandle chHandle, uint8_t *chEnableStat)

Get the channel enable status.

Parameters:

chHandle – [IN] UDMA channel handle. This parameter can’t be NULL.
chEnableStat – [INOUT] Pointer to channel enable status

Returns:

Udma_ErrorCodes

struct Udma_ChPrms

#include <udma_ch.h>

UDMA channel open parameters.

Public Members

uint32_t chNum

[IN] UDMAP channel to allocate.

Set to UDMA_DMA_CH_ANY if the channel to allocate and open could be any from the free pool. Set to the actual DMA channel when specific DMA channel need to be allocated. This channel number is relative to the channel type (TX, RX or External). The driver will internally calculate the respective offset to get the actual UDMAP channel number.

uint32_t peerChNum

[IN] The peer channel to link the chNum using PSILCFG.

Incase of PDMA peripherals this represent the PDMA channel to which the UDMA channel should pair with. Refer Udma_PdmaCh macros.

Incase of other PSIL master peripherals this represent the thread ID to which the UDMA channel should pair with. Refer Udma_PsilCh macros.

Incase of Block copy channel type (UDMA_CH_TYPE_TR_BLK_COPY), set this to UDMA_DMA_CH_NA, as the corresponding RX channel (same index as TX channel) is assumed to be paired with and the driver internally sets this up. The UdmaChPrms_init API takes care of this.

Incase of UTC channel type (UDMA_CH_TYPE_UTC), set this to UDMA_DMA_CH_NA.

uint32_t utcId: [IN] The UTC instance to use when channel type is UDMA_CH_TYPE_UTC.

uint32_t mappedChGrp

For other channel type set to UDMA_UTC_ID_INVALID [IN] The Mapped channel 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 channel groups or Udma_MappedRxGrpSoc macro for details about mapped RX channel groups.

For other channel type set to UDMA_MAPPED_GROUP_INVALID

void *appData: [IN] Application/caller context pointer passed back in all the channel callback functions. This could be used by the caller to identify the channel for which the callback is called. This can be set to NULL, if not required by caller.

Udma_RingPrms fqRingPrms: [IN] Free queue ring params where descriptors are queued

Udma_RingPrms cqRingPrms: [IN] Completion queue ring params where descriptors are dequeued This is not used for AM64x kind of devices, but even if the application sets this it will be ignored. But its not required to be set.

Udma_RingPrms tdCqRingPrms: [IN] Teardown completion queue ring params where teardown response and TR response incase of direct TR mode are received from UDMA This is not used for AM64x kind of devices, but even if the application sets this it will be ignored. But its not required to be set.

struct Udma_ChTxPrms

#include <udma_ch.h>

UDMA TX channel parameters.

Public Members

uint8_t pauseOnError: [IN] Bool: When set (TRUE), pause channel on error

uint8_t filterEinfo: [IN] Bool: When set (TRUE), filter out extended info

uint8_t filterPsWords: [IN] Bool: When set (TRUE), filter out protocl specific words

uint8_t addrType: [IN] Address type for this channel. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_atype

uint8_t chanType: [IN] Channel type. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_chan_type

uint16_t fetchWordSize: [IN] Descriptor/TR Size in 32-bit words

uint8_t busPriority: [IN] 3-bit priority value (0=highest, 7=lowest)

uint8_t busQos: [IN] 3-bit qos value (0=highest, 7=lowest)

uint8_t busOrderId: [IN] 4-bit orderid value

uint8_t dmaPriority: [IN] This field selects which scheduling bin the channel will be placed in for bandwidth allocation of the Tx DMA units. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_sched_priority

uint8_t txCredit: [IN] TX credit for external channels

uint16_t fifoDepth

[IN] The fifo depth is used to specify how many FIFO data phases deep the Tx per channel FIFO will be for the channel. While the maximum depth of the Tx FIFO is set at design time, the FIFO depth can be artificially reduced in order to control the maximum latency which can be introduced due to buffering effects.

The maximum FIFO depth suppported depends on the channel type as given below: Normal Capacity Channel - CSL_NAVSS_UDMAP_TX_CHANS_FDEPTH (128 bytes) High Capacity Channel - CSL_NAVSS_UDMAP_TX_HC_CHANS_FDEPTH (1024 bytes) Ultra High Capacity Channel - CSL_NAVSS_UDMAP_TX_UHC_CHANS_FDEPTH (4096 bytes)

The default init API will set this paramater as per the channel type.

uint8_t burstSize

[IN] Specifies the nominal burst size and alignment for data transfers on this channel. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_burst_size. Note1: This parameter should be set less than or equal to the FIFO depth parameter set for UTC channel i.e. fifoDepth >= burstSize Note2: In case of packet mode TX channels, the Tx fifoDepth must be at least 2 PSI-L data phases (32 bytes) larger than the burst size given in this field in order to hold the packet info and extended packet info header which is placed at the front of the data packet in addition to the payload i.e. fifoDepth >= (burstSize + 32 bytes)

Below are the supported burst sizes for various channel types Normal Capacity Channel - 64 bytes High Capacity Channel - 64, 128 or 256 bytes Ultra High Capacity Channel - 64, 128 or 256 bytes

uint8_t supressTdCqPkt: [IN] Bool: Specifies whether or not the channel should suppress sending the single data phase teardown packet when teardown is complete. FALSE = TD packet is sent TRUE = Suppress sending TD packet

struct Udma_ChRxPrms

#include <udma_ch.h>

UDMA RX channel parameters.

Public Members

uint8_t pauseOnError: [IN] Bool: When set (TRUE), pause channel on error

uint8_t addrType: [IN] Address type for this channel. Refer tisci_msg_rm_udmap_rx_ch_cfg_req::rx_atype

uint8_t chanType: [IN] Channel type. Refer tisci_msg_rm_udmap_rx_ch_cfg_req::rx_chan_type

uint16_t fetchWordSize: [IN] Descriptor/TR Size in 32-bit words

uint8_t busPriority: [IN] 3-bit priority value (0=highest, 7=lowest)

uint8_t busQos: [IN] 3-bit qos value (0=highest, 7=lowest)

uint8_t busOrderId: [IN] 4-bit orderid value

uint8_t dmaPriority: [IN] This field selects which scheduling bin the channel will be placed in for bandwidth allocation of the Tx DMA units. Refer tisci_msg_rm_udmap_rx_ch_cfg_req::rx_sched_priority

uint16_t flowIdFwRangeStart: [IN] Starting flow ID value for firewall check

uint16_t flowIdFwRangeCnt: [IN] Number of valid flow ID’s starting from flowIdFwRangeStart for firewall check

uint8_t flowEInfoPresent: [IN] default flow config parameter for EPIB Refer tisci_msg_rm_udmap_flow_cfg_req::rx_einfo_present

uint8_t flowPsInfoPresent: [IN] default flow config parameter for psInfo Refer tisci_msg_rm_udmap_flow_cfg_req::rx_psinfo_present

uint8_t flowErrorHandling: [IN] default flow config parameter for Error Handling Refer tisci_msg_rm_udmap_flow_cfg_req::rx_error_handling

uint8_t flowSopOffset: [IN] default flow config parameter for SOP offset Refer tisci_msg_rm_udmap_flow_cfg_req::rx_sop_offset

uint8_t ignoreShortPkts: [IN] Bool: This field controls whether or not short packets will be treated as exceptions (FALSE) or ignored (TRUE) for the channel. This field is only used when the channel is in split UTC mode.

uint8_t ignoreLongPkts: [IN] Bool: This field controls whether or not long packets will be treated as exceptions (FALSE) or ignored (TRUE) for the channel. This field is only used when the channel is in split UTC mode.

uint32_t configDefaultFlow: [IN] Bool: This field controls whether or not to program the default flow. TRUE - Configures the default flow equal to the RX channel number FALSE - Doesn’t configure the default flow of channel. The caller can allocate and use other generic flows or get the default flow handle and configure the flow using Udma_flowConfig API at a later point of time

uint8_t burstSize

[IN] Specifies the nominal burst size and alignment for data transfers on this channel. Refer tisci_msg_rm_udmap_rx_ch_cfg_req::rx_burst_size. Note1: This parameter should be set less than or equal to the FIFO depth parameter set for UTC channel i.e. fifoDepth >= burstSize Note2: In case of packet mode TX channels, the Tx fifoDepth must be at least 2 PSI-L data phases (32 bytes) larger than the burst size given in this field in order to hold the packet info and extended packet info header which is placed at the front of the data packet in addition to the payload i.e. fifoDepth >= (burstSize + 32 bytes)

Below are the supported burst sizes for various channel types Normal Capacity Channel - 64 bytes High Capacity Channel - 64, 128 or 256 bytes Ultra High Capacity Channel - 64, 128 or 256 bytes

struct Udma_ChUtcPrms

#include <udma_ch.h>

UDMA UTC channel parameters.

Public Members

uint8_t pauseOnError: [IN] Bool: When set (UTRUE), pause channel on error

uint8_t addrType: [IN] Address type for this channel. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_atype

uint8_t chanType: [IN] Channel type. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_chan_type

uint16_t fetchWordSize: [IN] Descriptor/TR Size in 32-bit words

uint8_t busPriority: [IN] 3-bit priority value (0=highest, 7=lowest)

uint8_t busQos: [IN] 3-bit qos value (0=highest, 7=lowest)

uint8_t busOrderId: [IN] 4-bit orderid value

uint8_t dmaPriority: [IN] This field selects which scheduling bin the channel will be placed in for bandwidth allocation of the Tx DMA units. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_sched_priority

uint8_t burstSize

[IN] Specifies the nominal burst size and alignment for data transfers on this channel. Refer tisci_msg_rm_udmap_tx_ch_cfg_req::tx_burst_size. Note1: This parameter should be set less than or equal to the FIFO depth parameter set i.e. fifoDepth >= burstSize

Below are the supported burst sizes for various channel types Normal Capacity Channel - 64 or 128 bytes High Capacity Channel - 64, 128 or 256 bytes Ultra High Capacity Channel - 64, 128 or 256 bytes

uint8_t supressTdCqPkt: [IN] Bool: Specifies whether or not the channel should suppress sending the single data phase teardown packet when teardown is complete. UFALSE = TD packet is sent UTRUE = Suppress sending TD packet TODO: Should we allocate tdCq based on this flag?

struct Udma_ChPdmaPrms

#include <udma_ch.h>

UDMA PDMA channel Static TR parameters.

Public Members

uint32_t elemSize

[IN] Element size. This field specifies how much data is transferred in each write which is performed by the PDMA. This is the X static TR parameter of PDMA.

In case of MCAN TX/RX PDMA channel, this is not used and should be set to 0.

Refer Udma_PdmaElemSize for supported values.

uint32_t elemCnt

[IN] Element count. This field specifies how many elements to transfer each time a trigger is received on the PDMA channel. This is the Y static TR parameter of PDMA.

In case of MCAN PDMA channel, this represents the buffer size. In case of MCAN TX, this field specifies how many bytes should be written to an MCAN TX buffer. This field includes the 8 byte MCAN header on the initial packet fragment. The PDMA will break up the source packet into fragments of this buffer size, copying the 8 byte MCAN header for the initial fragment, and then skipping it for each additional fragment and thus reusing the header from the first fragment. A buffer size less than 16 is treated as 16, and a buffer size greater than 72 is treated as 72. In case of MCAN RX, this field specifies how many bytes should be read from an MCAN RX buffer. This field includes the 8 byte MCAN header on the initial packet fragment. A buffer size less than 16 is treated as 16, and a buffer size greater than 72 is treated as 72.

uint32_t fifoCnt

[IN] FIFO count. This field specifies how many full FIFO operations comprise a complete packet. When the count has been reached, the PDMA will close the packet with an ‘EOP’ indication. If this parameter is set to 0, then no packet delineation is supplied by the PDMA and all framing is controlled via the UDMA TR.

This is the Z static TR parameter of PDMA. This is NA for TX and should be set to 0. In case of MCAN RX, this represents the buffer count. This field specifies how many MCAN RX buffers should be read before closing the CPPI packet with an ‘EOP’ indication. When this count is greater than 1, multiple MCAN RX buffers will be read into a single CPPI packet buffer. The 8 byte MCAN header will be skipped on subsequent MCAN buffer reads. Setting this field to NULL will suppress all packet delineation, and should be avoided.

uint8_t burst

[IN] Burst mode. Enable VBUSP burst mode for this channel.

Since MCAN buffers are stored in linear memory, the burst mode for MCAN is a simple linear burst across the transfer window. The max burst size is set to the 72 byte size of the MCAN buffer. This will allow a full MCAN packet to be read out as a single burst.

uint8_t acc32

[IN] 32b access. Enable 32b access mode.

When set, enables 32-bit access mode. On a 32-bit PDMA, all accesses will have XCNT=4 to support legacy IP that is not fully VBUSP compliant. This bit is ignored if the PDMA VBUSP port is not 32 bits wide.

uint8_t eol

[IN] EOL mode. Enable eol mode.

EOL mode. Normally, when the Z count of FIFO operations has been reached, the PDMA will close the packet with an ‘EOP’ indication. When this flag is set, the PDMA will instead trigger an EOL at the completion of Z.

uint8_t isAasrcCh

[IN] Is peer paired AASRC

Flag to indicate if the paired peer channel is of AASRC

uint8_t groupMode

[IN] Group mode

Group mode. It will look for Group Mode DMA requests, and access the Group Mode FIFOs. When clear, the channel is ‘Stream Mode’. It will look for Stream FIFO DMA requests, and access the Stream Mode FIFOs.

uint8_t dmaReqReset

[IN] DMA request reset

When set, resets any latched DMA request using the DmaReqMask. This bit is self-clearing. It should be used to synchronize the AASRC event status with the PDMA in the event that the AASRC has been previously used and it is not known if the PDMA may have latched, and is holding, previous DMA requests.

uint8_t lastSlot

[IN] Last slot index

This is the index (0-15) of the last slot in the TX/RX FIFO ordering table used by this channel. The ordering table is read to get the FIFO index to access for each slot, starting with the first and ending with the last.

uint8_t firstSlot

[IN] First slot index

This is the index (0-15) of the first slot in the TX/RX FIFO ordering table used by this channel. The ordering table is read to get the FIFO index to access for each slot, starting with the first and ending with the last.

uint16_t dmaReqMask

[IN] DMA request mask

This field holds a set of flags indicating which AASRC DMA requests must fire in order for this channel to activate.

In Steam Mode, these 16 flags correspond to the 16 DMA requests for each TX/RX FIFO. The flags corresponding to all TX/RX FIFOs involved with the channel should be set to 1.

In Group Mode, these flags indicate which Group Mode DMA requests must fire. In this case, only bits 3:0 are relevant and only one bit should be set to 1 as a DMA channel only services a single group.

uint32_t orderTable0

[IN] Order Table 0

FIFO index values is determined by this reg value. 31:28 Entry7 FIFO Index for slot 7 27:24 Entry6 FIFO Index for slot 6 23:20 Entry5 FIFO Index for slot 5 19:16 Entry4 FIFO Index for slot 4 15:12 Entry3 FIFO Index for slot 3 11:8 Entry2 FIFO Index for slot 2 7:4 Entry1 FIFO Index for slot 1 3:0 Entry0 FIFO Index for slot 0 Note: This is a single register that is shared by all RX or TX threads

uint32_t orderTable1

[IN] Order Table 1

FIFO index values is determined by this reg value 31:28 Entry15 FIFO Index for slot 15 27:24 Entry14 FIFO Index for slot 14 23:20 Entry13 FIFO Index for slot 13 19:16 Entry12 FIFO Index for slot 12 15:12 Entry11 FIFO Index for slot 11 11:8 Entry10 FIFO Index for slot 10 7:4 Entry9 FIFO Index for slot 9 3:0 Entry8 FIFO Index for slot 8 Note: This is a single register that is shared by all RX or TX threads

struct Udma_ChStats

#include <udma_ch.h>

UDMA channel statistics.

Public Members

uint32_t packetCnt: [OUT] Current completed packet count for the channel

uint32_t completedByteCnt: [OUT] Current completed payload byte count for the channel

uint32_t startedByteCnt: [OUT] Current started byte count for the channel

struct Udma_ChObject

#include <udma_ch.h>

Opaque UDMA channel object.

Public Members

uintptr_t rsv[UDMA_DRV_CH_OBJ_SIZE]: reserved, should NOT be modified by end users

UDMA ring related parameters and API.

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.

UDMA_RING_ES_4BYTES: 4 bytes Element size

UDMA_RING_ES_8BYTES: 8 bytes Element size

UDMA_RING_ES_16BYTES: 16 bytes Element size

UDMA_RING_ES_32BYTES: 32 bytes Element size

UDMA_RING_ES_64BYTES: 64 bytes Element size

UDMA_RING_ES_128BYTES: 128 bytes Element size

UDMA_RING_ES_256BYTES: 256 bytes Element size

Defines

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

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

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

UDMA_RING_SIZE_CHECK_SKIP: Macro used to skip the ring size check by driver.

UDMA_RING_ORDERID_MAX: Macro used to specificy the maximum ring order id value.

Functions

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

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

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)

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 SYSFW board config.

Returns:

Udma_ErrorCodes

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

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

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

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

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.

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.

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.

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

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

uint32_t Udma_ringGetMode(Udma_RingHandle ringHandle)

Returns the ring mode which is configured during ring alloc.