Added a word or two on threading, which should be sufficient to close task #6683

doc/FILES

@@ -1,5 +1,6 @@
 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.

doc/rawapi.txt

@@ -2,10 +2,11 @@ Raw TCP/IP interface for 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
@@ -14,6 +15,36 @@ paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
 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