Introduction

CPSW DMA submodule provides a API layer which allows applications to set up the UDMA peripheral to control the flow of packet data to/from the core from/to CPSW. CPSW DMA module is used to for

Configuration of receive UDMA channel & flow for enabling reception of Ethernet packets matching the application criteria Ex - OUI, Ether Type, IPv4 SA/DA.
Configuration of transmit UDMA channel for enabling transmit of Ethernet packets

The application using CPSW DMA submodule need to allocate memories for different DMA data structures like ring memories, host packet descriptors and packet buffer memories.

Sub Modules
	CPSW DMA CPPI protocol specific info

	CPSW DMA Configuration Definitions

	CPSW DMA Packet Utils

	CPSW_CONFIG_DEFINTIONS

	Packet Definitions

	Packet stats Definitions

Files
file	cpsw_dma.h
	This file contains the structure definitions and function prototypes of the CPSW Data/DMA path set up.

Functions
void	CpswDma_initRxFlowParams (CpswDma_OpenRxFlowPrms *pRxFlowPrm)
	Initialize RX flow open parameters. More...

void	CpswDma_initTxChParams (CpswDma_OpenTxChPrms *pTxChCfg)
	Initialize TX channel open parameters. More...

void	CpswDma_pktInfoInit (CpswDma_PktInfo *pktInfo)
	Initialize packet information structure. More...

CpswDma_RxFlowHandle	CpswDma_openRxFlow (CpswDma_OpenRxFlowPrms *pRxFlowPrms)
	CPSW DMA open Rx flow. More...

int32_t	CpswDma_closeRxFlow (CpswDma_RxFlowHandle hRxFlow, CpswDma_PktInfoQ pFqPktInfoQ, CpswDma_PktInfoQ pCqPktInfoQ)
	CPSW DMA close Rx flow. More...

CpswDma_TxChHandle	CpswDma_openTxCh (CpswDma_OpenTxChPrms *pTxChCfg)
	CPSW DMA open TX channel. More...

int32_t	CpswDma_closeTxCh (CpswDma_TxChHandle txChHandle, CpswDma_PktInfoQ pFqPktInfoQ, CpswDma_PktInfoQ pCqPktInfoQ)
	CPSW DMA close TX channel! More...

int32_t	CpswDma_enableTxEvent (CpswDma_TxChHandle txChHandle)
	Enable TX channel ring event. More...

int32_t	CpswDma_disableTxEvent (CpswDma_TxChHandle txChHandle)
	Disable TX channel ring event. More...

int32_t	CpswDma_enableRxEvent (CpswDma_RxFlowHandle hRxFlow)
	Enable RX flow ring event. More...

int32_t	CpswDma_disableRxEvent (CpswDma_RxFlowHandle hRxFlow)
	Disable RX flow ring event. More...

int32_t	CpswDma_retrieveRxPackets (CpswDma_RxFlowHandle hRxFlow, CpswDma_PktInfoQ *pFromFlowQueue)
	Retrieve Rx ready (full) packet queue from Rx flow. More...

int32_t	CpswDma_submitRxPackets (CpswDma_RxFlowHandle hRxFlow, CpswDma_PktInfoQ pToFlowQueue, CpswDma_PktInfoQ pUnUsedPktQueue)
	Submit a queue of free packets for reception from RX flow. More...

int32_t	CpswDma_retrieveTxDonePackets (CpswDma_TxChHandle hTxCh, CpswDma_PktInfoQ *pFromTxChQueue)
	Retrieve Tx ready (empty) packet queue from Tx channel. More...

int32_t	CpswDma_submitTxReadyPackets (CpswDma_TxChHandle hTxCh, CpswDma_PktInfoQ pToTxChQueue, CpswDma_PktInfoQ pUnUsedPktQueue)
	Submit a queue of ready (full) packet queue to TX channel. More...

int32_t	CpswDma_checkRxFlowSanity (CpswDma_RxFlowHandle hRxFlow, uint32_t margin)
	Check if any packet loss in RX flow FQ and CQ rings. More...

int32_t	CpswDma_checkTxChSanity (CpswDma_TxChHandle hTxCh, uint32_t margin)
	Check if any packet loss in TX Channel FQ and CQ rings. More...

int32_t	CpswDma_getRxFlowStats (CpswDma_RxFlowHandle hRxFlow, CpswDma_RxFlowStats *rxFlowStats)
	Get RX flow statistics. More...

int32_t	CpswDma_getTxChStats (CpswDma_TxChHandle hTxCh, CpswDma_TxChStats *txChStats)
	Get TX channel statistics. More...

int32_t	CpswDma_resetRxFlowStats (CpswDma_RxFlowHandle hRxFlow)
	Reset RX flow statistics. More...

int32_t	CpswDma_resetTxChStats (CpswDma_TxChHandle hTxCh)
	Reset TX channel statistics. More...

void	CpswDma_initDataPathParams (CpswDma_DataPathConfig *pDmaConfig)
	Set default data path parameters. More...

CpswDma_Handle	CpswDma_initDataPath (Cpsw_Type cpswType, const CpswDma_DataPathConfig *pCpswDmaDataPathConfig)
	Initialize data path. More...

int32_t	CpswDma_deInitDataPath (CpswDma_Handle hCpswDma)
	De-initialize data path. More...

CPSW DMA Instance configuration
Configuration macros for CPSW DMA module
#define	CPSW_DMA_MAX_TX_CH (8U)

#define	CPSW_DMA_MAX_RX_FLOW (64U)

#define	CPSW_DMA_MAX_RX_FREE_QUEUE (4U)

#define	CPSW_DMA_HPD_SIZE (128U)

#define	CPSW_DMA_EXTENDED_PKT_INFO_BLOCK_SIZE (16U)

#define	CPSW_DMA_PROTOCOL_SPECIFIC_INFO_BLOCK_SIZE (16U)

#define	CPSW_DMA_PKT_DESC_RESERVED_SIZE

#define	CPSW_DMA_RING_MEM_SIZE (sizeof(uint64_t))

#define	CPSW_DMA_RXFLOWIDX_INVALID (0xABCDABCDU)

#define	CPSW_DMA_RXMTU_ALIGN (1U << 5U)
	CPSW DMA RX MTU alignment. The RxFlow Mtu must be aligned to this value. More...

CPSW DMA Statistics configuration
No. of latest entries kept in the statistics
#define	CPSW_DMA_STATS_HISTORY_CNT ((uint32_t)32U)

CPSW DMA driver opaque handles
Opaque handle typedefs for CPSW DMA driver objects.
typedef struct CpswDma_RxFlowObj_s *	CpswDma_RxFlowHandle
	Opaque structure to hold software state for CPSW DMA RX flow. More...

typedef struct CpswDma_TxChObj_s *	CpswDma_TxChHandle
	Opaque structure to hold software state for CPSW TX DMA channel. More...

typedef struct CpswDma_PktInfo_s *	CpswDma_PktHandle
	Opaque structure to hold software state for CPSW Packet Info. More...

CPSW DMA driver Callback function types
Callback function typedefs so that the CpswDma layer can call into the app layer and let it translate between the hardware packet descriptors and packets and the stack/translation layer's buffers and packets.
typedef uint8_t (	CpswDma_AllocRingMemFxn) (void *appPriv, uint32_t numRingEle, uint32_t alignSize)

typedef void(*	CpswDma_FreeRingMemFxn) (void appPriv, void pRingMem, uint32_t numRingEle)

typedef struct CpswDma_DmaDesc_s (	CpswDma_AllocDmaDesccFxn) (void *appPriv, uint32_t alignSize)

typedef void(*	CpswDma_FreeDmaDescFxn) (void appPriv, struct CpswDma_DmaDesc_s dmaDescPtr)

typedef void(*	CpswDma_PktNotifyCb) (void *hCbArg)

Macro Definition Documentation

#define CPSW_DMA_MAX_TX_CH (8U)

Maximum number of CPSW TX DMA channels

#define CPSW_DMA_MAX_RX_FLOW (64U)

Maximum number of CPSW RX FLOWS channels

#define CPSW_DMA_MAX_RX_FREE_QUEUE (4U)

Max. number for Rx free queues for CPSW RX DMA flow

#define CPSW_DMA_HPD_SIZE (128U)

CPSW DMA HPD packet size

#define CPSW_DMA_EXTENDED_PKT_INFO_BLOCK_SIZE (16U)

Extended Packet Info Block size

#define CPSW_DMA_PROTOCOL_SPECIFIC_INFO_BLOCK_SIZE (16U)

Extended Packet Info Block size

#define CPSW_DMA_PKT_DESC_RESERVED_SIZE

Value:

(CPSW_DMA_HPD_SIZE - \
                                                             sizeof(CSL_UdmapCppi5HMPD) - \
                                                             (CPSW_DMA_EXTENDED_PKT_INFO_BLOCK_SIZE + \
                                                              CPSW_DMA_PROTOCOL_SPECIFIC_INFO_BLOCK_SIZE))

Extended Packet Info Block size

#define CPSW_DMA_RING_MEM_SIZE (sizeof(uint64_t))

CPSW DMA Desc size - this is used by applications to allocate DMA desc memory

#define CPSW_DMA_RXFLOWIDX_INVALID (0xABCDABCDU)

CPSW DMA Invalid RX flow id

#define CPSW_DMA_RXMTU_ALIGN (1U << 5U)

CPSW DMA RX MTU alignment. The RxFlow Mtu must be aligned to this value.

As per UDMAP spec "Rx Packet Size Threshold 0: This value is left shifted by 5 bits and compared against the packet size to determine which free descriptor queue should be used for the SOP buffer in the packet" The value programmed is hence supposed to be 32 bit aligned. Programming non aligned values will result in truncation and expected MTU size will not be programmed. For example setting MTU size of 1518 (required MTU size) results in actual value of 1504 getting programmed resulting in packet drop for frames of size 1504 - 1518 which the app expects to less than the programmed MTU based on the param passed. Refer ksdma_udmap spec section 4.4.2.6 for more details

#define CPSW_DMA_STATS_HISTORY_CNT ((uint32_t)32U)

Typedef Documentation

typedef struct CpswDma_RxFlowObj_s* CpswDma_RxFlowHandle

Opaque structure to hold software state for CPSW DMA RX flow.

typedef struct CpswDma_TxChObj_s* CpswDma_TxChHandle

Opaque structure to hold software state for CPSW TX DMA channel.

typedef struct CpswDma_PktInfo_s* CpswDma_PktHandle

Opaque structure to hold software state for CPSW Packet Info.

typedef uint8_t*(* CpswDma_AllocRingMemFxn) (void *appPriv, uint32_t numRingEle, uint32_t alignSize)

Function pointer type for DMAC packet allocation function

typedef void(* CpswDma_FreeRingMemFxn) (void *appPriv, void *pRingMem, uint32_t numRingEle)

Function pointer type for DMAC packet free function

typedef struct CpswDma_DmaDesc_s*(* CpswDma_AllocDmaDesccFxn) (void *appPriv, uint32_t alignSize)

Function pointer type for DMAC packet allocation function

typedef void(* CpswDma_FreeDmaDescFxn) (void *appPriv, struct CpswDma_DmaDesc_s *dmaDescPtr)

Function pointer type for DMAC packet free function

typedef void(* CpswDma_PktNotifyCb) (void *hCbArg)

Function pointer type for packet notify call back. This is called by driver when packet is received on the Rx flow or transmission completed from Tx channel.

Function Documentation

void CpswDma_initRxFlowParams ( CpswDma_OpenRxFlowPrms * pRxFlowPrm )

Initialize RX flow open parameters.

Initializes RX flow parameters with default values.

Parameters

pRxFlowPrm [IN] Pointer to CpswDma_OpenRxFlowPrms structure

void CpswDma_initTxChParams ( CpswDma_OpenTxChPrms * pTxChCfg )

Initialize TX channel open parameters.

Initializes TX channel open parameters with default values.

Parameters

pTxChCfg [IN] Pointer to CpswDma_OpenTxChPrms structure

void CpswDma_pktInfoInit ( CpswDma_PktInfo * pktInfo )

Initialize packet information structure.

Initialize packet information structure with null/zero values.

Parameters

pktInfo [IN] Pointer to CpswDma_PktInfo structure

CpswDma_RxFlowHandle CpswDma_openRxFlow ( CpswDma_OpenRxFlowPrms * pRxFlowPrms )

CPSW DMA open Rx flow.

Opens the CPSW DMA RX flow based on the flow parameters. This function attaches flow using flowIdx provided in CpswDma_OpenRxFlowPrms and configures the UDMA flow. This also configures event if notifyCb is not null.

Requirement:

Parameters

pRxFlowPrms [IN] CPSW RX Flow parameters CpswDma_OpenRxFlowPrms. This parameter can't be NULL.

Returns: RX flow opaque handle

int32_t CpswDma_closeRxFlow	(	CpswDma_RxFlowHandle	hRxFlow,
		CpswDma_PktInfoQ *	pFqPktInfoQ,
		CpswDma_PktInfoQ *	pCqPktInfoQ
	)

CPSW DMA close Rx flow.

Closes the CPSW DMA RX flow and frees all associated resources. During close operation, we flush FQ taking all DMA descriptors with packet submitted in advance for reception and return to app. Also we retrieve all packets from the CQ (packets received between last CpswDma_retrieveRxPackets packets call) and return those to app. App doesn't need to call CpswDma_retrieveRxPackets explicitly to retrieve these packets.

Requirement:

Parameters

hRxFlow	[IN] CPSW DMA flow handle. This parameter can't be NULL.
pFqPktInfoQ	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from FQ (submitted for reception) are retrieved and returned to application. This parameter can't be NULL.
pCqPktInfoQ	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from CQ (received packets) are retrieved and returned to application. This parameter can't be NULL.

Returns: Udma_ErrorCodes

CpswDma_TxChHandle CpswDma_openTxCh ( CpswDma_OpenTxChPrms * pTxChCfg )

CPSW DMA open TX channel.

Opens the CPSW TX UDMA channel based on the channel parameters. This function open TX channel using chNum provided in CpswDma_OpenTxChPrms() and configures TX channel. This also configures event if notifyCb is not null.

Requirement:

Parameters

pTxChCfg [IN] CPSW TX channel parameters CpswDma_OpenTxChPrms. This parameter can't be NULL.

Returns: TX channel opaque handle

int32_t CpswDma_closeTxCh	(	CpswDma_TxChHandle	txChHandle,
		CpswDma_PktInfoQ *	pFqPktInfoQ,
		CpswDma_PktInfoQ *	pCqPktInfoQ
	)

CPSW DMA close TX channel!

Closes the CPSW DMA TX channel and frees all associated resources. During close operation, we flush FQ taking all DMA descriptors with packet submitted but not yet transmitted and return to app. Also we retrieve all packets from the CQ (transmission completed packets) and return those to app. App doesn't need to call CpswDma_retrieveTxDonePackets() explicitly to retrieve these packets.

Requirement:

Parameters

txChHandle	[IN] CPSW DMA TX Channel handle. This parameter can't be NULL.
pFqPktInfoQ	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from FQ (submitted but not transmitted) are retrieved and returned to application. This parameter can't be NULL.
pCqPktInfoQ	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from CQ (transmission completed) are retrieved and returned to application. This parameter can't be NULL.

Returns: Udma_ErrorCodes

int32_t CpswDma_enableTxEvent ( CpswDma_TxChHandle txChHandle )

Enable TX channel ring event.

Enables the ring completion event for TX channel. This allows application to run time control ring events and retrieve packet once to do burst packet processing.

Parameters

txChHandle [IN] Handle to CPSW DMA TX channel

Returns: Udma_ErrorCodes

int32_t CpswDma_disableTxEvent ( CpswDma_TxChHandle txChHandle )

Disable TX channel ring event.

Disable the ring completion event for TX channel. This allows application to run time control ring events and retrieve packet once.

Parameters

txChHandle [IN] Handle to CPSW DMA TX channel

Returns: Udma_ErrorCodes

int32_t CpswDma_enableRxEvent ( CpswDma_RxFlowHandle hRxFlow )

Enable RX flow ring event.

Enables the ring completion event for RX Flow. This allows application to run time control ring events and retrieve packet once to do burst packet processing.

Parameters

hRxFlow [IN] Handle to CPSW DMA RX Flow

Returns: Udma_ErrorCodes

int32_t CpswDma_disableRxEvent ( CpswDma_RxFlowHandle hRxFlow )

Disable RX flow ring event.

Disable the ring completion event for RX Flow. This allows application to run time control ring events and retrieve packet once.

Parameters

hRxFlow [IN] Handle to CPSW DMA RX Flow

Returns: Udma_ErrorCodes

int32_t CpswDma_retrieveRxPackets	(	CpswDma_RxFlowHandle	hRxFlow,
		CpswDma_PktInfoQ *	pFromFlowQueue
	)

Retrieve Rx ready (full) packet queue from Rx flow.

Parameters

hRxFlow	[IN] flow handle for the flow we wish to retrieve packets from
pFromFlowQueue	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from hardware are retrieved and returned to application

Returns: Udma_ErrorCodes

int32_t CpswDma_submitRxPackets	(	CpswDma_RxFlowHandle	hRxFlow,
		CpswDma_PktInfoQ *	pToFlowQueue,
		CpswDma_PktInfoQ *	pUnUsedPktQueue
	)

Submit a queue of free packets for reception from RX flow.

Parameters

hRxFlow	[IN] flow handle for the flow we wish to submit packets to
pToFlowQueue	[OUT] Pointer to CpswDma_PktInfoQ structure containing packets to be submitted to flow
pUnUsedPktQueue	[OUT] Pointer to CpswDma_PktInfoQ structure. This queue is used by driver to return packets for which it couldn't allocate the DMA descriptors

Returns: Udma_ErrorCodes

int32_t CpswDma_retrieveTxDonePackets	(	CpswDma_TxChHandle	hTxCh,
		CpswDma_PktInfoQ *	pFromTxChQueue
	)

Retrieve Tx ready (empty) packet queue from Tx channel.

Parameters

hTxCh	[IN] CPSW DMA TX channel handle for the TX channel we wish to retrieve packets from
pFromTxChQueue	[OUT] Pointer to CpswDma_PktInfoQ structure where packets from hardware are retrieved and returned to application

Returns: Udma_ErrorCodes

int32_t CpswDma_submitTxReadyPackets	(	CpswDma_TxChHandle	hTxCh,
		CpswDma_PktInfoQ *	pToTxChQueue,
		CpswDma_PktInfoQ *	pUnUsedPktQueue
	)

Submit a queue of ready (full) packet queue to TX channel.

Parameters

hTxCh	[IN] TX Channel handle for the TX channel we wish to submit packets to
pToTxChQueue	[OUT] Pointer to CpswDma_PktInfoQ structure containing packets to be submitted to TX channel
pUnUsedPktQueue	[OUT] Pointer to CpswDma_PktInfoQ structure. This queue is used by driver to return packets for which it couldn't allocate the DMA descriptors

Returns: Udma_ErrorCodes

int32_t CpswDma_checkRxFlowSanity	(	CpswDma_RxFlowHandle	hRxFlow,
		uint32_t	margin
	)

Check if any packet loss in RX flow FQ and CQ rings.

This development time error checks API checks DMA descriptor loss due to any timing issues. We check amount of descriptors with DMA and free matches the number of allocated with some "margin" for packets in flight.

Note: Margin can vary drastically based on Core (A72 vs R5), type of Udma channel (NORMAL/HC etc.) and size of packet. This makes these API dependent on application configuration.

Parameters

hRxFlow	[IN] flow handle for the flow we wish to check sanity
margin	[IN] Amount of packets which can be in flight in DMA

Return values

UDMA_SOK	Number of of free descriptors and with DMA matches (total allocated packets - margin) = (packets in CQ + Packets in FQ)
UDMA_EFAIL	Number offree descriptors and with DMA don't match

int32_t CpswDma_checkTxChSanity	(	CpswDma_TxChHandle	hTxCh,
		uint32_t	margin
	)

Check if any packet loss in TX Channel FQ and CQ rings.

This development time error checks API checks dma desc loss due to any timing issues. We check amount of descriptors with DMA and free matches the number of allocated with some "margin" for packets in flight.

Note: Margin can vary drastically based on Core (A72 vs R5), type of Udma channel (NORMAL/HC etc.) and size of packet. This makes these API dependent on application configuration.

Parameters

hTxCh	[IN] TX Channel handle for the TX channel we wish to check sanity
margin	[IN] Amount of packets which can be in flight in DMA

Return values

UDMA_SOK	Number of free descriptors and with DMA matches (total allocated packets - margin) = (packets in CQ + Packets in FQ)
UDMA_EFAIL	Number of free descriptors and with DMA don't match

int32_t CpswDma_getRxFlowStats	(	CpswDma_RxFlowHandle	hRxFlow,
		CpswDma_RxFlowStats *	rxFlowStats
	)

Get RX flow statistics.

Parameters

hRxFlow	[IN] RX flow handle
rxFlowStats	[INOUT] Pointer to RX Flow stats object where stats would be returned

Return values

CPSW_SOK	Stats are enabled and supported
CPSW_ENOTSUPPORTED	Stats is not supported (enabled)

int32_t CpswDma_getTxChStats	(	CpswDma_TxChHandle	hTxCh,
		CpswDma_TxChStats *	txChStats
	)

Get TX channel statistics.

Parameters

hTxCh	[IN] TX channel handle
txChStats	[INOUT] Pointer to TX Channel stats object where stats would be returned

Return values

CPSW_SOK	Stats are enabled and supported
CPSW_ENOTSUPPORTED	Stats is not supported (enabled)

int32_t CpswDma_resetRxFlowStats ( CpswDma_RxFlowHandle hRxFlow )

Reset RX flow statistics.

Parameters

hRxFlow [IN] RX flow handle

Return values

CPSW_SOK	Stats are enabled and supported
CPSW_ENOTSUPPORTED	Stats is not supported (enabled)

int32_t CpswDma_resetTxChStats ( CpswDma_TxChHandle hTxCh )

Reset TX channel statistics.

Parameters

hTxCh [IN] TX Channel handle

Return values

CPSW_SOK	Stats are enabled and supported
CPSW_ENOTSUPPORTED	Stats is not supported (enabled)

void CpswDma_initDataPathParams ( CpswDma_DataPathConfig * pDmaConfig )

Set default data path parameters.

Parameters

pDmaConfig [IN] Data path config structure to be initialized

CpswDma_Handle CpswDma_initDataPath	(	Cpsw_Type	cpswType,
		const CpswDma_DataPathConfig *	pCpswDmaDataPathConfig
	)

Initialize data path.

Initialize DMA data path state on remote core.

Parameters

cpswType	[IN] Cpsw Type
pCpswDmaDataPathConfig	[IN] Data Path Init params

Returns: CPSW DMA opaque handle

int32_t CpswDma_deInitDataPath ( CpswDma_Handle hCpswDma )

De-initialize data path.

De-initialize DMA data path state on remote core.

Parameters

hCpswDma [IN] Cpsw DMA Handle

Returns: Udma_ErrorCodes

Introduction

Sub Modules

Files

Functions

CPSW DMA Instance configuration

CPSW DMA Statistics configuration

CPSW DMA driver opaque handles

CPSW DMA driver Callback function types

Macro Definition Documentation

Typedef Documentation

Function Documentation