Work on lwIP documentation

src/api/tcpip.c

@@ -190,8 +190,10 @@ tcpip_inpkt(struct pbuf *p, struct netif *inp, netif_input_fn input_fn)
 }
 
 /**
+ * @ingroup lwip_os
  * Pass a received packet to tcpip_thread for input processing with
- * ethernet_input or ip_input
+ * ethernet_input or ip_input. Don't call directly, pass to netif_add()
+ * and call netif->input().
  *
  * @param p the received packet, p->payload pointing to the Ethernet header or
  *          to an IP header (if inp doesn't have NETIF_FLAG_ETHARP or
@@ -441,7 +443,7 @@ tcpip_trycallback(struct tcpip_callback_msg* msg)
 }
 
 /**
- * @ingroup lwip
+ * @ingroup lwip_os
  * Initialize this module:
  * - initialize all sub modules
  * - start the tcpip_thread

src/core/dns.c

@@ -62,7 +62,7 @@
  * 
  * All functions must be called from TCPIP thread.
  * 
- * @see @ref netconn_dns
+ * @see @ref netconn_common for thread-safe access.
  */
 
 /*-----------------------------------------------------------------------------

src/core/init.c

@@ -37,7 +37,22 @@
 
 /**
  * @defgroup lwip lwIP
- * @ingroup infrastructure
+ *
+ * @defgroup lwip_nosys NO_SYS ("mainloop") mode
+ * @ingroup lwip
+ * Use this mode if you do not run an OS on your system. \#define NO_SYS to 1.
+ * Feed incoming packets to netif->input(pbuf, netif) function from mainloop,
+ * *not* *from* *interrupt* *context*. You can allocate a @ref pbuf in interrupt
+ * context and put it in a queue which is processed from mainloop.\n
+ * Call sys_check_timeouts() periodically in the mainloop.\n
+ * Porting: implement all functions in @ref sys_time and @ref sys_prot.
+ *
+ * @defgroup lwip_os OS mode (TCPIP thread)
+ * @ingroup lwip
+ * Use this mode if you run an OS on your system. It is recommended to
+ * use an RTOS that correctly handles priority inversion and
+ * to use LWIP_TCPIP_CORE_LOCKING.\n
+ * Porting: implement all functions in @ref sys_layer.
  */
 
 #include "lwip/opt.h"
@@ -322,7 +337,7 @@
 #endif /* !LWIP_DISABLE_TCP_SANITY_CHECKS */
 
 /**
- * @ingroup lwip
+ * @ingroup lwip_nosys
  * Initialize all modules.
  * Use this in NO_SYS mode. Use tcpip_init() otherwise.
  */

src/core/ip.c

@@ -102,7 +102,11 @@ ipaddr_aton(const char *cp, ip_addr_t *addr)
   return 0;
 }
 
-/* If both IP versions are enabled, this function can dispatch packets to the correct one. */
+/**
+ * @ingroup lwip_nosys
+ * If both IP versions are enabled, this function can dispatch packets to the correct one.
+ * Don't call directly, pass to netif_add() and call netif->input().
+ */
 err_t
 ip_input(struct pbuf *p, struct netif *inp)
 {

src/core/timeouts.c

@@ -293,7 +293,7 @@ sys_untimeout(sys_timeout_handler handler, void *arg)
 }
 
 /**
- * @ingroup lwip
+ * @ingroup lwip_nosys
  * Handle timeouts for NO_SYS==1 (i.e. without using
  * tcpip_thread/sys_timeouts_mbox_fetch(). Uses sys_now() to call timeout
  * handler functions when timeouts expire.

src/include/lwip/sys.h

@@ -41,12 +41,15 @@
  *
  * @defgroup sys_os OS abstraction layer
  * @ingroup sys_layer
+ * No need to implement functions in this section in NO_SYS mode.
  *
  * @defgroup sys_sem Semaphores
  * @ingroup sys_os
  *
  * @defgroup sys_mutex Mutexes
  * @ingroup sys_os
+ * Mutexes are recommended to correctly handle priority inversion,
+ * especially if you use LWIP_CORE_LOCKING .
  *
  * @defgroup sys_mbox Mailboxes
  * @ingroup sys_os
@@ -56,6 +59,14 @@
  *
  * @defgroup sys_prot Critical sections
  * @ingroup sys_layer
+ * Used to protect short regions of code against concurrent access.
+ * - Your system is a bare-metal system (probably with an RTOS) 
+ *   and interrupts are under your control:
+ *   Implement this as LockInterrupts() / UnlockInterrupts()
+ * - Your system uses an RTOS with deferred interrupt handling from a 
+ *   worker thread: Implement as a global mutex or lock/unlock scheduler
+ * - Your system uses a high-level OS with e.g. POSIX signals:
+ *   Implement as a global mutex
  *
  * @defgroup sys_thread Threads
  * @ingroup sys_os
@@ -250,7 +261,7 @@ void sys_sem_set_invalid(sys_sem_t *sem);
 
 #ifndef sys_msleep
 /**
- * @ingroup sys_time
+ * @ingroup sys_os
  * Sleep for specified number of ms
  */
 void sys_msleep(u32_t ms); /* only has a (close to) 1 ms resolution. */

src/include/lwip/tcpip.h

@@ -77,7 +77,7 @@ err_t  tcpip_input(struct pbuf *p, struct netif *inp);
 
 err_t  tcpip_callback_with_block(tcpip_callback_fn function, void *ctx, u8_t block);
 /** 
- * @ingroup lwip
+ * @ingroup lwip_os
  * @see tcpip_callback_with_block
  */
 #define tcpip_callback(f, ctx)  tcpip_callback_with_block(f, ctx, 1)

src/netif/ethernet.c

@@ -57,9 +57,11 @@ const struct eth_addr ethbroadcast = {{0xff,0xff,0xff,0xff,0xff,0xff}};
 const struct eth_addr ethzero = {{0,0,0,0,0,0}};
 
 /**
+ * @ingroup lwip_nosys
  * Process received ethernet frames. Using this function instead of directly
  * calling ip_input and passing ARP frames through etharp in ethernetif_input,
- * the ARP cache is protected from concurrent access.
+ * the ARP cache is protected from concurrent access.\n
+ * Don't call directly, pass to netif_add() and call netif->input().
  *
  * @param p the received packet, p->payload pointing to the ethernet header
  * @param netif the network interface on which the packet was received