Standalone LWIP library

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

Table of Contents

Introduction

LWIP211 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

  1. lwip211 library can be found at
    https://github.com/Xilinx/embeddedsw/tree/master/ThirdParty/sw_services/lwip211
    lwip211
    |
    - doc - Provides the API and data structure details
    |
    - src - Driver source files which are further organized into
    ||
    ---- contrib/ports/xilinx - Contains the interface specific implementation
    ||
    ---- lwip-2.0.2 - Contains the stack implementation
  2. 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.

Stack Features

  • TCP
  • UDP
  • DHCP

PHY configurations

lwip echo server supports the following PHY configurations:

FamilyPHYSupportRemarks
ZynqRGMIIYes

SGMII in PLYesRefer to AR# 66006

1000BaseX in PLYesRefer to AR# 66006

GMII2RGMII convertor in PLYes
ZynqMPRGMIIYes

SGMIINo

SGMII in PLYesRefer to xapp1306

1000BaseX in PLYesRefer to xapp1306

GMII2RGMII convertor in PLYes
VersalRGMIIYes



2. AXI Ethernet on Microblaze/Zynq/ZynqMP

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.

Stack Features

  • TCP
  • UDP
  • DHCP
  • IGMP
  • Multicast

PHY configurations

lwip echo server supports the following PHY configurations

FamilyPHYSupportRemarks
KC705GMIIYes

RGMIIYes

SGMIIYes

1000Base-xYes
ZYNQSGMIIYesRefer to AR# 66006

1000Base-XYesRefer to AR# 66006
ZYNQMPSGMIIYes

1000Base-xYes

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. iperf is run on the linux machine.

Zynq

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


TCPUDP
MTURx (Mbps)Tx (Mbps)RX (Mbps)TX (Mbps)
1500949949957956

ZynqMP

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


TCPUDP
MTURx (Mbps)Tx (Mbps)Rx (Mbps)Tx (Mbps)
1500949935957956


The above number are for raw mode (baremetal).

Socket mode(FreeRTOS) number shall be updated from next release.

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.

2020.2 lwip numbers:


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/lwip211/examples/README.txt

Known issues/Limitations

  • No support for 1588
  • No Support for 10G/25G

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.

Change log

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 source
ad05b02 lwip211: Fix emaclite xemacliteif_input freertos implementation 

lwip SW app commits:

590e779 sw_apps: Update mss files to add xilmem library
c5e6b96 lwip: Update SW apps to use the new version
2cd4174 lib: Remove xilmem and xilstandalone library dependencies
4bfb9a3 lwip: Update lwip tcl with psv_ethernet IP name


2018.3

  • Added support for 2.5G Ethernet
  • Added support for MCDMA
  • Bugfixes

Commits:

3bbb430 LwIP202: Update tcl to define 1588 macro in xlwipconfig.h
19f27c5 LwIP202: Handle IEEE_1588 for SGMII Phy
87d18bc LwIP202: Add support of AXI mcdma
11fb752 LwIP202: Update tcl and makefile for axi_mcdma
bab8511 LwIP202: Add AXI 2.5G Ethernet support in LwIP
62c4cb0 Adds PHY management with hotplug support for lwip with emaclite
4d5942a lwip202: Correct emaclite instance assignement
c931b9c lwip: Fix axiethernet applications build failure
e976415 lwip: Use -hier option while using get_cells command
f457c19 lwip202: Fix warning for redefining BYTE_ORDER

lwip SW app changes:

e1c8092 echo_server: Increase pool size
ffd23af lwip_echo_server: Fix warning for return in IIC PHY reset
d2617fb lwip: Resolved compilation warning from platform_zynqmp.c for a53 and R5


2018.2

  • Added hotplug support and minor fixes

dad2851 LwIP202: Avoid redundant axi ethernet config lookup & init
6a26aa9 LwIP202: Moved IEEE registers to separate header file
51db440 LwIP202: Hot plug detect support for EmacPS and AXI Ethernet
lwip echo server changes:
7fae789 Update standalone Echo-server app for hot plug detect


2018.1

  • Added new lwip202 version. lwip141 is deprecated and will be removed from the repository subsequently.

464fc11 LwIP202: Initial commit of LwIP v2.0.2 base source
afca857 LwIP202: copy contrib, Makefile, Changelog from LwIP141
5386fbc LwIP202: Port Xilinx changes
c330050 LwIP202: port contrib folder for LwIP202
cc60e3b LwIP202: port Makefile and Makefile.lwip
d055fe3 LwIP202: Add data folder with mld and tcl file
d60b673 LwIP202: Remove PPC references
cced15e LwIP202: Update Changelog
b06c350 LwIP202: Add IGMP support in xemacps contrib code
2e39353 lwIP202: Add workaround for RX hang in Zynq when using freertos
af32819 lwIP202: Disable L1 prefetch for ARMv8
1bae15c LWIP: Add IPv6 support in lwip202 lib
dad94a9 LWIP: Enable IPv6 support
891972d LWIP: Add Multicast MAC support in hash table
2250808 lwIP202: Options to configure mbox parameters
62df22f lwIP202: Correct proper references of TX BD ring
821796b lwip202: Perform AXI DMA lookup based on base address
289e647 lwip202: Fix jumbo frame checks on R5
b663922 lwip202: Move lwip raw sw apps to examples
cb51032 lwip202: Move lwip socket apps to examples
af0b812 lwip202: Update xInsideISR in emacps_error_handler
a219109 lwip202: Use UINTPTR for axidma base address
09aa57d lwip202: Add support for Realtek phy
32159f4 ThirdParty: Added latest freertos port, freertos10
bbeb096 lwip202: Correct example header names
c7efa4d lwip202: Update lwip socket mode example headers

lwip echo server changes:
6886e45 Update echo server code to work with LwIP 2.0.2
179815b Update echo server mss and tcl to use LwIP 2.0.2
7160846 LWIP: IPv6 Echo server raw mode application
0766f57 LWIP: IPv6 echo server freertos application
190fed8 lib: Updated mld/tcl files of sw_apps and libraries to pick up latest Freertos port 10.0

2017.4

019e94e lwip141: Correct tx bd ring assigments in xemacpsif
27e168d lwip141: Perform AXI DMA lookup based on base address. In multi dma design lookup based on the base address ensures that correct DMA instance is selected.
No changes in lwip echo server and freertos lwip echo server

2017.3

dd92d60 lwip: Add support for EL1 non secure mode
d602f73 lwip: Add SW workaround for TI DP83867 PHY Data integrity issues
811c4a5 lwip: Add freertos support for axiethernet fifo configuration
3221f51 lwip: Correct compiler used for A9
2133760 lwip: Update lwip compiler for A9
100857a lwip141: Make changes to fix conflicting types for xInsideISR
bdd7319 lwip141: Fix for various warnings in the AxiEthernet adapter
0200b10 lwip: Changes for CCI
e78aad2 lwip: Add workaround for RX hang in Zynq when using freertos
cab9ffe lwip141: Disable L1 prefetch for ARMv8
595b2da lwip141: Disable L1 prefetch for AXI DMA in lwip adapter
No changes in lwip echo server and freertos lwip echo server

2017.2

No changes in lwip library and lwip echo server


2017.1

c3fd75c lwip: Detect Xilinx PCS PMA with PHY addr
9fe3dc8 lwip: Add support for TI PHY DP83867 SGMII Configuration (AXI Ethernet)
317b53e lwip: Expose NO_SYS_NO_TIMERS and LWIP_TCP_KEEPALIVE to user
b15331e lwip : Fixed compilation warnings
7c56069 sw_apps, sw_services: updated tcl and mld file with latest freertos port name (lwip and freertos echo server)
749eade lwip: Add jumbo frame support for ZynqMP ethernet
33b4e72 lwip: Correct erroneous write to TI PHYCR register
417f848 lwip: Add SW workaround for TI DP83867 PHY link instability
905bab1 lwip: Update correct compiler details even when no ethernet is found

2016.4

7641174 lwip: Fix Axi Ethernet performance issue on ZynqMP
9062987 lwip: Fix compilation issue for the microblaze based designs
No changes in lwip_echo_server and freertos_lwip_echo_server

2016.3

commit: Change BD space memory attributes for Zynq to avoid corner case TX issues
commit: Dont set SLCR clock dividers when clk src is EMIO because clock is derived from EMIO
commit: Fix compilation issues in emaclite adapter for freertos823 bsp
commit: Add support for freertos in lwIP emaclite adapter
lwip echo server application (and freertos lwip echo server app)
commit: Perform a PHY reset for ZCU102 board

Related Links

Baremetal Drivers and Libraries

Standalone Ethernet Driver

AXI Ethernet Standalone Driver