mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2025-03-17 10:21:07 +00:00
Improve documentation: Some words about multiple execution contexts in lwIP
This commit is contained in:
parent
65796cd827
commit
682b82aad8
@ -2071,6 +2071,7 @@ INCLUDE_FILE_PATTERNS = *.h
|
|||||||
PREDEFINED = __DOXYGEN__=1 \
|
PREDEFINED = __DOXYGEN__=1 \
|
||||||
NO_SYS=0 \
|
NO_SYS=0 \
|
||||||
SYS_LIGHTWEIGHT_PROT=1 \
|
SYS_LIGHTWEIGHT_PROT=1 \
|
||||||
|
LWIP_TCPIP_CORE_LOCKING=1 \
|
||||||
LWIP_IPV4=1 \
|
LWIP_IPV4=1 \
|
||||||
LWIP_IPV6=1 \
|
LWIP_IPV6=1 \
|
||||||
LWIP_ICMP=1 \
|
LWIP_ICMP=1 \
|
||||||
|
@ -1,4 +1,4 @@
|
|||||||
/**
|
/**
|
||||||
* @defgroup lwip lwIP
|
* @defgroup lwip lwIP
|
||||||
*
|
*
|
||||||
* @defgroup infrastructure Infrastructure
|
* @defgroup infrastructure Infrastructure
|
||||||
@ -7,7 +7,7 @@
|
|||||||
* Non thread-safe APIs, callback style for maximum performance and minimum
|
* Non thread-safe APIs, callback style for maximum performance and minimum
|
||||||
* memory footprint.
|
* memory footprint.
|
||||||
*
|
*
|
||||||
* @defgroup threadsafe_api Thread-safe APIs
|
* @defgroup sequential_api Sequential-style APIs
|
||||||
* Thread-safe APIs, blocking functions. More overhead, but can be called
|
* Thread-safe APIs, blocking functions. More overhead, but can be called
|
||||||
* from any thread except TCPIP thread.
|
* from any thread except TCPIP thread.
|
||||||
*
|
*
|
||||||
@ -31,6 +31,63 @@
|
|||||||
* @verbinclude "contrib.txt"
|
* @verbinclude "contrib.txt"
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @page pitfalls Common pitfalls
|
||||||
|
*
|
||||||
|
* Multiple Execution Contexts in lwIP code
|
||||||
|
* ========================================
|
||||||
|
*
|
||||||
|
* The most common source of lwIP problems is to have multiple execution contexts
|
||||||
|
* inside the lwIP code.
|
||||||
|
*
|
||||||
|
* lwIP can be used in two basic modes: @ref lwip_nosys (no OS/RTOS
|
||||||
|
* running on target system) or @ref lwip_os (there is an OS running
|
||||||
|
* on the target system).
|
||||||
|
*
|
||||||
|
* Mainloop Mode
|
||||||
|
* -------------
|
||||||
|
* In mainloop mode, only @ref callbackstyle_api can be used.
|
||||||
|
* The user has two possibilities to ensure there is only one
|
||||||
|
* exection context at a time in lwIP:
|
||||||
|
*
|
||||||
|
* 1) Deliver RX ethernet packets directly in interrupt context to lwIP
|
||||||
|
* by calling netif->input directly in interrupt. This implies all lwIP
|
||||||
|
* callback functions are called in IRQ context, which may cause further
|
||||||
|
* problems in application code: IRQ is blocked for a long time, multiple
|
||||||
|
* execution contexts in application code etc. When the application wants
|
||||||
|
* to call lwIP, it only needs to disable interrupts during the call.
|
||||||
|
* If timers are involved, even more locking code is needed to lock out
|
||||||
|
* timer IRQ and ethernet IRQ from each other, assuming these may be nested.
|
||||||
|
*
|
||||||
|
* 2) Run lwIP in a mainloop. There is example code here: @ref lwip_nosys.
|
||||||
|
* lwIP is _ONLY_ called from mainloop callstacks here. The ethernet IRQ
|
||||||
|
* has to put received telegrams into a queue which is polled in the
|
||||||
|
* mainloop. Ensure lwIP is _NEVER_ called from an interrupt, e.g.
|
||||||
|
* some SPI IRQ wants to forward data to udp_send() or tcp_write()!
|
||||||
|
*
|
||||||
|
* OS Mode
|
||||||
|
* -------
|
||||||
|
* In OS mode, @ref callbackstyle_api AND @ref sequential_api can be used.
|
||||||
|
* @ref sequential_api are designed to be called from threads other than
|
||||||
|
* the TCPIP thread, so there is nothing to consider here.
|
||||||
|
* But @ref callbackstyle_api functions must _ONLY_ be called from
|
||||||
|
* TCPIP thread. It is a common error to call these from other threads
|
||||||
|
* or from IRQ contexts. Ethernet RX needs to deliver incoming packets
|
||||||
|
* in the correct way by sending a message to TCPIP thread, this is
|
||||||
|
* implemented in tcpip_input().
|
||||||
|
* Again, ensure lwIP is _NEVER_ called from an interrupt, e.g.
|
||||||
|
* some SPI IRQ wants to forward data to udp_send() or tcp_write()!
|
||||||
|
*
|
||||||
|
* 1) tcpip_callback() can be used get called back from TCPIP thread,
|
||||||
|
* it is safe to call any @ref callbackstyle_api from there.
|
||||||
|
*
|
||||||
|
* 2) Use @ref LWIP_TCPIP_CORE_LOCKING. All @ref callbackstyle_api
|
||||||
|
* functions can be called when lwIP core lock is aquired, see
|
||||||
|
* @ref LOCK_TCPIP_CORE() and @ref UNLOCK_TCPIP_CORE().
|
||||||
|
* These macros cannot be used in an interrupt context!
|
||||||
|
* Note the OS must correctly handle priority inversion for this.
|
||||||
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @page bugs Reporting bugs
|
* @page bugs Reporting bugs
|
||||||
* Please report bugs in the lwIP bug tracker at savannah.\n
|
* Please report bugs in the lwIP bug tracker at savannah.\n
|
||||||
@ -60,7 +117,7 @@
|
|||||||
* to use @ref LWIP_TCPIP_CORE_LOCKING.\n
|
* to use @ref LWIP_TCPIP_CORE_LOCKING.\n
|
||||||
* Porting: implement all functions in @ref sys_layer.\n
|
* Porting: implement all functions in @ref sys_layer.\n
|
||||||
* You can use @ref callbackstyle_api together with @ref tcpip_callback,
|
* You can use @ref callbackstyle_api together with @ref tcpip_callback,
|
||||||
* and all @ref threadsafe_api.
|
* and all @ref sequential_api.
|
||||||
*/
|
*/
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
@ -3,7 +3,7 @@
|
|||||||
* Sequential API External module
|
* Sequential API External module
|
||||||
*
|
*
|
||||||
* @defgroup netconn Netconn API
|
* @defgroup netconn Netconn API
|
||||||
* @ingroup threadsafe_api
|
* @ingroup sequential_api
|
||||||
* Thread-safe, to be called from non-TCPIP threads only.
|
* Thread-safe, to be called from non-TCPIP threads only.
|
||||||
* TX/RX handling based on @ref netbuf (containing @ref pbuf)
|
* TX/RX handling based on @ref netbuf (containing @ref pbuf)
|
||||||
* to avoid copying data around.
|
* to avoid copying data around.
|
||||||
|
@ -3,7 +3,7 @@
|
|||||||
* Network Interface Sequential API module
|
* Network Interface Sequential API module
|
||||||
*
|
*
|
||||||
* @defgroup netifapi NETIF API
|
* @defgroup netifapi NETIF API
|
||||||
* @ingroup threadsafe_api
|
* @ingroup sequential_api
|
||||||
* Thread-safe functions to be called from non-TCPIP threads
|
* Thread-safe functions to be called from non-TCPIP threads
|
||||||
*
|
*
|
||||||
* @defgroup netifapi_netif NETIF related
|
* @defgroup netifapi_netif NETIF related
|
||||||
|
@ -3,7 +3,7 @@
|
|||||||
* Sockets BSD-Like API module
|
* Sockets BSD-Like API module
|
||||||
*
|
*
|
||||||
* @defgroup socket Socket API
|
* @defgroup socket Socket API
|
||||||
* @ingroup threadsafe_api
|
* @ingroup sequential_api
|
||||||
* BSD-style socket API.\n
|
* BSD-style socket API.\n
|
||||||
* Thread-safe, to be called from non-TCPIP threads only.\n
|
* Thread-safe, to be called from non-TCPIP threads only.\n
|
||||||
* Can be activated by defining @ref LWIP_SOCKET to 1.\n
|
* Can be activated by defining @ref LWIP_SOCKET to 1.\n
|
||||||
|
@ -52,7 +52,9 @@ extern "C" {
|
|||||||
#if LWIP_TCPIP_CORE_LOCKING
|
#if LWIP_TCPIP_CORE_LOCKING
|
||||||
/** The global semaphore to lock the stack. */
|
/** The global semaphore to lock the stack. */
|
||||||
extern sys_mutex_t lock_tcpip_core;
|
extern sys_mutex_t lock_tcpip_core;
|
||||||
|
/** Lock lwIP core mutex (needs @ref LWIP_TCPIP_CORE_LOCKING 1) */
|
||||||
#define LOCK_TCPIP_CORE() sys_mutex_lock(&lock_tcpip_core)
|
#define LOCK_TCPIP_CORE() sys_mutex_lock(&lock_tcpip_core)
|
||||||
|
/** Unlock lwIP core mutex (needs @ref LWIP_TCPIP_CORE_LOCKING 1) */
|
||||||
#define UNLOCK_TCPIP_CORE() sys_mutex_unlock(&lock_tcpip_core)
|
#define UNLOCK_TCPIP_CORE() sys_mutex_unlock(&lock_tcpip_core)
|
||||||
#else /* LWIP_TCPIP_CORE_LOCKING */
|
#else /* LWIP_TCPIP_CORE_LOCKING */
|
||||||
#define LOCK_TCPIP_CORE()
|
#define LOCK_TCPIP_CORE()
|
||||||
|
Loading…
x
Reference in New Issue
Block a user