There has been a few questions about how lwIP can be used in a standalone environment (i.e., an environment without a multi-threaded operating system) lately. The purpose of this document is to describe how lwIP is designed to be used with and without a multi-threaded operating system.

The lwIP single-threaded core Edit

The core of lwIP consists of the actual implementations of the IP, ICMP, UDP, and TCP protocols, as well as support functions such as buffer and memory management. The core components are the only ones that are needed when lwIP is to be run in a single-threaded (non-OS) environment.

The core components can be viewed as a software library which has the following interface:

• ip_input(pbuf, netif): Takes an IP packet and the incoming network interface as arguments and does the TCP/IP processing for the packet.
• tcp_tmr(): Should be called every 250 ms (=TCP_TMR_INTERVAL). Does all TCP timer processing such as doing retransmissions.

Because none of the core functions ever needs to block when run in a single-threaded environment, a sys_arch (operating system abstraction layer) implementation is not needed (and semaphore and mailbox functions are stub definitions only).

A simple main loop for a single-threaded system might look like this:

while(1) {  
   if(poll_driver(netif) == PACKET_READY) {  
     pbuf = get_packet(netif);  
     ip_input(pbuf, netif);  
   }  
   if (clock() - last_arp_time >= ARP_TMR_INTERVAL * CLOCKTICKS_PER_MS)  
   {  
       etharp_tmr();  
       last_arp_time = clock();  
   }  
   if(clock() - last_time >= TCP_TMR_INTERVAL * CLOCKTICKS_PER_MS) {  
     tcp_tmr();  
     last_time = clock();  
   }      
 }

ATTENTION: Note that CLOCKTICKS_PER_MS is only valid for a hardware timer with at least one tick per millisecond. If you want to use an OS-tick-counter (e.g. one that is incremented every 10ms), you have to adjust the code to:

clock() - last_time >= TCP_TMR_INTERVAL / MS_PER_TICK

In case you use more than just TCP/IP and ARP, you might need to add more calls to timers. In a multi-threaded system all these timers are called from api/tcpip.c, so this source file is a good place to check if you need to call any more timers (like IP_REASSEMBLY, DHCP, etc.). Hint: Both in api/tcpip.c and the examples above, the timers do not "catch up". That means if one timer tick is delayed (for whatever reason), all following timer ticks will be delayed, too.

An implementation with the above main loop can already be pinged, but you will probably also want to process tcp connections. You can open, close, read, write (to) tcp connections using the LwIP raw API. Continue reading at Raw/native API and doc/rawapi.txt.

An working example for a main loop for a single-threaded system can be found in contrib/ports/unix/proj/minimal/.

lwIP in a multi-threaded system Edit

lwIP is designed to be able to be run in a multi-threaded system with applications running in concurrent threads. The model used in this case is that all TCP/IP processing is done in a single thread. The application thread communicates with the TCP/IP thread using the sequential API.

The inter-thread communication is implemented in the two files api_lib.c and api_msg.c. The former contains the functions used by the application programs and the latter implements the TCP/IP stack interface. A third file, tcpip.c, handles incoming packets and timer events as described in the previous section.

When run in a multi-threaded environment, incoming packets are handled by the function tcpip_input() (or alternatively tcpip_ethinput()), which takes the same arguments as the ip_input() function. The difference between the two functions is that the tcpip_input() function does not process the incoming packet immediately. It merely puts the packet on a queue which later is drained by the TCP/IP thread.

When being run in a multi-threaded system, timer events are taken care of internally in tcpip.c.