savannah.txt - How to obtain the current development source code.
contrib.txt - How to contribute to lwIP as a developer.
rawapi.txt - The documentation for the core API of lwIP.
+ Also provides an overview about the other APIs and multithreading.
snmp_agent.txt - The documentation for the lwIP SNMP agent.
sys_arch.txt - The documentation for a system abstraction layer of lwIP.
Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
-lwIP provides two Application Program's Interfaces (APIs) for programs
+lwIP provides three Application Program's Interfaces (APIs) for programs
to use for communication with the TCP/IP code:
* low-level "core" / "callback" or "raw" API.
* higher-level "sequential" API.
+* BSD-style socket API.
The sequential API provides a way for ordinary, sequential, programs
to use the lwIP stack. It is quite similar to the BSD socket API. The
code and the application program must reside in different execution
contexts (threads).
+The socket API is a compatibility API for existing applications,
+currently it is built on top of the sequential API. It is meant to
+provide all functions needed to run socket API applications running
+on other platforms (e.g. unix / windows etc.). However, due to limitations
+in the specification of this API, there might be incompatibilities
+that require small modifications of existing programs.
+
+** Threading
+
+lwIP started targeting single-threaded environments. When adding multi-
+threading support, instead of making the core thread-safe, another
+approach was chosen: there is one main thread running the lwIP core
+(also known as the "tcpip_thread"). The raw API may only be used from
+this thread! Application threads using the sequential- or socket API
+communicate with this main thread through message passing.
+
+ As such, the list of functions that may be called from
+ other threads or an ISR is very limited! Only functions
+ from these API header files are thread-safe:
+ - api.h
+ - sockets.h
+ - netifapi.h
+ - sys.h
+
+ Only since 1.3.0, if SYS_LIGHTWEIGHT_PROT is set to 1
+ and LWIP_ALLOW_MEM_FREE_FROM_OTHER_CONTEXT is set to 1,
+ pbuf_free() may also be called from another thread or
+ an ISR!
+
+
** The remainder of this document discusses the "raw" API. **
The raw TCP/IP interface allows the application program to integrate