AM64x MCU+ SDK  10.00.00
enet_dma.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Texas Instruments Incorporated 2020-23
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the
14  * distribution.
15  *
16  * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
47 #ifndef ENET_DMA_H_
48 #define ENET_DMA_H_
49 
50 /* ========================================================================== */
51 /* Include Files */
52 /* ========================================================================== */
53 
54 #include <stdint.h>
58 
59 #if defined(SOC_AM64X) || defined(SOC_AM243X) || defined(SOC_AM62AX) || defined(SOC_AM62PX) || defined(SOC_AM62DX)
60 #include <drivers/udma.h>
64 #elif defined (SOC_AM273X) || defined(SOC_AWR294X) || defined(SOC_AWR2544) || defined(SOC_AM263X) || defined(SOC_AM263PX) || defined(SOC_AM261X)
65 #include <include/dma/cpdma/enet_cpdma.h>
66 #else
67 #error "SOC not supported"
68 #endif
69 
70 #ifdef __cplusplus
71 extern "C" {
72 #endif
73 
74 /* ========================================================================== */
75 /* Macros */
76 /* ========================================================================== */
77 
78 
79 
80 #if defined(SOC_AM273X) || defined(SOC_AWR294X) || defined(SOC_AWR2544) || defined(SOC_AM263X) || defined(SOC_AM263PX) || defined(SOC_AM261X)
81 
82 #define Enet_isCacheCoherent() (false)
83 #elif defined(SOC_AM64X) || defined(SOC_AM243X) || defined(SOC_AM62AX) || defined(SOC_AM62PX) || defined(SOC_AM62DX)
84 
85 #define Enet_isCacheCoherent() (Udma_isCacheCoherent())
86 #else
87 #error "SOC not supported"
88 #endif
89 
91 #define ENETDMA_RXCSUMINFO_CHKSUM_ADD_SHIFT (0U)
92 
94 #define ENETDMA_RXCSUMINFO_CHKSUM_ADD_MASK (((uint32_t) 0xFFFF) << ENETDMA_RXCSUMINFO_CHKSUM_ADD_SHIFT)
95 
97 #define ENETDMA_RXCSUMINFO_CHKSUM_ERR_SHIFT (16U)
98 
100 #define ENETDMA_RXCSUMINFO_CHKSUM_ERR_MASK (((uint32_t) 0x1U) << ENETDMA_RXCSUMINFO_CHKSUM_ERR_SHIFT)
101 
103 #define ENETDMA_RXCSUMINFO_FRAGMENT_SHIFT (17U)
104 
106 #define ENETDMA_RXCSUMINFO_FRAGMENT_MASK (((uint32_t) 0x1U) << ENETDMA_RXCSUMINFO_FRAGMENT_SHIFT)
107 
109 #define ENETDMA_RXCSUMINFO_TCP_UDP_N_SHIFT (18U)
110 
112 #define ENETDMA_RXCSUMINFO_TCP_UDP_N_MASK (((uint32_t) 0x1U) << ENETDMA_RXCSUMINFO_TCP_UDP_N_SHIFT)
113 
115 #define ENETDMA_RXCSUMINFO_IPV6_VALID_SHIFT (19U)
116 
118 #define ENETDMA_RXCSUMINFO_IPV6_VALID_MASK (((uint32_t) 0x1U) << ENETDMA_RXCSUMINFO_IPV6_VALID_SHIFT)
119 
121 #define ENETDMA_RXCSUMINFO_IPV4_VALID_SHIFT (20U)
122 
124 #define ENETDMA_RXCSUMINFO_IPV4_VALID_MASK (((uint32_t) 0x1U) << ENETDMA_RXCSUMINFO_IPV4_VALID_SHIFT)
125 
127 #define ENETDMA_TXCSUMINFO_CHKSUM_BYTECNT_SHIFT (0U)
128 
130 #define ENETDMA_TXCSUMINFO_CHKSUM_BYTECNT_MASK (((uint32_t) 0x3FFFU) << ENETDMA_TXCSUMINFO_CHKSUM_BYTECNT_SHIFT)
131 
133 #define ENETDMA_TXCSUMINFO_CHKSUM_INV_SHIFT (15U)
134 
136 #define ENETDMA_TXCSUMINFO_CHKSUM_INV_MASK (((uint32_t) 0x1U) << ENETDMA_TXCSUMINFO_CHKSUM_INV_SHIFT)
137 
139 #define ENETDMA_TXCSUMINFO_CHKSUM_STARTBYTE_SHIFT (16U)
140 
142 #define ENETDMA_TXCSUMINFO_CHKSUM_STARTBYTE_MASK (((uint32_t) 0xFFU) << ENETDMA_TXCSUMINFO_CHKSUM_STARTBYTE_SHIFT)
143 
145 #define ENETDMA_TXCSUMINFO_CHKSUM_RESULT_SHIFT (24U)
146 
148 #define ENETDMA_TXCSUMINFO_CHKSUM_RESULT_MASK (((uint32_t) 0xFFU) << ENETDMA_TXCSUMINFO_CHKSUM_RESULT_SHIFT)
149 
150 
151 /* --- Utilities macros to extract fields from THOST Checksum Encapsulation word --- */
152 
154 #define ENETDMA_RXCSUMINFO_GET_IPV4_FLAG(chkSumInfo) \
155  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_IPV4_VALID)
156 
158 #define ENETDMA_RXCSUMINFO_GET_IPV6_FLAG(chkSumInfo) \
159  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_IPV6_VALID)
160 
162 #define ENETDMA_RXCSUMINFO_GET_TCPUDP_N_FLAG(chkSumInfo) \
163  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_TCP_UDP_N)
164 
166 #define ENETDMA_RXCSUMINFO_GET_FRAGMENT_FLAG(chkSumInfo) \
167  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_FRAGMENT)
168 
170 #define ENETDMA_RXCSUMINFO_GET_CHKSUM_ERR_FLAG(chkSumInfo) \
171  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_CHKSUM_ERR)
172 
174 #define ENETDMA_RXCSUMINFO_GET_CHKSUM_RESULT(chkSumInfo) \
175  ENET_FEXT(chkSumInfo, ENETDMA_RXCSUMINFO_CHKSUM_ADD)
176 
177 /* --- Utilities macros to insert fields in FHOST Checksum Encapsulation word --- */
178 
180 #define ENETDMA_TXCSUMINFO_SET_CHKSUM_RESBYTE(chkSumInfo, val) \
181  ENET_FINS(chkSumInfo, ENETDMA_TXCSUMINFO_CHKSUM_RESULT, val)
182 
184 #define ENETDMA_TXCSUMINFO_SET_CHKSUM_STARTBYTE(chkSumInfo, val) \
185  ENET_FINS(chkSumInfo, ENETDMA_TXCSUMINFO_CHKSUM_STARTBYTE, val)
186 
188 #define ENETDMA_TXCSUMINFO_SET_CHKSUM_INV_FLAG(chkSumInfo, val) \
189  ENET_FINS(chkSumInfo, ENETDMA_TXCSUMINFO_CHKSUM_INV, val)
190 
192 #define ENETDMA_TXCSUMINFO_SET_CHKSUM_BYTECNT(chkSumInfo, val) \
193  ENET_FINS(chkSumInfo, ENETDMA_TXCSUMINFO_CHKSUM_BYTECNT, val)
194 
200 #define ENET_DMA_STATS_HISTORY_CNT ((uint32_t)2U)
201 
212 typedef EnetDma_Pkt *(*EnetDma_AllocEthPktFxn)(uint32_t pktSize,
213  uint32_t alignSize,
214  void *appPriv);
215 
217 typedef void (*EnetDma_FreeEthPktFxn)(EnetDma_Pkt *pPktInfo);
218 
229 
230 
231 /* ========================================================================== */
232 /* Structures and Enums */
233 /* ========================================================================== */
234 
246 typedef struct EnetDma_CbStats_s
247 {
249  uint64_t dataNotifyCnt;
250 
253  uint64_t zeroNotifyCnt;
255  uint64_t totalPktCnt;
257  uint64_t totalCycleCnt;
258 
263 
266  uint64_t pktsPerNotify[ENET_DMA_STATS_HISTORY_CNT];
269 
272  uint64_t cycleCntPerNotify[ENET_DMA_STATS_HISTORY_CNT];
275 
278  uint64_t cycleCntPerPkt[ENET_DMA_STATS_HISTORY_CNT];
279 
283  uint64_t readyDmaDescQCnt[ENET_DMA_STATS_HISTORY_CNT];
285 
289 typedef struct EnetDma_DmaDescStats_s
290 {
292  uint64_t readyDmaDescEnq;
294  uint64_t freeDmaDescDeq;
296  uint64_t underFlowCnt;
298 
302 typedef struct EnetDma_RxChStats_s
303 {
311  uint64_t rxSubmitPktEnq;
317 
321 typedef struct EnetDma_TxChStats_s
322 {
330  uint64_t txSubmitPktEnq;
336 
339 /* ========================================================================== */
340 /* Global Variables Declarations */
341 /* ========================================================================== */
342 
343 /* None */
344 
345 /* ========================================================================== */
346 /* Function Declarations */
347 /* ========================================================================== */
348 
361  uint32_t instId,
362  const EnetDma_initCfg *pDmaCfg);
363 
374 
384 void EnetDma_initRxChParams(void *pRxChCfg);
385 
405  const void *pRxChCfg);
406 
428  EnetDma_PktQ *fq,
429  EnetDma_PktQ *cq);
430 
443 
458 
469 
479 void EnetDma_initTxChParams(void *pTxChCfg);
480 
500  const void *pTxChCfg);
501 
524  EnetDma_PktQ *fq,
525  EnetDma_PktQ *cq);
526 
539 
550 
561 
574  EnetDma_PktQ *pRetrieveQ);
575 
588  EnetDma_Pkt **pPkt);
589 
603  EnetDma_PktQ *pSubmitQ);
604 
616  EnetDma_Pkt *pPkt);
617 
630  EnetDma_PktQ *pRetrieveQ);
631 
644  EnetDma_Pkt **pPkt);
645 
657  EnetDma_PktQ *pSubmitQ);
658 
670  EnetDma_Pkt *pPkt);
671 
680 
692  EnetDma_RxChStats *pStats);
693 
705  EnetDma_TxChStats *pStats);
706 
716 
726 
727 /* ========================================================================== */
728 /* Deprecated Function Declarations */
729 /* ========================================================================== */
730 
731 /* None */
732 
733 /* ========================================================================== */
734 /* Static Function Definitions */
735 /* ========================================================================== */
736 
737 /* None */
738 
739 #ifdef __cplusplus
740 }
741 #endif
742 
743 #endif /* ENET_DMA_H_ */
744 
EnetDma_TxChStats::txSubmitPktEnq
uint64_t txSubmitPktEnq
Definition: enet_dma.h:330
EnetDma_RxChStats::rxSubmitPktEnq
uint64_t rxSubmitPktEnq
Definition: enet_dma.h:311
EnetDma_disableRxEvent
int32_t EnetDma_disableRxEvent(EnetDma_RxChHandle hRxCh)
Disable RX channel packet reception event.
EnetDma_DmaDescStats::freeDmaDescDeq
uint64_t freeDmaDescDeq
Definition: enet_dma.h:294
EnetDma_retrieveTxPkt
int32_t EnetDma_retrieveTxPkt(EnetDma_TxChHandle hTxCh, EnetDma_Pkt **pPkt)
Retrieve single TX free (empty) packet from TX channel.
EnetDma_submitTxPktQ
int32_t EnetDma_submitTxPktQ(EnetDma_TxChHandle hTxCh, EnetDma_PktQ *pSubmitQ)
Submit a queue of ready (full) packets to TX channel.
EnetDma_RxChStats::rxRetrievePktDeq
uint64_t rxRetrievePktDeq
Definition: enet_dma.h:313
EnetDma_RxChStats::submitPktStats
EnetDma_CbStats submitPktStats
Definition: enet_dma.h:305
ENET_DMA_STATS_HISTORY_CNT
#define ENET_DMA_STATS_HISTORY_CNT
Enet DMA statistics configuration.
Definition: enet_dma.h:200
EnetDma_enableTxEvent
int32_t EnetDma_enableTxEvent(EnetDma_TxChHandle hTxCh)
Enable TX channel packet transmit completion event.
EnetDma_initRxChParams
void EnetDma_initRxChParams(void *pRxChCfg)
Initialize RX channel open parameters.
EnetDma_RxChStats
RX channel statistics.
Definition: enet_dma.h:303
enet_types.h
This file contains the basic types using across the Enet driver.
EnetDma_TxChStats
TX channel statistics.
Definition: enet_dma.h:322
EnetDma_getTxChStats
int32_t EnetDma_getTxChStats(EnetDma_TxChHandle hTxCh, EnetDma_TxChStats *pStats)
Get TX channel statistics.
EnetDma_RxChStats::retrievePktStats
EnetDma_CbStats retrievePktStats
Definition: enet_dma.h:307
EnetDma_TxChHandle
struct EnetUdma_TxChObj_s * EnetDma_TxChHandle
Opaque handle that holds software state for Enet TX DMA channel.
Definition: enet_udma_types.h:99
EnetDma_getRxChStats
int32_t EnetDma_getRxChStats(EnetDma_RxChHandle hRxCh, EnetDma_RxChStats *pStats)
Get RX channel statistics.
enet_queue.h
This file contains the type definitions and helper macros for the Enet software queue.
EnetDma_CbStats::zeroNotifyCnt
uint64_t zeroNotifyCnt
Definition: enet_dma.h:253
EnetDma_CbStats::pktsPerNotifyMax
uint64_t pktsPerNotifyMax
Definition: enet_dma.h:262
EnetDma_TxChStats::txRetrievePktDeq
uint64_t txRetrievePktDeq
Definition: enet_dma.h:332
EnetDma_TxChStats::txSubmitPktOverFlowCnt
uint64_t txSubmitPktOverFlowCnt
Definition: enet_dma.h:334
EnetDma_PktNotifyCb
void(* EnetDma_PktNotifyCb)(void *cbArg)
Function pointer type for packet notify call back.
Definition: enet_udma.h:184
EnetDma_resetRxChStats
int32_t EnetDma_resetRxChStats(EnetDma_RxChHandle hRxCh)
Reset RX channel statistics.
EnetDma_initPktInfo
void EnetDma_initPktInfo(EnetDma_Pkt *pktInfo)
Initialize packet information structure.
EnetDma_openTxCh
EnetDma_TxChHandle EnetDma_openTxCh(EnetDma_Handle hDma, const void *pTxChCfg)
Enet DMA open TX channel.
EnetDma_RxChStats::dmaDescStats
EnetDma_DmaDescStats dmaDescStats
Definition: enet_dma.h:309
EnetDma_TxChStats::dmaDescStats
EnetDma_DmaDescStats dmaDescStats
Definition: enet_dma.h:328
enet_dma_pktutils.h
Enet DMA utility API to check packet and descriptor ownership states during development and debug.
EnetDma_resetTxChStats
int32_t EnetDma_resetTxChStats(EnetDma_TxChHandle hTxCh)
Reset TX channel statistics.
EnetDma_CbStats::totalCycleCnt
uint64_t totalCycleCnt
Definition: enet_dma.h:257
EnetDma_initTxChParams
void EnetDma_initTxChParams(void *pTxChCfg)
Initialize TX channel open parameters.
EnetDma_Pkt
struct EnetUdma_PktInfo_s EnetDma_Pkt
Opaque handle that represents a DMA packet.
Definition: enet_udma_types.h:104
EnetDma_initDmaCfg
EnetDma_Handle EnetDma_initDmaCfg(Enet_Type enetType, uint32_t instId, const EnetDma_initCfg *pDmaCfg)
Initialize data path.
EnetDma_retrieveRxPktQ
int32_t EnetDma_retrieveRxPktQ(EnetDma_RxChHandle hRxCh, EnetDma_PktQ *pRetrieveQ)
Retrieve queue of RX ready (full) packets from RX channel.
enet_udma.h
This file contains the type definitions and helper macros for the Enet UDMA data path (DMA) interface...
EnetDma_DmaDescStats::underFlowCnt
uint64_t underFlowCnt
Definition: enet_dma.h:296
enet_udma_psi.h
This file contains the type definitions and helper macros for the Enet UDMA CPPI protocol specific in...
enet_udma_types.h
This file contains the base DMA definitions.
EnetDma_retrieveRxPkt
int32_t EnetDma_retrieveRxPkt(EnetDma_RxChHandle hRxCh, EnetDma_Pkt **pPkt)
Retrieve single RX ready (full) packet (single) from RX channel.
EnetDma_enableRxEvent
int32_t EnetDma_enableRxEvent(EnetDma_RxChHandle hRxCh)
Enable RX channel packet reception event.
EnetDma_retrieveTxPktQ
int32_t EnetDma_retrieveTxPktQ(EnetDma_TxChHandle hTxCh, EnetDma_PktQ *pRetrieveQ)
Retrieve queue of TX free (empty) packets from TX channel.
EnetDma_TxChStats::retrievePktStats
EnetDma_CbStats retrievePktStats
Definition: enet_dma.h:326
EnetDma_CbStats::dataNotifyCnt
uint64_t dataNotifyCnt
Definition: enet_dma.h:249
EnetDma_submitTxPkt
int32_t EnetDma_submitTxPkt(EnetDma_TxChHandle hTxCh, EnetDma_Pkt *pPkt)
Submit a single ready (full) packet to TX channel.
Enet_Type
Enet_Type
Ethernet peripheral type.
Definition: enet_types.h:199
EnetDma_submitRxPkt
int32_t EnetDma_submitRxPkt(EnetDma_RxChHandle hRxCh, EnetDma_Pkt *pPkt)
Submit single RX free (empty) packet for reception to RX channel.
EnetDma_FreeEthPktFxn
void(* EnetDma_FreeEthPktFxn)(EnetDma_Pkt *pPktInfo)
Function pointer type for Ethernet packet free function.
Definition: enet_dma.h:217
EnetDma_submitRxPktQ
int32_t EnetDma_submitRxPktQ(EnetDma_RxChHandle hRxCh, EnetDma_PktQ *pSubmitQ)
Submit queue of RX free (empty) packets for reception to RX channel.
EnetDma_CbStats::cycleCntPerPktMax
uint64_t cycleCntPerPktMax
Definition: enet_dma.h:274
EnetDma_DmaDescStats
DMA descriptor stats for the RX & TX channels.
Definition: enet_dma.h:290
udma.h
UDMA Driver API/interface file.
EnetDma_TxChStats::submitPktStats
EnetDma_CbStats submitPktStats
Definition: enet_dma.h:324
EnetDma_openRxCh
EnetDma_RxChHandle EnetDma_openRxCh(EnetDma_Handle hDma, const void *pRxChCfg)
Enet DMA open RX channel.
EnetDma_registerTxEventCb
int32_t EnetDma_registerTxEventCb(EnetDma_TxChHandle hTxCh, EnetDma_PktNotifyCb notifyCb, void *cbArg)
Register packet transmit completion event callback.
EnetDma_CbStats::totalPktCnt
uint64_t totalPktCnt
Definition: enet_dma.h:255
EnetDma_initCfg
Config structure for Enet UDMA Data Path initialization.
Definition: enet_udma.h:822
EnetDma_closeTxCh
int32_t EnetDma_closeTxCh(EnetDma_TxChHandle hTxCh, EnetDma_PktQ *fq, EnetDma_PktQ *cq)
Enet DMA close TX channel.
EnetDma_CbStats
Stats for packets submitted/retrieved in the DMA event callbacks functions.
Definition: enet_dma.h:247
EnetDma_registerRxEventCb
int32_t EnetDma_registerRxEventCb(EnetDma_RxChHandle hRxCh, EnetDma_PktNotifyCb notifyCb, void *cbArg)
Register packet arrival event callback.
EnetDma_PktQ
EnetQ EnetDma_PktQ
Packet queue.
Definition: enet_dma.h:228
EnetDma_RxChHandle
struct EnetUdma_RxFlowObj_s * EnetDma_RxChHandle
Opaque handle that holds software state for Enet RX DMA flow.
Definition: enet_udma_types.h:94
EnetDma_disableTxEvent
int32_t EnetDma_disableTxEvent(EnetDma_TxChHandle hTxCh)
Disable TX channel packet transmit completion event.
EnetDma_Handle
struct EnetUdma_DrvObj_s * EnetDma_Handle
Opaque handle for Enet UDMA driver object.
Definition: enet_udma_types.h:85
EnetDma_closeRxCh
int32_t EnetDma_closeRxCh(EnetDma_RxChHandle hRxCh, EnetDma_PktQ *fq, EnetDma_PktQ *cq)
Enet DMA close RX channel.
EnetQ
Generic queue.
Definition: enet_queue.h:83
EnetDma_RxChStats::rxSubmitPktUnderFlowCnt
uint64_t rxSubmitPktUnderFlowCnt
Definition: enet_dma.h:315
EnetDma_DmaDescStats::readyDmaDescEnq
uint64_t readyDmaDescEnq
Definition: enet_dma.h:292
EnetDma_deinitDmaCfg
int32_t EnetDma_deinitDmaCfg(EnetDma_Handle hEnetUdma)
De-initialize data path.
EnetDma_CbStats::cycleCntPerNotifyMax
uint64_t cycleCntPerNotifyMax
Definition: enet_dma.h:268