Work on lwIP documentation

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.