mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2024-12-25 00:14:02 +00:00
Move API description text from rawapi.txt to doxygen docs
This commit is contained in:
Dirk Ziegelmeier
parent
a8edee8268
commit
33ce04019d
@ -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
|
||||
*
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
*/
|
||||
|
||||
/*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user