This page provides details related to the light weight IP (LWIP) library and the SW app lwip echo server.

Table of Contents

Introduction

LWIP220 provides a light weight TCP/IP stack to use with ethernet interfaces. It supports:

• GEM on Zynq, Zynq Ultrascale+ MPSoC and Versal (using emacps driver)

• AXI ethernet (using axiethernet driver)

How to enable

• lwip220 library can be found at
  https://github.com/Xilinx/embeddedsw/tree/master/ThirdParty/sw_services/lwip220
  lwip220
  |
  - src - Driver source files which are further organized into
  ||
  ---- lwip-2.2.0

• lwip_echo_server is an application demonstrating the use of lwip library with a basic echo test using telnet. It can be found at
  https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/lwip_echo_server

Features supported

1. GEM on Zynq/ZynqMP/Versal

Controller/Driver features supported

• All the basic controller features are supported through the controller driver emacps - 10/100/1000 speeds, PHY management, DMA, Packet buffer support, Checksum offload.

• ZynqMP and Versal only: 64 bit descriptor support, Priority queue support, Jumbo frame support.

• Support for common/shared MDIO bus across multiple GEM instances (e.g., KR260, VCK190), allowing multiple GEMs to share a single MDIO bus for PHY management.

Stack Features

• TCP

• UDP

• DHCP

PHY configurations

lwip echo server supports the following PHY configurations:

Associating a specific PHY DT node to PS GEM

• Default LWIP PS GEM implementation searches from PHY from address 31 down to 0 to detect a PHY connected over its MDIO.

• In some board configurations, it may be desirable for users to specifically associate a PHY with a given GEM (for example when more than one PHY is connected to the MDIO but GEM0 needs to be used PHY@2). This can be supported by specifying the "phy-handle" devicetree property.

• This devicetree description is already present in the board specific devicetree files for AMD evaluation boards. See versal (applicable to both vmk180 and vck190 boards) for ex., https://github.com/Xilinx/u-boot-xlnx/blob/master/arch/arm/dts/versal-vmk180-revA.dts#L81

• This board devicetree or any customer user defined devicetree snippet can be passed to Vitis Unified IDE while creating a platform, via an Advanced options: https://adaptivesupport.amd.com/s/article/Unlocking-the-Potential-of-the-System-Device-Tree-SDT-in-Vitis-Unified-IDE?language=en_US

2. AXI Ethernet on Microblaze/Zynq/ZynqMP/Microblaze-V

Controller/Driver features supported

• Support for MII, GMII, RGMII, SGMII, and 1000BASE-X PHY interfaces

• Support for Check sum offloading.

• Supports AXI DMA + 1G Ethernet Configuration on KC705//KCU105Zynq/ZynqMP Platforms

• Supports AXI FIFO + 1G Ethernet Configuration.

• Supports AXI Ethernet + AXIDMA Configuration with Microblaze-V(KCU105,SP701)

• Supports AXI Ethernet + FIFO Configuration with Microblaze(KCU105)

Stack Features

• TCP

• UDP

• DHCP

• IGMP

• Multicast

PHY configurations

lwip echo server supports the following PHY configurations

3. AXI Ethernetlite (Emaclite) on Microblaze

Controller/Driver features supported

• Supports MII interface.

• Supports 10/100Mbps.

Stack Features

• TCP

• UDP

• DHCP

• IGMP

PHY configurations

MII PHY support

Features not supported

• The following features are not supported:

  • MCDMA

  • 10G/25G MAC

Performance

These benchmark performance numbers were obtained by connecting Xilinx boards to Linux PCs/server machines (Ubuntu/Red Hat Enterprise).
The application used is the lwip SW app (see test cases below) with optimal settings on the board side. iperf2 is run on the linux machine.

Zynq

Board: ZC706
CPU Freq: 666MHz (A9)
Link Speed: 1000Mbps, Full duplex

ZynqMP

Board: ZCU102
CPU Freq 1100MHz (A53)
Link Speed 1000Mbps, Full duplex
DDR 533MHz
CCU: No

Versal

Board: vck190

CPU Freq: 1349MHz(A72)

Link Speed 1000Mbps, Full duplex

DDR:

CCU: No

Note: Socket mode performance on Xilinx 2020.1 is 19% lower than 2019 and it is recommended to use the next release for better performance.

Test cases

Echo server

lwip echo server is used to test lwip library with a basic TCP echo application.
Create an lwip echo server application. Run fsbl and then lwip echo server elf.
On the link partner, run
telnet <ip address> 7

Note: If DHCP is not being used (enabled by default), make sure to set static IP addresses in the same group in lwip echo server and the link partner machine.

Sample expected output:

Refer to https://github.com/Xilinx/embeddedsw/blob/master/lib/sw_apps/lwip_echo_server/src/README.txt for more information.

Performance tests

Performance measurement with lwip library can be done using the TCP/UDP server/client SW apps:
Raw mode:
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/lwip_tcp_perf_server
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/lwip_tcp_perf_client
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/lwip_udp_perf_server
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/lwip_udp_perf_client
Socket mode:
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_tcp_perf_server
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_tcp_perf_client
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_udp_perf_server
https://github.com/Xilinx/embeddedsw/tree/master/lib/sw_apps/freertos_lwip_udp_perf_client

Xilinx HW running one of the above lwip applications can be connected to a standard linux machine (Ubuntu) to obtain optimal performance numbers.
Raw or socket mode TCP/UDP client/server can be run on Xilinx HW while the iperf server/client (in suitable pairs) can be run on the linux machine.
Refer to the SW apps' README files for more information

NOTE: These performance tests are not supported or benchmarked with emaclite. The application throws an error message to indicate the same when built on emaclite designs.

Miscellaneous functional test

lwip library examples folder contains additional functional tests such as:
- IGMP test case
- TFTP server test case
- TFTP client test case
- Webserver test case
Please refer to this readme file for additional information:

https://github.com/Xilinx/embeddedsw/blob/master/ThirdParty/sw_services/lwip220/examples/README.txt

Known issues/Limitations

• No support for 1588

• No Support for 10G/25G

• No MCDMA support

• Performance numbers are not benchmarked on PL interfaces on Microblaze

• lwip perf client application cannot be rerun without a power on reset. For ex., doing rst -proc from xsdb before downloading the executable again does not work. It is required to perform "power 0 power 1" in systest before running a new test.

• LWIP examples (IGMP, webserver and TFTP) are not ported to SDT flow.

• Clock change is not automatically handled in lwip adapter for GEM in SDT flow currently. Clock registers can still be manually modified by users. Support for automatically handling this through baremetal clocking framework will be added in an upcoming release.

• LWIP open source code is not supported with C++

• LWIP is not supported with 64 bit Microblaze

• LWIP applications are meant as reference and may not always have board specific support such as specific PHY resets. If there's a GPIO or I2C based reset on board, this can be added to the application by users.

• The lwip speed configuration CONFIG_LINKSPEED_AUTODETECT is only supported. it won’t support CONFIG_LINKSPEED10, CONFIG_LINKSPEED100 and CONFIG_LINKSPEED1000.

1. GEM

None

2. AXI Ethernet

• The current lwip stack won't support 1G Non processor/Non buffered mode feature

• No Support for Legacy 10G and 10G/25G MAC.

Current ARs

• There is an issue with freertos support for AXI Ethernet + FIFO designs in 2017.1 and 2017.2. For details refer to AR-69578.

• Emaclite support in lwip is broken in 2018.2. Please refer to AR-71330.

• USE_JUMBO_FRAME configuration option is missing in SDT flow, this is fixed in a future release. <AR link TBD>

Change log

2025.2
(NOTE: The version is lwip220_v1_3)
https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2025.2/doc/ChangeLog#L213

2025.1
(NOTE: The version is lwip220_v1_2)

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2025.1/doc/ChangeLog#L133

2024.2
(NOTE: The version is lwip220_v1_1)

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2024.2/doc/ChangeLog#L453

2024.1

(NOTE: The version is lwip220_v1_0)

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2024.1/doc/ChangeLog#L154

2023.2

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2023.2/doc/ChangeLog#L537

2023.1

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2023.1/doc/ChangeLog#L231

2022.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2022.2/doc/ChangeLog#L178

2022.1

https://github.com/Xilinx/embeddedsw/blob/xilinx_v2022.1/doc/ChangeLog#L161

2021.2

https://github.com/Xilinx/embeddedsw/blob/xlnx_rel_v2021.2/doc/ChangeLog#L138

2020.2

Summary:

• Bugfixes related to RX BD setup, RX pbuf handling in error path, mkfs format in examples, VCU118 PHY handling and lwip timer & delay handling.

• Minor changes in lwip app tcl checks and usage of canonical definitions.

Commits:

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2020.2/ThirdParty/sw_services/lwip211

2020.1

Summary:

• Minor enhancements to Makefile and dependencies.props file.

• Removed xps timer reference in lwip SW apps as it is no longer supported.

Commits:

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2020.1/ThirdParty/sw_services/lwip211

3e7863e sw_apps: Remove xps_timer reference

2019.2

Summary:

• Minor enhancements; Bug fix related to hotplug support.

Commits:

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2019.2/ThirdParty/sw_services/lwip211

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2019.2/lib/sw_apps/lwip_echo_server

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2019.2/lib/sw_apps/freertos_lwip_echo_server

3ad626b lwip211: Fix comment and print statements typos
87cc506 Fixed trivial typos for lwip211 reported by codespell utility
cbe08cc lwip211: Fix emacps hotplug support
9378ccb lwip211: Add support for A53 32 bit compiler

2019.1

Summary:

• Upgraded lwip to open source 2.1.1

• Bug fixes

Commits

https://github.com/Xilinx/embeddedsw/commits/xilinx-v2019.1/ThirdParty/sw_services/lwip211

d00b7a1 Add lwip 2.1.1 base source
6f3c2aa lwip211: Copy existing adapter
84b2ccf lwip211: Port Xilinx specific lwip changes to source
4c450f2 lwip211: Copy examples folder
3ea5d43 lwip211: Fix cache handling in RX path for GEM
fa31392 lwip211: Define NO_CTYPE for R5
f8c1904 lwip211: Fix freertos echo server compilation on emaclite platform
a67456b ThirdParty: Update to be inline with standalone BSP structure
30b9744 lwip211: Fix compiler for R5
5f1e123 lwip211: Update examples according to new xilffs prototypes
3127546 lwip211: Add 8 byte padding for IEEE1588 on PL Ethernet b738e79 lwip: Update lwip tcl with psv_ethernet IP name e8e43fd lwip211: Fix BYTE_ORDER redefined warning f7404ed lwip211: Fix gcc warnings in emaclite adapter sourcead05b02 lwip211: Fix emaclite xemacliteif_input freertos implementation