|
|
|
|
@ -2,8 +2,84 @@
|
|
|
|
|
* @defgroup lwip lwIP |
|
|
|
|
* |
|
|
|
|
* @defgroup infrastructure Infrastructure |
|
|
|
|
*
|
|
|
|
|
* @defgroup api APIs |
|
|
|
|
* lwIP provides three Application Program's Interfaces (APIs) for programs |
|
|
|
|
* to use for communication with the TCP/IP code: |
|
|
|
|
* - low-level "core" / "callback" or @ref callbackstyle_api. |
|
|
|
|
* - higher-level @ref sequential_api. |
|
|
|
|
* - BSD-style @ref socket. |
|
|
|
|
*
|
|
|
|
|
* The raw TCP/IP interface allows the application program to integrate |
|
|
|
|
* better with the TCP/IP code. Program execution is event based by |
|
|
|
|
* having callback functions being called from within the TCP/IP |
|
|
|
|
* code. The TCP/IP code and the application program both run in the same |
|
|
|
|
* thread. The sequential API has a much higher overhead and is not very |
|
|
|
|
* well suited for small systems since it forces a multithreaded paradigm |
|
|
|
|
* on the application. |
|
|
|
|
*
|
|
|
|
|
* The raw TCP/IP interface is not only faster in terms of code execution |
|
|
|
|
* time but is also less memory intensive. The drawback is that program |
|
|
|
|
* development is somewhat harder and application programs written for |
|
|
|
|
* the raw TCP/IP interface are more difficult to understand. Still, this |
|
|
|
|
* is the preferred way of writing applications that should be small in |
|
|
|
|
* code size and memory usage. |
|
|
|
|
*
|
|
|
|
|
* All APIs can be used simultaneously by different application |
|
|
|
|
* programs. In fact, the sequential API is implemented as an application |
|
|
|
|
* program using the raw TCP/IP interface. |
|
|
|
|
*
|
|
|
|
|
* Do not confuse the lwIP raw API with raw Ethernet or IP sockets. |
|
|
|
|
* The former is a way of interfacing the lwIP network stack (including |
|
|
|
|
* TCP and UDP), the latter refers to processing raw Ethernet or IP data |
|
|
|
|
* instead of TCP connections or UDP packets. |
|
|
|
|
*
|
|
|
|
|
* Raw API applications may never block since all packet processing |
|
|
|
|
* (input and output) as well as timer processing (TCP mainly) is done |
|
|
|
|
* in a single execution context. |
|
|
|
|
*
|
|
|
|
|
* Multithreading |
|
|
|
|
* -------------- |
|
|
|
|
* 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"). When running in a multithreaded |
|
|
|
|
* environment, raw API functions MUST only be called from the core thread |
|
|
|
|
* since raw API functions are not protected from concurrent access (aside |
|
|
|
|
* from pbuf- and memory management functions). 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 |
|
|
|
|
* - netbuf.h |
|
|
|
|
* - netdb.h |
|
|
|
|
* - netifapi.h |
|
|
|
|
* - pppapi.h |
|
|
|
|
* - sockets.h |
|
|
|
|
* - sys.h |
|
|
|
|
*
|
|
|
|
|
* Additionaly, memory (de-)allocation functions may be |
|
|
|
|
* called from multiple threads (not ISR!) with NO_SYS=0 |
|
|
|
|
* since they are protected by SYS_LIGHTWEIGHT_PROT and/or |
|
|
|
|
* semaphores. |
|
|
|
|
*
|
|
|
|
|
* Netconn or Socket API functions are thread safe against the |
|
|
|
|
* core thread but they are not reentrant at the control block |
|
|
|
|
* granularity level. That is, a UDP or TCP control block must |
|
|
|
|
* not be shared among multiple threads without proper locking. |
|
|
|
|
*
|
|
|
|
|
* 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 (since only then, mem_free - for PBUF_RAM - may |
|
|
|
|
* be called from an ISR: otherwise, the HEAP is only |
|
|
|
|
* protected by semaphores). |
|
|
|
|
* |
|
|
|
|
* @defgroup callbackstyle_api Callback-style APIs |
|
|
|
|
* @defgroup callbackstyle_api "raw" APIs |
|
|
|
|
* @ingroup api |
|
|
|
|
* Non thread-safe APIs, callback style for maximum performance and minimum |
|
|
|
|
* memory footprint. |
|
|
|
|
* Program execution is driven by callbacks functions, which are then |
|
|
|
|
@ -18,10 +94,35 @@
|
|
|
|
|
* argument. Also, in order to be able to keep program specific state, |
|
|
|
|
* the callback functions are called with a program specified argument |
|
|
|
|
* that is independent of the TCP/IP state. |
|
|
|
|
* The raw API (sometimes called native API) is an event-driven API designed |
|
|
|
|
* to be used without an operating system that implements zero-copy send and |
|
|
|
|
* receive. This API is also used by the core stack for interaction between |
|
|
|
|
* the various protocols. It is the only API available when running lwIP |
|
|
|
|
* without an operating system. |
|
|
|
|
*
|
|
|
|
|
* @defgroup sequential_api Sequential-style APIs |
|
|
|
|
* @ingroup api |
|
|
|
|
* Sequential-style APIs, blocking functions. More overhead, but can be called |
|
|
|
|
* from any thread except TCPIP thread. |
|
|
|
|
* 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 |
|
|
|
|
* model of execution is based on the blocking open-read-write-close |
|
|
|
|
* 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). |
|
|
|
|
*
|
|
|
|
|
* @defgroup socket Socket API |
|
|
|
|
* @ingroup api |
|
|
|
|
* BSD-style socket API.\n |
|
|
|
|
* Thread-safe, to be called from non-TCPIP threads only.\n |
|
|
|
|
* Can be activated by defining @ref LWIP_SOCKET to 1.\n |
|
|
|
|
* Header is in posix/sys/socket.h\n |
|
|
|
|
* 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. |
|
|
|
|
*
|
|
|
|
|
* @defgroup netifs NETIFs |
|
|
|
|
*
|
|
|
|
|
|
Dirk Ziegelmeier
9 years ago