From 8d07629b71df3e49bc49773d893c749e00a898a9 Mon Sep 17 00:00:00 2001 From: Dirk Ziegelmeier Date: Sun, 7 Aug 2016 10:05:34 +0200 Subject: [PATCH] Some documentation cleanups and include more comments that have been already in code into doxygen docs --- doc/doxygen/main_page.h | 31 ++++++++++++++++++++++ src/api/api_lib.c | 38 +++++++++++++-------------- src/api/netbuf.c | 15 +++++------ src/api/netdb.c | 8 ++---- src/api/netifapi.c | 17 +++++------- src/api/sockets.c | 15 +++++------ src/core/def.c | 23 ++++++++--------- src/core/inet_chksum.c | 22 ++++++++-------- src/core/init.c | 23 ----------------- src/core/ip.c | 39 +++++++++++++--------------- src/core/ipv4/autoip.c | 57 ++++++++++++++++------------------------- src/core/ipv4/dhcp.c | 52 +++++++++++++++---------------------- src/core/ipv4/igmp.c | 9 +++---- src/core/ipv6/mld6.c | 15 +++++------ src/core/memp.c | 11 ++++---- src/core/netif.c | 8 +++--- src/core/raw.c | 22 +++++----------- src/core/tcp.c | 20 +++++++-------- src/core/udp.c | 19 +++++--------- 19 files changed, 190 insertions(+), 254 deletions(-) diff --git a/doc/doxygen/main_page.h b/doc/doxygen/main_page.h index 9f01d9f3..86f96b73 100644 --- a/doc/doxygen/main_page.h +++ b/doc/doxygen/main_page.h @@ -30,3 +30,34 @@ * @page contrib How to contribute to lwIP * @verbinclude "contrib.txt" */ + +/** + * @defgroup lwip_nosys Mainloop mode ("NO_SYS") + * @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 them into 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.\n + * You can only use @ref callbackstyle_api in this mode.\n + * Sample code:\n + * @verbinclude NO_SYS_SampleCode.c + */ + +/** + * @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 @ref LWIP_TCPIP_CORE_LOCKING.\n + * Porting: implement all functions in @ref sys_layer.\n + * You can use @ref callbackstyle_api together with \#define tcpip_callback, + * and all @ref threadsafe_api. + */ + +/** + * @defgroup raw_api RAW API + * @ingroup callbackstyle_api + * @verbinclude "rawapi.txt" + */ diff --git a/src/api/api_lib.c b/src/api/api_lib.c index 5e696d88..740fe396 100644 --- a/src/api/api_lib.c +++ b/src/api/api_lib.c @@ -1,6 +1,24 @@ /** * @file * Sequential API External module + * + * @defgroup netconn Netconn API + * @ingroup threadsafe_api + * Thread-safe, to be called from non-TCPIP threads only. + * TX/RX handling based on @ref netbuf (containing @ref pbuf) + * to avoid copying data around. + * + * @defgroup netconn_common Common functions + * @ingroup netconn + * For use with TCP and UDP + * + * @defgroup netconn_tcp TCP only + * @ingroup netconn + * TCP only functions + * + * @defgroup netconn_udp UDP only + * @ingroup netconn + * UDP only functions */ /* @@ -34,26 +52,6 @@ * Author: Adam Dunkels */ -/** - * @defgroup netconn Netconn API - * @ingroup threadsafe_api - * Thread-safe, to be called from non-TCPIP threads only. - * TX/RX handling based on @ref netbuf (containing @ref pbuf) - * to avoid copying data around. - * - * @defgroup netconn_common Common functions - * @ingroup netconn - * For use with TCP and UDP - * - * @defgroup netconn_tcp TCP only - * @ingroup netconn - * TCP only functions - * - * @defgroup netconn_udp UDP only - * @ingroup netconn - * UDP only functions - */ - /* This is the part of the API that is linked with the application */ diff --git a/src/api/netbuf.c b/src/api/netbuf.c index 342717be..50625167 100644 --- a/src/api/netbuf.c +++ b/src/api/netbuf.c @@ -2,6 +2,12 @@ * @file * Network buffer management * + * @defgroup netbuf Network buffers + * @ingroup netconn + * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally + * to avoid copying data around.\n + * Buffers must not be shared accross multiple threads, all functions except + * netbuf_new() and netbuf_delete() are not thread-safe. */ /* @@ -36,15 +42,6 @@ * */ -/** - * @defgroup netbuf Network buffers - * @ingroup netconn - * Network buffer descriptor for @ref netconn. Based on @ref pbuf internally - * to avoid copying data around.\n - * Buffers must not be shared accross multiple threads, all functions except - * netbuf_new() and netbuf_delete() are not thread-safe. - */ - #include "lwip/opt.h" #if LWIP_NETCONN /* don't build if not configured for use in lwipopts.h */ diff --git a/src/api/netdb.c b/src/api/netdb.c index f9d63d46..670f6b97 100644 --- a/src/api/netdb.c +++ b/src/api/netdb.c @@ -2,6 +2,8 @@ * @file * API functions for name resolving * + * @defgroup netdbapi NETDB API + * @ingroup socket */ /* @@ -33,12 +35,6 @@ * */ - -/** - * @defgroup netdbapi NETDB API - * @ingroup socket - */ - #include "lwip/netdb.h" #if LWIP_DNS && LWIP_SOCKET diff --git a/src/api/netifapi.c b/src/api/netifapi.c index 3a02d521..265b60c5 100644 --- a/src/api/netifapi.c +++ b/src/api/netifapi.c @@ -2,6 +2,13 @@ * @file * Network Interface Sequential API module * + * @defgroup netifapi NETIF API + * @ingroup threadsafe_api + * Thread-safe functions to be called from non-TCPIP threads + * + * @defgroup netifapi_netif NETIF related + * @ingroup netifapi + * To be called from non-TCPIP threads */ /* @@ -31,16 +38,6 @@ * */ -/** - * @defgroup netifapi NETIF API - * @ingroup threadsafe_api - * Thread-safe functions to be called from non-TCPIP threads - * - * @defgroup netifapi_netif NETIF related - * @ingroup netifapi - * To be called from non-TCPIP threads - */ - #include "lwip/opt.h" #if LWIP_NETIF_API /* don't build if not configured for use in lwipopts.h */ diff --git a/src/api/sockets.c b/src/api/sockets.c index 6547182c..db90e16c 100644 --- a/src/api/sockets.c +++ b/src/api/sockets.c @@ -2,6 +2,12 @@ * @file * Sockets BSD-Like API module * + * @defgroup socket Socket API + * @ingroup threadsafe_api + * BSD-style socket API.\n + * Thread-safe, to be called from non-TCPIP threads only.\n + * Can be activated by defining @ref LWIP_SOCKET to 1.\n + * Header is in posix/sys/socket.h\b */ /* @@ -38,15 +44,6 @@ * */ -/** - * @defgroup socket Socket API - * @ingroup threadsafe_api - * BSD-style socket API.\n - * Thread-safe, to be called from non-TCPIP threads only.\n - * Can be activated by defining LWIP_SOCKET to 1.\n - * Header is in posix/sys/socket.h\b - */ - #include "lwip/opt.h" #if LWIP_SOCKET /* don't build if not configured for use in lwipopts.h */ diff --git a/src/core/def.c b/src/core/def.c index bb4b8e01..7d3c93fb 100644 --- a/src/core/def.c +++ b/src/core/def.c @@ -2,6 +2,16 @@ * @file * Common functions used throughout the stack. * + * These are reference implementations of the byte swapping functions. + * Again with the aim of being simple, correct and fully portable. + * Byte swapping is the second thing you would want to optimize. You will + * need to port it to your architecture and in your cc.h: + * + * \#define LWIP_PLATFORM_BYTESWAP 1 + * \#define LWIP_PLATFORM_HTONS(x) your_htons + * \#define LWIP_PLATFORM_HTONL(x) your_htonl + * + * Note ntohs() and ntohl() are merely references to the htonx counterparts. */ /* @@ -39,19 +49,6 @@ #include "lwip/opt.h" #include "lwip/def.h" -/** - * These are reference implementations of the byte swapping functions. - * Again with the aim of being simple, correct and fully portable. - * Byte swapping is the second thing you would want to optimize. You will - * need to port it to your architecture and in your cc.h: - * - * #define LWIP_PLATFORM_BYTESWAP 1 - * #define LWIP_PLATFORM_HTONS(x) - * #define LWIP_PLATFORM_HTONL(x) - * - * Note ntohs() and ntohl() are merely references to the htonx counterparts. - */ - #if (LWIP_PLATFORM_BYTESWAP == 0) && (BYTE_ORDER == LITTLE_ENDIAN) /** diff --git a/src/core/inet_chksum.c b/src/core/inet_chksum.c index 57cbad79..6ccf8391 100644 --- a/src/core/inet_chksum.c +++ b/src/core/inet_chksum.c @@ -1,7 +1,16 @@ /** * @file - * Incluse internet checksum functions. + * Incluse internet checksum functions.\n * + * These are some reference implementations of the checksum algorithm, with the + * aim of being simple, correct and fully portable. Checksumming is the + * first thing you would want to optimize for your platform. If you create + * your own version, link it in and in your cc.h put: + * + * \#define LWIP_CHKSUM your_checksum_routine + * + * Or you can select from the implementations below by defining + * LWIP_CHKSUM_ALGORITHM to 1, 2 or 3. */ /* @@ -45,17 +54,6 @@ #include #include -/* These are some reference implementations of the checksum algorithm, with the - * aim of being simple, correct and fully portable. Checksumming is the - * first thing you would want to optimize for your platform. If you create - * your own version, link it in and in your cc.h put: - * - * #define LWIP_CHKSUM - * - * Or you can select from the implementations below by defining - * LWIP_CHKSUM_ALGORITHM to 1, 2 or 3. - */ - #ifndef LWIP_CHKSUM # define LWIP_CHKSUM lwip_standard_chksum # ifndef LWIP_CHKSUM_ALGORITHM diff --git a/src/core/init.c b/src/core/init.c index bce01bef..22d5616c 100644 --- a/src/core/init.c +++ b/src/core/init.c @@ -35,29 +35,6 @@ * Author: Adam Dunkels */ -/** - * @defgroup lwip_nosys Mainloop mode ("NO_SYS") - * @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 them into 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.\n - * You can only use @ref callbackstyle_api in this mode.\n - * Sample code:\n - * @verbinclude NO_SYS_SampleCode.c - * - * @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.\n - * You can use @ref callbackstyle_api together with \#define tcpip_callback, - * and all @ref threadsafe_api. - */ - #include "lwip/opt.h" #include "lwip/init.h" diff --git a/src/core/ip.c b/src/core/ip.c index 89cd36a8..2e024085 100644 --- a/src/core/ip.c +++ b/src/core/ip.c @@ -1,7 +1,24 @@ /** - * @file ip.c + * @file * Common IPv4 and IPv6 code * + * @defgroup ip IP + * @ingroup callbackstyle_api + * + * @defgroup ip4 IPv4 + * @ingroup ip + * + * @defgroup ip6 IPv6 + * @ingroup ip + * + * @defgroup ipaddr IP address handling + * @ingroup infrastructure + * + * @defgroup ip4addr IPv4 only + * @ingroup ipaddr + * + * @defgroup ip6addr IPv6 only + * @ingroup ipaddr */ /* @@ -36,26 +53,6 @@ * */ -/** - * @defgroup ip IP - * @ingroup callbackstyle_api - * - * @defgroup ip4 IPv4 - * @ingroup ip - * - * @defgroup ip6 IPv6 - * @ingroup ip - * - * @defgroup ipaddr IP address handling - * @ingroup infrastructure - * - * @defgroup ip4addr IPv4 only - * @ingroup ipaddr - * - * @defgroup ip6addr IPv6 only - * @ingroup ipaddr - */ - #include "lwip/opt.h" #if LWIP_IPV4 || LWIP_IPV6 diff --git a/src/core/ipv4/autoip.c b/src/core/ipv4/autoip.c index 8ca26712..f9bc60c8 100644 --- a/src/core/ipv4/autoip.c +++ b/src/core/ipv4/autoip.c @@ -2,6 +2,28 @@ * @file * AutoIP Automatic LinkLocal IP Configuration * + * This is a AutoIP implementation for the lwIP TCP/IP stack. It aims to conform + * with RFC 3927. + * + * @defgroup autoip AUTOIP + * @ingroup ip4 + * AUTOIP related functions + * USAGE: + * + * define @ref LWIP_AUTOIP 1 in your lwipopts.h + * Options: + * @ref AUTOIP_TMR_INTERVAL msecs, + * I recommend a value of 100. The value must divide 1000 with a remainder almost 0. + * Possible values are 1000, 500, 333, 250, 200, 166, 142, 125, 111, 100 .... + * + * Without DHCP: + * - Call autoip_start() after netif_add(). + * + * With DHCP: + * - define @ref LWIP_DHCP_AUTOIP_COOP 1 in your lwipopts.h. + * - Configure your DHCP Client. + * + * @see netifapi_autoip */ /* @@ -32,41 +54,6 @@ * OF SUCH DAMAGE. * * Author: Dominik Spies - * - * This is a AutoIP implementation for the lwIP TCP/IP stack. It aims to conform - * with RFC 3927. - * - * - * Please coordinate changes and requests with Dominik Spies - * - */ - -/******************************************************************************* - * USAGE: - * - * define LWIP_AUTOIP 1 in your lwipopts.h - * - * If you don't use tcpip.c (so, don't call, you don't call tcpip_init): - * - First, call autoip_init(). - * - call autoip_tmr() all AUTOIP_TMR_INTERVAL msces, - * that should be defined in autoip.h. - * I recommend a value of 100. The value must divide 1000 with a remainder almost 0. - * Possible values are 1000, 500, 333, 250, 200, 166, 142, 125, 111, 100 .... - * - * Without DHCP: - * - Call autoip_start() after netif_add(). - * - * With DHCP: - * - define LWIP_DHCP_AUTOIP_COOP 1 in your lwipopts.h. - * - Configure your DHCP Client. - * - */ - -/** - * @defgroup autoip AUTOIP - * @ingroup ip4 - * AUTOIP related functions - * @see netifapi_autoip */ #include "lwip/opt.h" diff --git a/src/core/ipv4/dhcp.c b/src/core/ipv4/dhcp.c index b3307dac..7536af02 100644 --- a/src/core/ipv4/dhcp.c +++ b/src/core/ipv4/dhcp.c @@ -2,6 +2,26 @@ * @file * Dynamic Host Configuration Protocol client * + * @defgroup dhcp4 DHCPv4 + * @ingroup ip4 + * DHCP (IPv4) related functions + * This is a DHCP client for the lwIP TCP/IP stack. It aims to conform + * with RFC 2131 and RFC 2132. + * + * @todo: + * - Support for interfaces other than Ethernet (SLIP, PPP, ...) + * + * Options: + * @ref DHCP_COARSE_TIMER_SECS (recommended 60 which is a minute) + * @ref DHCP_FINE_TIMER_MSECS (recommended 500 which equals TCP coarse timer) + * + * dhcp_start() starts a DHCP client instance which + * configures the interface by obtaining an IP address lease and maintaining it. + * + * Use dhcp_release() to end the lease and use dhcp_stop() + * to remove the DHCP client. + * + * @see netifapi_dhcp4 */ /* @@ -38,38 +58,6 @@ * * Author: Leon Woestenberg * - * This is a DHCP client for the lwIP TCP/IP stack. It aims to conform - * with RFC 2131 and RFC 2132. - * - * @todo: - * - Support for interfaces other than Ethernet (SLIP, PPP, ...) - * - * Please coordinate changes and requests with Leon Woestenberg - * - * - * Integration with your code: - * - * In lwip/dhcp.h - * #define DHCP_COARSE_TIMER_SECS (recommended 60 which is a minute) - * #define DHCP_FINE_TIMER_MSECS (recommended 500 which equals TCP coarse timer) - * - * Then have your application call dhcp_coarse_tmr() and - * dhcp_fine_tmr() on the defined intervals. - * - * dhcp_start(struct netif *netif); - * starts a DHCP client instance which configures the interface by - * obtaining an IP address lease and maintaining it. - * - * Use dhcp_release(netif) to end the lease and use dhcp_stop(netif) - * to remove the DHCP client. - * - */ - -/** - * @defgroup dhcp4 DHCPv4 - * @ingroup ip4 - * DHCP (IPv4) related functions - * @see netifapi_dhcp4 */ #include "lwip/opt.h" diff --git a/src/core/ipv4/igmp.c b/src/core/ipv4/igmp.c index 089a7611..90a80d38 100644 --- a/src/core/ipv4/igmp.c +++ b/src/core/ipv4/igmp.c @@ -2,6 +2,9 @@ * @file * IGMP - Internet Group Management Protocol * + * @defgroup igmp IGMP + * @ingroup ip4 + * To be called from TCPIP thread */ /* @@ -38,12 +41,6 @@ * source code. */ -/** - * @defgroup igmp IGMP - * @ingroup ip4 - * To be called from TCPIP thread - */ - /*------------------------------------------------------------- Note 1) Although the rfc requires V1 AND V2 capability diff --git a/src/core/ipv6/mld6.c b/src/core/ipv6/mld6.c index ef854e76..82510019 100644 --- a/src/core/ipv6/mld6.c +++ b/src/core/ipv6/mld6.c @@ -1,5 +1,12 @@ /** * @file + * Multicast listener discovery + * + * @defgroup mld6 MLD6 + * @ingroup ip6 + * Multicast listener discovery for IPv6. Aims to be compliant with RFC 2710. + * No support for MLDv2.\n + * To be called from TCPIP thread */ /* @@ -37,14 +44,6 @@ * */ -/** - * @defgroup mld6 MLD6 - * @ingroup ip6 - * Multicast listener discovery for IPv6. Aims to be compliant with RFC 2710. - * No support for MLDv2.\n - * To be called from TCPIP thread - */ - /* Based on igmp.c implementation of igmp v2 protocol */ #include "lwip/opt.h" diff --git a/src/core/memp.c b/src/core/memp.c index 5d2c4fb5..6473e18b 100644 --- a/src/core/memp.c +++ b/src/core/memp.c @@ -4,6 +4,11 @@ * * lwIP has dedicated pools for many structures (netconn, protocol control blocks, * packet buffers, ...). All these pools are managed here. + * + * @defgroup mempool Memory pools + * @ingroup infrastructure + * Custom memory pools + */ /* @@ -38,12 +43,6 @@ * */ -/** - * @defgroup mempool Memory pools - * @ingroup infrastructure - * Custom memory pools - */ - #include "lwip/opt.h" #include "lwip/memp.h" diff --git a/src/core/netif.c b/src/core/netif.c index 86003175..33560ae9 100644 --- a/src/core/netif.c +++ b/src/core/netif.c @@ -1,6 +1,9 @@ /** * @file * lwIP network interface abstraction + * + * @defgroup netif Network interface (NETIF) + * @ingroup callbackstyle_api */ /* @@ -34,11 +37,6 @@ * Author: Adam Dunkels */ -/** - * @defgroup netif Network interface (NETIF) - * @ingroup callbackstyle_api - */ - #include "lwip/opt.h" #include "lwip/def.h" diff --git a/src/core/raw.c b/src/core/raw.c index 90f2e302..df94c4b3 100644 --- a/src/core/raw.c +++ b/src/core/raw.c @@ -4,6 +4,13 @@ * different types of protocols besides (or overriding) those * already available in lwIP.\n * See also @ref raw_raw + * + * @defgroup raw_raw RAW + * @ingroup raw_api + * Implementation of raw protocol PCBs for low-level handling of + * different types of protocols besides (or overriding) those + * already available in lwIP.\n + * @see @ref raw_api */ /* @@ -38,21 +45,6 @@ * */ -/** - * @defgroup raw_api RAW API - * @ingroup callbackstyle_api - * @verbinclude "rawapi.txt" - */ - -/** - * @defgroup raw_raw RAW - * @ingroup raw_api - * Implementation of raw protocol PCBs for low-level handling of - * different types of protocols besides (or overriding) those - * already available in lwIP.\n - * @see @ref raw_api - */ - #include "lwip/opt.h" #if LWIP_RAW /* don't build if not configured for use in lwipopts.h */ diff --git a/src/core/tcp.c b/src/core/tcp.c index dfda7965..09286e67 100644 --- a/src/core/tcp.c +++ b/src/core/tcp.c @@ -2,6 +2,15 @@ * @file * Transmission Control Protocol for IP * See also @ref tcp_raw + * + * @defgroup tcp_raw TCP + * @ingroup raw_api + * Transmission Control Protocol for IP\n + * @see @ref raw_api and @ref netconn + * + * Common functions for the TCP implementation, such as functinos + * for manipulating the data structures and the TCP timer functions. TCP functions + * related to input and output is found in tcp_in.c and tcp_out.c respectively.\n */ /* @@ -36,17 +45,6 @@ * */ -/** - * @defgroup tcp_raw TCP - * @ingroup raw_api - * Transmission Control Protocol for IP\n - * @see @ref raw_api and @ref netconn - * - * Common functions for the TCP implementation, such as functinos - * for manipulating the data structures and the TCP timer functions. TCP functions - * related to input and output is found in tcp_in.c and tcp_out.c respectively.\n - */ - #include "lwip/opt.h" #if LWIP_TCP /* don't build if not configured for use in lwipopts.h */ diff --git a/src/core/udp.c b/src/core/udp.c index 14130ab3..e7ff246d 100644 --- a/src/core/udp.c +++ b/src/core/udp.c @@ -1,7 +1,13 @@ /** * @file * User Datagram Protocol module\n + * The code for the User Datagram Protocol UDP & UDPLite (RFC 3828).\n * See also @ref udp_raw + * + * @defgroup udp_raw UDP + * @ingroup raw_api + * User Datagram Protocol module\n + * @see @ref raw_api and @ref netconn */ /* @@ -36,19 +42,6 @@ * */ -/** - * @defgroup udp_raw UDP - * @ingroup raw_api - * User Datagram Protocol module\n - * @see @ref raw_api and @ref netconn - */ - -/* udp.c - * - * The code for the User Datagram Protocol UDP & UDPLite (RFC 3828). - * - */ - /* @todo Check the use of '(struct udp_pcb).chksum_len_rx'! */