diff --git a/doc/doxygen/main_page.h b/doc/doxygen/main_page.h index 9094330a..b9f4d92e 100644 --- a/doc/doxygen/main_page.h +++ b/doc/doxygen/main_page.h @@ -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 * diff --git a/doc/rawapi.txt b/doc/rawapi.txt index 2c003172..04704765 100644 --- a/doc/rawapi.txt +++ b/doc/rawapi.txt @@ -2,103 +2,6 @@ Raw TCP/IP interface for lwIP Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons -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 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. - -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). - -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. - -** 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). - - -** The remainder of this document discusses the "raw" API. ** - -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. - --- System initalization A truly complete and generic sequence for initializing the lwIP stack diff --git a/src/api/sockets.c b/src/api/sockets.c index 535ae073..fbf4a925 100644 --- a/src/api/sockets.c +++ b/src/api/sockets.c @@ -1,13 +1,6 @@ /** * @file * Sockets BSD-Like API module - * - * @defgroup socket Socket API - * @ingroup sequential_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\b */ /*