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
  *