Introduction

This page offers detailed information about the standalone emacps driver. The driver enables GEM support for Versal Gen2, Versal, Zynq Ultrascale+ MPSoC, and Zynq devices.
For further details, please refer to the GEM Ethernet chapter in the following Technical Reference Manuals (TRMs): Versal TRM (AM011), Zynq TRM (UG585), or ZynqMP TRM (UG1085).

1 Introduction
2 Driver Sources
3 Driver Implementation
- 3.1 Features
  - 3.1.1 Controller/Driver features supported
  - 3.1.2 PHY configurations
- 3.2 Known Issues and Limitations
- 3.3 Interop
4 Example Applications
- 4.1 Links to Examples
  - 4.1.1 Example Application Usage
5 Example Design Architecture
6 Performance
7 Change Log
8 Related Links

Driver Sources

The source code for the driver is available in the Xilinx GitHub repository and is included as part of the Vitis Unified Software Platform installation.

^{Driver Name}	^Emacps

^{Driver Name}	^Emacps
Vitis	<Vitis Install Directory>/data/embedded/XilinxProcessorIPLib/drivers/emacps
Github	https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/emacps

Note: To view the sources for a particular release, use the rel-version tag in github.
For example, for the 2021.1 release, the proper version of the code is
https://github.com/Xilinx/embeddedsw/tree/xilinx_v2021.1/XilinxProcessorIPLib/drivers/emacps

Driver source code organisation

├── data : Driver .tcl, .mdd file and .yaml files
├── examples : Example applications that show how to use the driver features
└── src : Driver source files, make and cmake files

The emacps.yaml located in the data/ and the CMakeLists.txt found in the src/ are crucial components for the System Device Tree-based workflow.
The emacps.tcl and emacps.mdd files associated with the driver are intended for the previous build flow, which is set to be phased out in the future.
The 2023.2 release has introduced an updated build flow for AMD Xilinx embedded software, incorporating a new system device tree-based approach
- Porting embeddedsw components to system device tree (SDT) based flow - Xilinx Wiki - Confluence (atlassian.net)

Driver Implementation

For a comprehensive list of features supported by this IP, please consult the GEM Chapter in the Zynq TRM (UG585), ZynqMP TRM (UG1085), or Versal TRM (AM011) for the respective devices.

Features

Controller/Driver features supported

The system supports speeds of 10/100/1000 Mbps and includes PHY/external loopback functionality, which is available in EMACPS.
PHY management
MMI 10Gbe support with SFP (without PHY) external loopback connector.
The features include DMA, packet buffer support, checksum offload, FCS stripping, programmable inter-packet gap (IPG), as well as multicasting, promiscuous, and broadcast modes.
The controller supports flow control and half-duplex features; however, these functionalities are not illustrated in the provided examples.
ZynqMP and Versal only: 64 bit descriptor support, Priority queue support, Jumbo frame support, CCI support
Common MDIO support: Multiple GEM instances can now share a single MDIO bus for PHY management. Boards such as KR260 and VCK190 utilize this feature.

PHY configurations

The emacps driver example accommodates the following PHY configurations:

Family	PHY	Support

Family	PHY	Support
Zynq	RGMII	supported in HW and driver example
ZynqMP	RGMII	supported in HW and driver example
ZynqMP	SGMII	supported in HW and driver example
Versal	RGMII	supported in HW and driver example

Known Issues and Limitations

The following features are not supported:
- External FIFO interface: This driver exclusively targets DMA.
- Partial store and forward: This feature is not supported.
Currently, the example in the SDT flow does not automatically manage clock changes. However, users still have the ability to manually adjust the clock registers. Future updates will include support for automatic handling of this feature through the baremetal clocking framework.
- The legacy XPAR values for clock divisors pertaining to 10/100/1000 Mbps are also not exported in the SDT flow, starting from the Vitis Unified 2024.1 release.
XPAR properties for the following items are not produced in the SDT flow, specifically from the launch of the Vitis Unified 2024.1 release:
1. XPAR for GMII2RGMII in the design is now automatically generated in SDT as "gmiitorgmii-addr". Please utilise the corresponding GMII2RGMII PHY address entry within the Config structure, starting from the 2025.1 release.
2. XPAR for Soft PCS/PMA in the design is now automatically generated in SDT as "phy-mode." To identify the PCS PMA (SGMII/1000BaseX) PHY within the design, utilize the standard PHY scanning and identifier registers, as well as the PhyType in the Config structure. For further details, please refer to xemacpsif_physpeed.c in the AMD lwIP adapter implementation.

Interop

The Marvell 88E1116 PHY device has been successfully tested on the Zynq evaluation board.
The following PHY devices have undergone testing on the ZynqMP: Marvell 88E1512, TI DP83867 (both RGMII and SGMII), VSC8211, and RTL8211.
On the Versal platform, the tested PHY devices include Marvell 88E1512, TI DP83867, VSC8531_02, and RTL8211DN.
On Versal Gen2 platform, the tested PHY device(s) include TI DP83867

Example Applications

The Emacps driver offers a DMA-based loopback example, illustrating how to leverage its various features effectively. Users can easily import these example applications into the Vitis IDE via the Board Support Package settings tab.

Links to Examples

Examples Path:
https://github.com/Xilinx/embeddedsw/tree/master/XilinxProcessorIPLib/drivers/emacps

Test Name	Example Source	Description

Test Name

Example Source

Description

Emacps DMA loopback example

xemacps_example_intr_dma.c

xemacps_example.h

xemacps_example_util.c

Emacps' fundamental DMA loopback examples facilitate the sending and receiving of multiple single frames in loopback mode.
Refer to Emacps_example_readme.txt for more information.

In emacps 1588, examples were deprecated as they were originally added as a reference for Zynq-7000, but the timestamping logic in that version of the IP has issues, rendering this feature unusable. These examples were removed in the 2021.1 release.

Example Application Usage

Emacps DMA loopback example

Emacps' DMA-loopback example demonstrates the sending and receiving of multiple single frames with different payload sizes in loopback mode.

MMI 10GBe Build Instructions

The Versal Gen2 device is equipped with three GEMs: GEM0, GEM1, and MMI_10GBe. By default, both GEM0 and MMI_10GBe are enabled in the designs.
The application is compiled for GEM0 by default, as the initial base address is always set to GEM0. To utilize MMI_10GBe, the following modification must be made in the example application code.
--- a/XilinxProcessorIPLib/drivers/emacps/examples/xemacps_example_intr_dma.c +++ b/XilinxProcessorIPLib/drivers/emacps/examples/xemacps_example_intr_dma.c @@ -136,7 +136,7 @@ #endif #ifdef SDT -#define EMACPS_BASEADDR XPAR_XEMACPS_0_BASEADDR +#define EMACPS_BASEADDR XPAR_XEMACPS_1_BASEADDR #elif XPAR_INTC_0_DEVICE_ID #define INTC XIntc #define EMACPS_DEVICE_ID XPAR_XEMACPS_0_DEVICE_ID

Expected Output

Entering into main()
Running Emacps example on 10GBE
Packet: 1       Queue: 1        Payload size: 6761
Packet: 2       Queue: 2        Payload size: 514
Packet: 3       Queue: 3        Payload size: 3694
Packet: 4       Queue: 0        Payload size: 5413
Packet: 5       Queue: 1        Payload size: 2228
Packet: 6       Queue: 2        Payload size: 4676
Packet: 7       Queue: 3        Payload size: 9875
Packet: 8       Queue: 0        Payload size: 1956
Packet: 9       Queue: 1        Payload size: 3492
Packet: 10      Queue: 2        Payload size: 1979
Packet: 11      Queue: 3        Payload size: 3258
Packet: 12      Queue: 0        Payload size: 8666
Total Packets sent: 12
Total Packets received: 12
Successfully ran Emacps intr dma Example

Example Design Architecture

NA

Performance

Standalone Ethernet performance is benchmarked with the use of a lightweight IP library and application. Please refer to
http://www.wiki.xilinx.com/Standalone+LWIP+library#Performance