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

Update documentation

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
+ * If @ref SYS_LIGHTWEIGHT_PROT is set to 1 and
- * LWIP_ALLOW_MEM_FREE_FROM_OTHER_CONTEXT is set to 1,
+ * @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. 
  */
 
 /**

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 @ref 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 = 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()