none none none

RTLinux Lightweight TCP/IP Stack

Project Description


Using RTL-lwIP




Mailing List

The RTL-lwIP Logo

Projects using RTL-lwIP


Development Page
The development page at: Logo
Project Description

What is RTL-lwIP?

RTL-lwIP is the porting of the lwIP TCP/IP stack to RTLinux-GPL. RTL-lwIP gives to RT-Tasks the chance of communicating via TCP/IP directly with other RT-Tasks or even with Linux user processes.

The focus of the RTL-lwIP stack is to reduce memory usage and code size, making RTL-lwIP suitable for use in small clients with very limited resources such as embedded systems. In order to reduce processing and memory demands, RTL-lwIP uses a tailor made API that does not require any data copying.

RTL-lwIP includes IP, ICMP, UDP and TCP protocols. It provides to RT-Tasks a socket-like API to communicate over a network. In this software package you'll find:


  • The TCP/IP stack (IPV4, IPV6, ICMP, UDP, TCP)

  • Asynchronous DNS resolver

  • Programming examples

  • Support for the REDD (RTLinux Ethernet Device Drivers) drivers (3c59x, 8139too and e100).

What is NOT RTL-lwIP?

RTL-lwIP is NOT a real time communication protocol since ethernet (802.3) and TCP/IP are not real time communication protocols. RTL-lwIP just gives communication via TCP/IP and all what it implies.

NOTE: RTL-lwIP is intended to work in real time embedded systems, so memory limitations are taken into account. Hugh burst of incoming packets may exhaust the memory. That's normal, big routers have lots of RAM, small embedded systems have not. RTL-lwIP responds to this situation stoping all its services. If stoped, there's no way to restart it. All modules must be removed and inserted again.

Requirements [top]

In order to correctly compile and run RTL-lwIP you need:

  • RTLinux Ethernet Drivers: some Ethernet drivers for RTLinux were included in RTL-lwIP up to version 0.4. From version 0.5 on, Ethernet drivers are supported and mantained in another project: REDD (RTLinux Ethernet Device Drivers). Visit REDD to download and compile the drivers you need.

  • POSIX Signals: provides signals implementation for RT-Linux. POSIX signals are included in the RTLinux-3.2 distribution. You must check that option when compiling RTLinux-3.2. If you're using an older distribution such as 3.1, you can download the POSIX signals patch from here.

  • POSIX Timers: allows a mechanism that can notify a thread when the time as measured by a particular clock has reached expired. POSIX timers are included in the RTLinux-3.2 distribution and depend on POSIX signals. You must check that option when compiling RTLinux-3.2. If you're using older distributions such as the 3.1 then you can download de POSIX timers patch from here.

Using RTL-lwIP [top]

RTL-lwIP consists of several files which are compiled and linked into one module: rtl_lwip_stack.o.

Users may want to change or to select some parameters such as the network card, buffer sizes, the Ethernet cards' IP addresses, and others ... all of them are gathered together into a header file (rtl_lwipopts.h), so take a look at it and tune it. Also the path to the file must be properly set in the Makefile. Once this has been done, just compile (it's as simple as typing make). After compiling you can read the INSTALL file to see how to install the RTL-lwIP module.

Once inserted, the stack offers a sockets-like API to the RT-Tasks that can be used to send and receive packets over a network. The sockets API is build over the "sequential API" (which is quite similar to the BSD socket API). The sequential API is a high performance API because it is designed to take advantage of the specific internal design of the stack. RTL-lwIP also offers another API called raw API which is not only faster in terms of code execution time but is also less memory intensive. See the Documentation section to get reference manuals of these APIs.

Note: all communication APIs are inherited from lwIP, so more documentation can be found in its home page ( go there).

"So, the tools, the driver(s), and the stack are inserted... what do I do now?".

You may want to write a real time application using RTL-lwIP, so you have to use the communications APIs described above and (at least once) the OSEL API (Operating System Emulation Layer). The OSEL API gives access to operating system specific calls and data structures (thread managing, semaphores, interrupts, etc...) and must be used at least for creating communication threads, or to register a thread (not created by means of the OSEL API) as a communication thread (this is for the TCIP/IP stack internal management). In the Documentation section there's a document describing the OSEL API and how applications should use it.

In order to correctly access header files you should use the Makefile included with the distribution (just adding an entry for your application/s). If you don't wanto to use the Makefile, you can include in your own Makefile the file, which gives the macro definitions needed to use RTL-lwIP. That's it. Take a look at the examples directory, it will be quite instructive.

Documentation [top]
RTL-lwIP source navigation
Navigate on the RTL-lwIP 0.4 sources as a LXR
728 kb
OSEL-0.2.1 API
Description of the Operating System Emulation Layer API (Used in RTL-lwIP 0.2.1, 0.3, 0.4 and 0.5)
231 kb
Description of the Operating System Emulation Layer API (Used in RTL-lwIP 0.2)
230 kb
Description of the Operating System Emulation Layer API (Used in RTL-lwIP 0.1)

99.1 kb

lwIP API and sockets API
Description of the communications API (author: Adam Dunkels)
283 kb
Description of the raw API (author: Adam Dunkels)
11.9 kb
Download Section [top]

The CVS access has been disabled. From now on, RTL-lwIP new relases will be provided in a tarball file.

RTL-lwIP none
644 kb (Tar)
644 kb (Tar)
673 kb (Tar)
456 kb (Tar)
429 kb (Tar)
440 kb (Tar)
237 kb (Tar)
The RTL-lwIP logo [top]

The history of this logo is quite simple. I was just looking for images related with TCP/IP in google and one of them attracted my attention, this one (taken from here):


It was funny for me because my machine is called "carranc", which means crab in valencian (language that I speak) and that's why I choosed the crab as part of the RTL-lwIP logo. I tried to achieve a sand effect for the text.... Did I achieve it??


Once the logo was created I realized that the Realtek's logo (brand of one of the Ethernet cards supported by RTL-lwIP) is also a crab!! (logo taken from Realtek's home page) The fate, maybe?? ;)


Projects Using RTL-lwIP [top]

This section tries to join links to projects where RTL-lwIP is used and links to webs referencing RTL-lwIP.

ELX Real-Time OS 2.0
New RTOS that uses RTL-lwIP to access the network. In this page some performance data is provided.

Study of the different possibilities to access the network from within RTLinux by Pierre Morel
In this web page, Pierre Morel studies different projects that allow RTLinux to access the network. At the end of the study, the author gives his opinion about which projects could be better in which context. There's no a comparative study (performance, delays, ...), so it looks just what he says: his opinion.

OpenTech- RTLinux Support in Europe
Company giving support to RTLinux in Europe. They link RTL-lwIP as a RTLinux GPL community project.

If you are using RTL-lwIP in any project and you want your project's home page to be listed here, please send me a mail with a link to your project's home page.

Frequently Asked Questions [top]

- How many sockets can i open simultaneously? In my program if i open 5 sockets( 1 listen socket and 4 accepeted sockets) simultaneously, the time that 4th accepet() call ( for 4th accepet socket) takes is too long.

The file rtl_lwipopts.h contains most of the parameters that can be changed in RTL-lwIP, and most of them related to the number of connections that can be opened simultaneously. Check them and tune them for your system.

This problem may happen with distributions previous to RTL-lwIP-0.4

- I had an under error messages when I install rtl_lwip_tools.o. I successfully compiled rtl_lwip with rtlinux-3.0 and linux-2.4.4. and I also installed required packages. It's same result when I tried with linux-2.4.18 kernel.

# ./instools
rtl_lwip_tools.o: init_module: Operation not permitted
Hint: insmod errors can be caused by incorrect module parameters, including invalid IO or IRQ parameters

The problem is due to the macro CONFIG_BIGPHYSAREA definition of DIDMA.h. Some versions of the patch doesn't use the same macro and DIDMA doesn't take it into account. Try to change CONFIG_BIGPHYSAREA to CONFIG_BIGPHYS_AREA along to your .config Linux file and then compile RTL-lwIP again.

Last updated: 2004/11/29 11:53 $ (GMT+1)


[29/11/04] RTL-lwIP 0.6 released!!
Download it here (read the changelog).

Archived news.

The REDD project
RT-Portal UPV

Interoperable Web Page

Valid HTML 4.01!

Valid CSS!

The development of this web page and the work it contains has been supported under the Spanish grant TIC2002-04123-C03-03: Reliable Distributed Embedded Real-Time Systems based on Components (TRECOM).

Webmaster and project maintainer: Sergio Pérez Alcañiz (serpeal_AT_upvnet_DOT_upv_DOT_es)