1 /******************************************************************************
2 * Copyright (C) 2010 - 2020 Xilinx, Inc.  All rights reserved.
3 * SPDX-License-Identifier: MIT
4 ******************************************************************************/
5 
6 /*****************************************************************************/
7 /**
8 *
9 * @file xemacps_bdring.h
10 * @addtogroup emacps_v3_11
11 * @{
12 *
13 * The Xiline EmacPs Buffer Descriptor ring driver. This is part of EmacPs
14 * DMA functionalities.
15 *
16 * <pre>
17 * MODIFICATION HISTORY:
18 *
19 * Ver   Who  Date     Changes
20 * ----- ---- -------- -------------------------------------------------------
21 * 1.00a wsy  01/10/10 First release
22 * 2.1   srt  07/15/14 Add support for Zynq Ultrascale Mp architecture.
23 * 3.0   kvn  02/13/15 Modified code for MISRA-C:2012 compliance.
24 * 3.6   rb   09/08/17 HwCnt variable (in XEmacPs_BdRing structure) is
25 *              changed to volatile.
26 *
27 * </pre>
28 *
29 ******************************************************************************/
30 
31 #ifndef XEMACPS_BDRING_H    /* prevent curcular inclusions */
32 #define XEMACPS_BDRING_H    /* by using protection macros */
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 
39 /**************************** Type Definitions *******************************/
40 
41 /** This is an internal structure used to maintain the DMA list */
42 typedef struct {
43     UINTPTR PhysBaseAddr;/**< Physical address of 1st BD in list */
44     UINTPTR BaseBdAddr;     /**< Virtual address of 1st BD in list */
45     UINTPTR HighBdAddr;     /**< Virtual address of last BD in the list */
46     u32 Length;     /**< Total size of ring in bytes */
47     u32 RunState;     /**< Flag to indicate DMA is started */
48     u32 Separation;     /**< Number of bytes between the starting address
49                                   of adjacent BDs */
50     XEmacPs_Bd *FreeHead;
51                  /**< First BD in the free group */
52     XEmacPs_Bd *PreHead;/**< First BD in the pre-work group */
53     XEmacPs_Bd *HwHead; /**< First BD in the work group */
54     XEmacPs_Bd *HwTail; /**< Last BD in the work group */
55     XEmacPs_Bd *PostHead;
56                  /**< First BD in the post-work group */
57     XEmacPs_Bd *BdaRestart;
58                  /**< BDA to load when channel is started */
59 
60     volatile u32 HwCnt;    /**< Number of BDs in work group */
61     u32 PreCnt;     /**< Number of BDs in pre-work group */
62     u32 FreeCnt;    /**< Number of allocatable BDs in the free group */
63     u32 PostCnt;    /**< Number of BDs in post-work group */
64     u32 AllCnt;     /**< Total Number of BDs for channel */
65 } XEmacPs_BdRing;
66 
67 
68 /***************** Macros (Inline Functions) Definitions *********************/
69 
70 /*****************************************************************************/
71 /**
72 * Use this macro at initialization time to determine how many BDs will fit
73 * in a BD list within the given memory constraints.
74 *
75 * The results of this macro can be provided to XEmacPs_BdRingCreate().
76 *
77 * @param Alignment specifies what byte alignment the BDs must fall on and
78 *        must be a power of 2 to get an accurate calculation (32, 64, 128,...)
79 * @param Bytes is the number of bytes to be used to store BDs.
80 *
81 * @return Number of BDs that can fit in the given memory area
82 *
83 * @note
84 * C-style signature:
85 *    u32 XEmacPs_BdRingCntCalc(u32 Alignment, u32 Bytes)
86 *
87 ******************************************************************************/
88 #define XEmacPs_BdRingCntCalc(Alignment, Bytes)                    \
89     (u32)((Bytes) / (sizeof(XEmacPs_Bd)))
90 
91 /*****************************************************************************/
92 /**
93 * Use this macro at initialization time to determine how many bytes of memory
94 * is required to contain a given number of BDs at a given alignment.
95 *
96 * @param Alignment specifies what byte alignment the BDs must fall on. This
97 *        parameter must be a power of 2 to get an accurate calculation (32, 64,
98 *        128,...)
99 * @param NumBd is the number of BDs to calculate memory size requirements for
100 *
101 * @return The number of bytes of memory required to create a BD list with the
102 *         given memory constraints.
103 *
104 * @note
105 * C-style signature:
106 *    u32 XEmacPs_BdRingMemCalc(u32 Alignment, u32 NumBd)
107 *
108 ******************************************************************************/
109 #define XEmacPs_BdRingMemCalc(Alignment, NumBd)                    \
110     (u32)(sizeof(XEmacPs_Bd) * (NumBd))
111 
112 /****************************************************************************/
113 /**
114 * Return the total number of BDs allocated by this channel with
115 * XEmacPs_BdRingCreate().
116 *
117 * @param  RingPtr is the DMA channel to operate on.
118 *
119 * @return The total number of BDs allocated for this channel.
120 *
121 * @note
122 * C-style signature:
123 *    u32 XEmacPs_BdRingGetCnt(XEmacPs_BdRing* RingPtr)
124 *
125 *****************************************************************************/
126 #define XEmacPs_BdRingGetCnt(RingPtr) ((RingPtr)->AllCnt)
127 
128 /****************************************************************************/
129 /**
130 * Return the number of BDs allocatable with XEmacPs_BdRingAlloc() for pre-
131 * processing.
132 *
133 * @param  RingPtr is the DMA channel to operate on.
134 *
135 * @return The number of BDs currently allocatable.
136 *
137 * @note
138 * C-style signature:
139 *    u32 XEmacPs_BdRingGetFreeCnt(XEmacPs_BdRing* RingPtr)
140 *
141 *****************************************************************************/
142 #define XEmacPs_BdRingGetFreeCnt(RingPtr)   ((RingPtr)->FreeCnt)
143 
144 /****************************************************************************/
145 /**
146 * Return the next BD from BdPtr in a list.
147 *
148 * @param  RingPtr is the DMA channel to operate on.
149 * @param  BdPtr is the BD to operate on.
150 *
151 * @return The next BD in the list relative to the BdPtr parameter.
152 *
153 * @note
154 * C-style signature:
155 *    XEmacPs_Bd *XEmacPs_BdRingNext(XEmacPs_BdRing* RingPtr,
156 *                                      XEmacPs_Bd *BdPtr)
157 *
158 *****************************************************************************/
159 #define XEmacPs_BdRingNext(RingPtr, BdPtr)                           \
160     (((UINTPTR)((void *)(BdPtr)) >= (RingPtr)->HighBdAddr) ?                     \
161     (XEmacPs_Bd*)((void*)(RingPtr)->BaseBdAddr) :                              \
162     (XEmacPs_Bd*)((UINTPTR)((void *)(BdPtr)) + (RingPtr)->Separation))
163 
164 /****************************************************************************/
165 /**
166 * Return the previous BD from BdPtr in the list.
167 *
168 * @param  RingPtr is the DMA channel to operate on.
169 * @param  BdPtr is the BD to operate on
170 *
171 * @return The previous BD in the list relative to the BdPtr parameter.
172 *
173 * @note
174 * C-style signature:
175 *    XEmacPs_Bd *XEmacPs_BdRingPrev(XEmacPs_BdRing* RingPtr,
176 *                                      XEmacPs_Bd *BdPtr)
177 *
178 *****************************************************************************/
179 #define XEmacPs_BdRingPrev(RingPtr, BdPtr)                           \
180     (((UINTPTR)(BdPtr) <= (RingPtr)->BaseBdAddr) ?                     \
181     (XEmacPs_Bd*)(RingPtr)->HighBdAddr :                              \
182     (XEmacPs_Bd*)((UINTPTR)(BdPtr) - (RingPtr)->Separation))
183 
184 /************************** Function Prototypes ******************************/
185 
186 /*
187  * Scatter gather DMA related functions in xemacps_bdring.c
188  */
189 LONG XEmacPs_BdRingCreate(XEmacPs_BdRing * RingPtr, UINTPTR PhysAddr,
190               UINTPTR VirtAddr, u32 Alignment, u32 BdCount);
191 LONG XEmacPs_BdRingClone(XEmacPs_BdRing * RingPtr, XEmacPs_Bd * SrcBdPtr,
192              u8 Direction);
193 LONG XEmacPs_BdRingAlloc(XEmacPs_BdRing * RingPtr, u32 NumBd,
194              XEmacPs_Bd ** BdSetPtr);
195 LONG XEmacPs_BdRingUnAlloc(XEmacPs_BdRing * RingPtr, u32 NumBd,
196                XEmacPs_Bd * BdSetPtr);
197 LONG XEmacPs_BdRingToHw(XEmacPs_BdRing * RingPtr, u32 NumBd,
198             XEmacPs_Bd * BdSetPtr);
199 LONG XEmacPs_BdRingFree(XEmacPs_BdRing * RingPtr, u32 NumBd,
200             XEmacPs_Bd * BdSetPtr);
201 u32 XEmacPs_BdRingFromHwTx(XEmacPs_BdRing * RingPtr, u32 BdLimit,
202                  XEmacPs_Bd ** BdSetPtr);
203 u32 XEmacPs_BdRingFromHwRx(XEmacPs_BdRing * RingPtr, u32 BdLimit,
204                  XEmacPs_Bd ** BdSetPtr);
205 LONG XEmacPs_BdRingCheck(XEmacPs_BdRing * RingPtr, u8 Direction);
206 
207 void XEmacPs_BdRingPtrReset(XEmacPs_BdRing * RingPtr, void *virtaddrloc);
208 
209 #ifdef __cplusplus
210 }
211 #endif
212 
213 
214 #endif /* end of protection macros */
215 /** @} */
216