Chapter 160. lwIP overview

160.1. Introduction

lwIP, short for lightweight IP, is an implementation of a standard Internet Protocol v4 and v6 networking protocol stack designed to operate in a resource-constrained environment. It was created in 2001 by Adam Dunkels of the Swedish Institute of Computer Science for his Master's thesis. The core lwIP code was released publically under an open licence.

The lwIP stack supports the IP, TCP, UDP, ICMP, IGMP, ARP, DHCP, AutoIP, DNS, SNMP, SLIP and PPP protocols, and there is a selection of APIs which applications can use to interact with it. As well as being designed from the outset to have a low memory footprint, it also gains many of its lightweight properties from being highly configurable. This makes it an excellent choice for integration into eCos.

This documentation describes lwIP and properties specific to its port to eCosPro. The usage, configuration and tuning of lwIP will also be discussed. Many of the concepts discussed here will require some understanding of the inherent underlying properties of the TCP, UDP and IP protocols. This documentation cannot substitute for an introduction to TCP/IP stacks and protocols generally, and it is recommended that where needed the reader seeks out a good reference book, such as:

  • TCP/IP Illustrated, Volume 1: The Protocols, W. Richard Stevens, published by Addison-Wesley Professional, ISBN-10: 0-201-63346-9, ISBN-13: 978-0-201-63346-7.
  • Internetworking with TCP/IP: volume 1, Douglas E. Comer, published by Prentice-Hall, ISBN-10: 0-131-87671-6, ISBN-13: 978-0-131-87671-2.

or one of the many online guides:

160.2. lwIP sources and ports

lwIP is portable and by no means specific to eCos. It has an active development community and undergoes continuous development of its core code, focussed around its project page on the Savannah development site run by the Free Software Foundation.

In order to provide a robust, feature-rich, and commercially supportable solution for eCosPro, the eCos support has been overhauled by eCosCentric® to work with the latest lwIP releases.

This documentation corresponds solely to the eCosPro port of lwIP, and the usage, configuration system and operation differs in many regards from that in other code bases.

[Warning]Warning

As detailed in Section 162.1, “Port status” the current eCosPro lwIP is using a much newer lwIP source base with substantial changes from previous eCosPro lwIP offerings. As such some CDL compatibility issues will arise if attempts are made to use old .ecc configuration files.

Either a fresh configuration can be created, and options re-selected as desired, or prior to switching to the newer source world, whilst still configured to use the older ECOS_REPOSITORY the eCos configtool can be used to export (File->Export) the configuration to a .ecm (minimal configuration) file. Then after switching to the new ECOS_REPOSITORY source tree the eCos configtool can be used to import (File->Import) the created .ecm file.

160.3. External documentation

A limited amount of publically available documentation is available for the lwIP project. Some of it has been incorporated into this manual. The following lists useful documentation known about at the time of writing:

  • Adam Dunkel's Master's Thesis - the original description of lwIP design and operation, but now somewhat outdated.
  • Report by Adam Dunkel into the design and implementation of lwIP, including a sequential API reference, and example code. Largely still applicable to current lwIP, albeit incomplete. A copy of the PDF version may be found in the doc/ subdirectory of the lwIP package in the eCosPro source repository (packages/net/lwip_tcpip/VERSION/doc/dunkels-lwip.pdf relative to the base of the eCosPro installation).
  • The lwIP Wiki site provides a good introduction to many lwIP features, and provides links to related documentation.
  • Text description of the lwIP raw API. A copy of the version at time of writing may be found in the doc/ subdirectory of the lwIP package in the eCosPro source repository (packages/net/lwip_tcpip/VERSION/doc/rawapi.txt relative to the base of the eCosPro installation).
  • Text description of the sys_arch porting abstraction layer. A copy of the version at time of writing may be found in the doc/ subdirectory of the lwIP package in the eCosPro source repository (packages/net/lwip_tcpip/VERSION/doc/sys_arch.txt relative to the base of the eCosPro installation).

160.4. Licensing

The lwIP core code is distributed under a 3 clause BSD-style license. Confirmation has been received from Adam Dunkels that the existing public lwIP documentation is also covered by this license.

The original public eCos port included elements distributed under the eCos license.

As a result of the changes made by eCosCentric, portions of the eCos port of lwIP in eCosPro are covered by the eCosPro License.