1 /******************************************************************************
3 * Copyright (C) 2004 - 2014 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /*****************************************************************************/
37 * The Xilinx Ethernet Lite (EmacLite) driver. This driver supports the Xilinx
38 * Ethernet Lite 10/100 MAC (EmacLite).
40 * The Xilinx Ethernet Lite 10/100 MAC supports the following features:
41 * - Media Independent Interface (MII) for connection to external
42 * 10/100 Mbps PHY transceivers
43 * - Independent internal transmit and receive buffers
44 * - CSMA/CD compliant operations for half-duplex modes
45 * - Unicast and broadcast
46 * - Automatic FCS insertion
47 * - Automatic pad insertion on transmit
48 * - Configurable ping/pong buffers for either/both transmit and receive
50 * - Interrupt driven mode
51 * - Internal loop back
52 * - MDIO Support to access PHY Registers
54 * The Xilinx Ethernet Lite 10/100 MAC does not support the following features:
55 * - multi-frame buffering
56 * only 1 transmit frame is allowed into each transmit buffer,
57 * only 1 receive frame is allowed into each receive buffer.
58 * the hardware blocks reception until buffer is emptied
59 * - Pause frame (flow control) detection in full-duplex mode
60 * - Programmable inter frame gap
61 * - Multicast and promiscuous address filtering
62 * - Automatic source address insertion or overwrite
64 * <b>Driver Description</b>
66 * The device driver enables higher layer software (e.g., an application) to
67 * communicate to the EmacLite. The driver handles transmission and reception
68 * of Ethernet frames, as well as configuration of the controller. It does not
69 * handle protocol stack functionality such as Link Layer Control (LLC) or the
70 * Address Resolution Protocol (ARP). The protocol stack that makes use of the
71 * driver handles this functionality. This implies that the driver is simply a
72 * pass-through mechanism between a protocol stack and the EmacLite.
74 * Since the driver is a simple pass-through mechanism between a protocol stack
75 * and the EmacLite, no assembly or disassembly of Ethernet frames is done at
76 * the driver-level. This assumes that the protocol stack passes a correctly
77 * formatted Ethernet frame to the driver for transmission, and that the driver
78 * does not validate the contents of an incoming frame. A single device driver
79 * can support multiple EmacLite devices.
81 * The driver supports interrupt driven mode and the default mode of operation
82 * is polled mode. If interrupts are desired, XEmacLite_InterruptEnable() must
85 * <b>Device Configuration</b>
87 * The device can be configured in various ways during the FPGA implementation
88 * process. Configuration parameters are stored in the xemaclite_g.c file.
89 * A table is defined where each entry contains configuration information for an
90 * EmacLite device. This information includes such things as the base address
91 * of the memory-mapped device and the number of buffers.
93 * <b>Interrupt Processing</b>
95 * After _Initialize is called, _InterruptEnable can be called to enable the
96 * interrupt driven functionality. If polled operation is desired, just call
97 * _Send and check the return code. If XST_FAILURE is returned, call _Send with
98 * the same data until XST_SUCCESS is returned. The same idea applies to _Recv.
99 * Call _Recv until the returned length is non-zero at which point the received
100 * data is in the buffer provided in the function call.
102 * The Transmit and Receive interrupts are enabled within the _InterruptEnable
103 * function and disabled in the _InterruptDisable function. The _Send and _Recv
104 * functions acknowledge the EmacLite generated interrupts associated with each
106 * It is the application's responsibility to acknowledge any associated Interrupt
107 * Controller interrupts if it is used in the system.
109 * <b>Memory Buffer Alignment</b>
111 * The alignment of the input/output buffers for the _Send and _Recv routine is
112 * not required to be 32 bits. If the buffer is not aligned on a 32-bit boundary
113 * there will be a performance impact while the driver aligns the data for
114 * transmission or upon reception.
116 * For optimum performance, the user should provide a 32-bit aligned buffer
117 * to the _Send and _Recv routines.
121 * Asserts are used within all Xilinx drivers to enforce constraints on argument
122 * values. Asserts can be turned off on a system-wide basis by defining, at
123 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
124 * is recommended that application developers leave asserts on during
129 * This driver requires EmacLite hardware version 1.01a and higher. It is not
130 * compatible with earlier versions of the EmacLite hardware. Use version 1.00a
131 * software driver for hardware version 1.00a/b.
133 * The RX hardware is enabled from powerup and there is no disable. It is
134 * possible that frames have been received prior to the initialization
135 * of the driver. If this situation is possible, call XEmacLite_FlushReceive()
136 * to empty the receive buffers after initialization.
138 * This driver is intended to be RTOS and processor independent. It works
139 * with physical addresses only. Any needs for dynamic memory management,
140 * threads or thread mutual exclusion, virtual memory, or cache control must
141 * be satisfied by the layer above this driver.
144 * MODIFICATION HISTORY:
146 * Ver Who Date Changes
147 * ----- ---- -------- -----------------------------------------------
148 * 1.01a ecm 01/30/04 First release
149 * 1.11a mta 03/21/07 Updated to new coding style
150 * 1.12a mta 11/28/07 Added the function XEmacLite_CfgInitialize,
151 * moved the functions XEmacLite_LookupConfig and
152 * XEmacLite_Initialize to xemaclite_sinit.c for removing
153 * the dependency on the static config table and
154 * xparameters.h from the driver initialization
155 * 1.13a sv 02/1/08 Updated the TxBufferAvailable routine to return
156 * busy status properly and added macros for Tx/Rx status
157 * 1.14a sdm 08/22/08 Removed support for static interrupt handlers from the MDD
159 * 2.00a ktn 02/16/09 Added support for MDIO and internal loop back
160 * 2.01a ktn 07/20/09 Updated the XEmacLite_AlignedWrite and
161 * XEmacLite_AlignedRead functions to use volatile
162 * variables so that they are not optimized.
163 * Modified the XEmacLite_EnableInterrupts and
164 * XEmacLite_DisableInterrupts functions to enable/disable
165 * the interrupt in the Ping buffer as this is used to enable
166 * the interrupts for both Ping and Pong Buffers.
167 * The interrupt enable bit in the Pong buffer is not used by
169 * Modified XEmacLite_Send function to use Ping buffers
170 * Interrupt enable bit since this alone is used to enable
171 * the interrupts for both Ping and Pong Buffers.
172 * 3.00a ktn 10/22/09 Updated driver to use the HAL Processor APIs/macros.
173 * The macros have been renamed to remove _m from the name in
174 * all the driver files.
175 * The macros changed in this file are
176 * XEmacLite_mNextTransmitAddr is XEmacLite_NextTransmitAddr,
177 * XEmacLite_mNextReceiveAddr is XEmacLite_NextReceiveAddr,
178 * XEmacLite_mIsMdioConfigured is XEmacLite_IsMdioConfigured,
179 * XEmacLite_mIsLoopbackConfigured is
180 * XEmacLite_IsLoopbackConfigured.
181 * See xemaclite_i.h for the macros which have changed.
182 * 3.01a ktn 07/08/10 The macro XEmacLite_GetReceiveDataLength in the
183 * xemaclite.c file is changed to a static function.
184 * XEmacLite_GetReceiveDataLength and XEmacLite_Recv
185 * functions are updated to support little endian
187 * 3.02a sdm 07/22/11 Removed redundant code in XEmacLite_Recv functions for
189 * 3.03a asa 04/05/12 Defined the flag __LITTLE_ENDIAN__ for cases where the
190 * driver is compiled with ARM toolchain.
191 * 3.04a srt 04/13/13 Removed warnings (CR 705000).
192 * 4.0 adk 19/12/13 Updated as per the New Tcl API's
197 ******************************************************************************/
198 #ifndef XEMACLITE_H /* prevent circular inclusions */
199 #define XEMACLITE_H /* by using protection macros */
205 /***************************** Include Files *********************************/
208 #include "xil_types.h"
209 #include "xil_assert.h"
211 #include "xemaclite_l.h"
214 #ifndef __LITTLE_ENDIAN__
215 #define __LITTLE_ENDIAN__
218 /************************** Constant Definitions *****************************/
222 #define XEL_DEVICE_NAME "xemaclite"
223 #define XEL_DEVICE_DESC "Xilinx Ethernet Lite 10/100 MAC"
225 /**************************** Type Definitions *******************************/
228 * This typedef contains configuration information for a device.
231 u16 DeviceId; /**< Unique ID of device */
232 u32 BaseAddress; /**< Device base address */
233 u8 TxPingPong; /**< 1 if TX Pong buffer configured, 0 otherwise */
234 u8 RxPingPong; /**< 1 if RX Pong buffer configured, 0 otherwise */
235 u8 MdioInclude; /**< 1 if MDIO is enabled, 0 otherwise */
236 u8 Loopback; /**< 1 if internal loopback is enabled, 0 otherwise */
241 * Callback when data is sent or received .
242 * @param CallBackRef is a callback reference passed in by the upper layer
243 * when setting the callback functions, and passed back to the
244 * upper layer when the callback is invoked.
246 typedef void (*XEmacLite_Handler) (void *CallBackRef);
249 * The XEmacLite driver instance data. The user is required to allocate a
250 * variable of this type for every EmacLite device in the system. A pointer
251 * to a variable of this type is then passed to the driver API functions.
254 XEmacLite_Config EmacLiteConfig; /* Device configuration */
255 u32 IsReady; /* Device is initialized and ready */
257 u32 NextTxBufferToUse; /* Next TX buffer to write to */
258 u32 NextRxBufferToUse; /* Next RX buffer to read from */
263 XEmacLite_Handler RecvHandler;
265 XEmacLite_Handler SendHandler;
270 /***************** Macros (Inline Functions) Definitions *********************/
272 /****************************************************************************/
275 * Return the next expected Transmit Buffer's address.
277 * @param InstancePtr is the pointer to the instance of the driver to
280 * @note C-Style signature:
281 * u32 XEmacLite_NextTransmitAddr(XEmacLite *InstancePtr);
283 * This macro returns the address of the next transmit buffer to put data into.
284 * This is used to determine the destination of the next transmit data frame.
286 *****************************************************************************/
287 #define XEmacLite_NextTransmitAddr(InstancePtr) \
288 ((InstancePtr)->EmacLiteConfig.BaseAddress + \
289 (InstancePtr)->NextTxBufferToUse) + XEL_TXBUFF_OFFSET
291 /****************************************************************************/
294 * Return the next expected Receive Buffer's address.
296 * @param InstancePtr is the pointer to the instance of the driver to
299 * @note C-Style signature:
300 * u32 XEmacLite_NextReceiveAddr(XEmacLite *InstancePtr);
302 * This macro returns the address of the next receive buffer to read data from.
303 * This is the expected receive buffer address if the driver is in sync.
305 *****************************************************************************/
306 #define XEmacLite_NextReceiveAddr(InstancePtr) \
307 ((InstancePtr)->EmacLiteConfig.BaseAddress + \
308 (InstancePtr)->NextRxBufferToUse)
310 /*****************************************************************************/
313 * This macro determines if the device is currently configured for MDIO.
315 * @param InstancePtr is the pointer to the instance of the
319 * - TRUE if the device is configured for MDIO.
320 * - FALSE if the device is NOT configured for MDIO.
322 * @note C-Style signature:
323 * int XEmacLite_IsMdioConfigured(XEmacLite *InstancePtr)
325 ******************************************************************************/
326 #define XEmacLite_IsMdioConfigured(InstancePtr) \
327 ((InstancePtr)->EmacLiteConfig.MdioInclude == 1)
329 /*****************************************************************************/
332 * This macro determines if the device is currently configured for internal
335 * @param InstancePtr is the pointer to the instance of the
339 * - TRUE if the device is configured for internal loopback.
340 * - FALSE if the device is NOT configured for internal loopback.
342 * @note C-Style signature:
343 * int XEmacLite_IsLoopbackConfigured(XEmacLite *InstancePtr)
345 ******************************************************************************/
346 #define XEmacLite_IsLoopbackConfigured(InstancePtr) \
347 ((InstancePtr)->EmacLiteConfig.Loopback == 1)
349 /************************** Variable Definitions *****************************/
351 /************************** Function Prototypes ******************************/
354 * Functions in xemaclite.c
356 int XEmacLite_CfgInitialize(XEmacLite *InstancePtr,
357 XEmacLite_Config *EmacLiteConfigPtr,
359 void XEmacLite_SetMacAddress(XEmacLite *InstancePtr, u8 *AddressPtr);
360 int XEmacLite_TxBufferAvailable(XEmacLite *InstancePtr);
361 void XEmacLite_FlushReceive(XEmacLite *InstancePtr);
363 int XEmacLite_Send(XEmacLite *InstancePtr, u8 *FramePtr, unsigned ByteCount);
364 u16 XEmacLite_Recv(XEmacLite *InstancePtr, u8 *FramePtr);
366 int XEmacLite_PhyRead(XEmacLite *InstancePtr, u32 PhyAddress, u32 RegNum,
368 int XEmacLite_PhyWrite(XEmacLite *InstancePtr, u32 PhyAddress, u32 RegNum,
371 void XEmacLite_EnableLoopBack(XEmacLite *InstancePtr);
372 void XEmacLite_DisableLoopBack(XEmacLite *InstancePtr);
375 * Initialization functions in xemaclite_sinit.c
377 XEmacLite_Config *XEmacLite_LookupConfig(u16 DeviceId);
378 int XEmacLite_Initialize(XEmacLite *InstancePtr, u16 DeviceId);
381 * Interrupt driven functions in xemaclite_intr.c
383 int XEmacLite_EnableInterrupts(XEmacLite *InstancePtr);
384 void XEmacLite_DisableInterrupts(XEmacLite *InstancePtr);
386 void XEmacLite_InterruptHandler(void *InstancePtr);
388 void XEmacLite_SetRecvHandler(XEmacLite *InstancePtr, void *CallBackRef,
389 XEmacLite_Handler FuncPtr);
390 void XEmacLite_SetSendHandler(XEmacLite *InstancePtr, void *CallBackRef,
391 XEmacLite_Handler FuncPtr);
394 * Selftest function in xemaclite_selftest.c
396 int XEmacLite_SelfTest(XEmacLite *InstancePtr);
402 #endif /* end of protection macro */