Move API description text from rawapi.txt to doxygen docs

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
  * 

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

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
  */
 
 /*