From 004b13ca09d8d8d8f43d4a1e8a39bf638b983a54 Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Tue, 2 Jan 2018 21:45:30 +0100 Subject: [PATCH] Work on task #14780: Add debug helper asserts to ensure threading/locking requirements are met Update documentation --- doc/doxygen/main_page.h | 28 +++++++++++++++++++++++++--- src/include/lwip/opt.h | 10 ++++++---- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/doc/doxygen/main_page.h b/doc/doxygen/main_page.h index c7877ee4..400c96ae 100644 --- a/doc/doxygen/main_page.h +++ b/doc/doxygen/main_page.h @@ -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. */ /** diff --git a/src/include/lwip/opt.h b/src/include/lwip/opt.h index be5fa983..d7b2339e 100644 --- a/src/include/lwip/opt.h +++ b/src/include/lwip/opt.h @@ -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()