mirror/lwip
1
0
Fork 0
mirror of https://github.com/lwip-tcpip/lwip.git synced 2024-12-24 15:14:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Work on task #14780: Add debug helper asserts to ensure threading/locking requirements are met

Browse Source 
Update documentation
This commit is contained in:
Dirk Ziegelmeier 2018-01-02 21:45:30 +01:00
parent d569a22c73
commit 004b13ca09
2 changed files with 31 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/doxygen/main_page.h
View File

@ -121,6 +121,8 @@
* 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).
*
* See also: @ref multithreading
*
* Mainloop Mode
* -------------
@ -309,7 +311,7 @@ Call these functions in the order of appearance:
*
* 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
* since they are protected by @ref SYS_LIGHTWEIGHT_PROT and/or
* semaphores.
*
* Netconn or Socket API functions are thread safe against the
@ -317,12 +319,32 @@ Call these functions in the order of appearance:
* 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,
* If @ref SYS_LIGHTWEIGHT_PROT is set to 1 and
* @ref 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).
*
* How to get threading done right
* -------------------------------
*
* It is strongly recommended to implement the LWIP_ASSERT_CORE_LOCKED()
* macro in an application that uses multithreading. lwIP code has
* several places where a check for a correct thread context is
* implemented which greatly helps the user to get threading done right.
* See the example sys_arch.c files in unix and Win32 port
* in the contrib repository.
*
* In short: Copy the functions sys_mark_tcpip_thread() and
* sys_check_core_locking() to your port and modify them to work with your OS.
* Then let @ref LWIP_ASSERT_CORE_LOCKED() and @ref LWIP_MARK_TCPIP_THREAD()
* point to these functions.
*
* If you use @ref LWIP_TCPIP_CORE_LOCKING, you also need to copy and adapt
* the functions sys_lock_tcpip_core() and sys_unlock_tcpip_core().
* Let @ref LOCK_TCPIP_CORE() and @ref UNLOCK_TCPIP_CORE() point
* to these functions.
*/
/**

10
src/include/lwip/opt.h
View File

@ -214,13 +214,14 @@
#endif
/**
* LWIP_ASSERT_CORE_LOCKED: Macro to check whether lwIP's threading/locking
* Macro/function to check whether lwIP's threading/locking
* requirements are satisfied during current function call.
* This macro usually calls a function that is implemented in the OS-dependent
* sys layer and performs the following checks:
* - Not in ISR
* - If LWIP_TCPIP_CORE_LOCKING=1: TCPIP core lock is held
* - If LWIP_TCPIP_CORE_LOCKING=0: function is called from TCPIP thread
* - If @ref LWIP_TCPIP_CORE_LOCKING = 1: TCPIP core lock is held
* - If @ref LWIP_TCPIP_CORE_LOCKING = 0: function is called from TCPIP thread
* @see @ref multithreading
*/
#if !defined LWIP_ASSERT_CORE_LOCKED || defined __DOXYGEN__
#define LWIP_ASSERT_CORE_LOCKED()
@ -228,7 +229,8 @@
/**
* Called as first thing in the lwIP TCPIP thread. Can be used in conjunction
* with LWIP_ASSERT_CORE_LOCKED to check core locking.
* with @ref LWIP_ASSERT_CORE_LOCKED to check core locking.
* @see @ref multithreading
*/
#if !defined LWIP_MARK_TCPIP_THREAD || defined __DOXYGEN__
#define LWIP_MARK_TCPIP_THREAD()