emaclite
Xilinx Vitis Drivers API Documentation
emaclite Documentation

The Xilinx Ethernet Lite (EmacLite) driver. This driver supports the Xilinx Ethernet Lite 10/100 MAC (EmacLite).

The Xilinx Ethernet Lite 10/100 MAC supports the following features:

  • Media Independent Interface (MII) for connection to external 10/100 Mbps PHY transceivers
  • Independent internal transmit and receive buffers
  • CSMA/CD compliant operations for half-duplex modes
  • Unicast and broadcast
  • Automatic FCS insertion
  • Automatic pad insertion on transmit
  • Configurable ping/pong buffers for either/both transmit and receive buffer areas
  • Interrupt driven mode
  • Internal loop back
  • MDIO Support to access PHY Registers

The Xilinx Ethernet Lite 10/100 MAC does not support the following features:

  • multi-frame buffering only 1 transmit frame is allowed into each transmit buffer, only 1 receive frame is allowed into each receive buffer. the hardware blocks reception until buffer is emptied
  • Pause frame (flow control) detection in full-duplex mode
  • Programmable inter frame gap
  • Multicast and promiscuous address filtering
  • Automatic source address insertion or overwrite

Driver Description

The device driver enables higher layer software (e.g., an application) to communicate to the EmacLite. The driver handles transmission and reception of Ethernet frames, as well as configuration of the controller. It does not handle protocol stack functionality such as Link Layer Control (LLC) or the Address Resolution Protocol (ARP). The protocol stack that makes use of the driver handles this functionality. This implies that the driver is simply a pass-through mechanism between a protocol stack and the EmacLite.

Since the driver is a simple pass-through mechanism between a protocol stack and the EmacLite, no assembly or disassembly of Ethernet frames is done at the driver-level. This assumes that the protocol stack passes a correctly formatted Ethernet frame to the driver for transmission, and that the driver does not validate the contents of an incoming frame. A single device driver can support multiple EmacLite devices.

The driver supports interrupt driven mode and the default mode of operation is polled mode. If interrupts are desired, XEmacLite_InterruptEnable() must be called.

Device Configuration

The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the xemaclite_g.c file. A table is defined where each entry contains configuration information for an EmacLite device. This information includes such things as the base address of the memory-mapped device and the number of buffers.

Interrupt Processing

After _Initialize is called, _InterruptEnable can be called to enable the interrupt driven functionality. If polled operation is desired, just call _Send and check the return code. If XST_FAILURE is returned, call _Send with the same data until XST_SUCCESS is returned. The same idea applies to _Recv. Call _Recv until the returned length is non-zero at which point the received data is in the buffer provided in the function call.

The Transmit and Receive interrupts are enabled within the _InterruptEnable function and disabled in the _InterruptDisable function. The _Send and _Recv functions acknowledge the EmacLite generated interrupts associated with each function. It is the application's responsibility to acknowledge any associated Interrupt Controller interrupts if it is used in the system.

Memory Buffer Alignment

The alignment of the input/output buffers for the _Send and _Recv routine is not required to be 32 bits. If the buffer is not aligned on a 32-bit boundary there will be a performance impact while the driver aligns the data for transmission or upon reception.

For optimum performance, the user should provide a 32-bit aligned buffer to the _Send and _Recv routines.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that application developers leave asserts on during development.

Note

This driver requires EmacLite hardware version 1.01a and higher. It is not compatible with earlier versions of the EmacLite hardware. Use version 1.00a software driver for hardware version 1.00a/b.

The RX hardware is enabled from powerup and there is no disable. It is possible that frames have been received prior to the initialization of the driver. If this situation is possible, call XEmacLite_FlushReceive() to empty the receive buffers after initialization.

This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads or thread mutual exclusion, virtual memory, or cache control must be satisfied by the layer above this driver.

MODIFICATION HISTORY:
Ver   Who  Date     Changes


1.01a ecm 01/30/04 First release 1.11a mta 03/21/07 Updated to new coding style 1.12a mta 11/28/07 Added the function XEmacLite_CfgInitialize, moved the functions XEmacLite_LookupConfig and XEmacLite_Initialize to xemaclite_sinit.c for removing the dependency on the static config table and xparameters.h from the driver initialization 1.13a sv 02/1/08 Updated the TxBufferAvailable routine to return busy status properly and added macros for Tx/Rx status 1.14a sdm 08/22/08 Removed support for static interrupt handlers from the MDD file 2.00a ktn 02/16/09 Added support for MDIO and internal loop back 2.01a ktn 07/20/09 Updated the XEmacLite_AlignedWrite and XEmacLite_AlignedRead functions to use volatile variables so that they are not optimized. Modified the XEmacLite_EnableInterrupts and XEmacLite_DisableInterrupts functions to enable/disable the interrupt in the Ping buffer as this is used to enable the interrupts for both Ping and Pong Buffers. The interrupt enable bit in the Pong buffer is not used by the HW. Modified XEmacLite_Send function to use Ping buffers Interrupt enable bit since this alone is used to enable the interrupts for both Ping and Pong Buffers. 3.00a ktn 10/22/09 Updated driver to use the HAL Processor APIs/macros. The macros have been renamed to remove _m from the name in all the driver files. The macros changed in this file are XEmacLite_mNextTransmitAddr is XEmacLite_NextTransmitAddr, XEmacLite_mNextReceiveAddr is XEmacLite_NextReceiveAddr, XEmacLite_mIsMdioConfigured is XEmacLite_IsMdioConfigured, XEmacLite_mIsLoopbackConfigured is XEmacLite_IsLoopbackConfigured. See xemaclite_i.h for the macros which have changed. 3.01a ktn 07/08/10 The macro XEmacLite_GetReceiveDataLength in the xemaclite.c file is changed to a static function. XEmacLite_GetReceiveDataLength and XEmacLite_Recv functions are updated to support little endian MicroBlaze. 3.02a sdm 07/22/11 Removed redundant code in XEmacLite_Recv functions for CR617290 3.03a asa 04/05/12 Defined the flag LITTLE_ENDIAN for cases where the driver is compiled with ARM toolchain. 3.04a srt 04/13/13 Removed warnings (CR 705000). 4.0 adk 19/12/13 Updated as per the New Tcl API's 4.1 nsk 07/13/15 Added Length check in XEmacLite_AlignedWrite function in xemaclite_l.c file to avoid extra write operation (CR 843707). 4.2 sk 11/10/15 Used UINTPTR instead of u32 for Baseaddress CR# 867425. Changed the prototype of XEmacLite_CfgInitialize API. 4.2 adk 11/18/15 Fix compilation errors due to conflicting data types CR#917930 4.2 adk 29/02/16 Updated interrupt example to support Zynq and ZynqMP CR#938244. 4.3 asa 08/27/16 Fix compilation warning by making change xemaclite_l.c ms 01/23/17 Added xil_printf statement in main function for all examples to ensure that "Successfully ran" and "Failed" strings are available in all examples. This is a fix for CR-965028. ms 03/17/17 Modified text file in examples folder for doxygen generation.