Some documentation cleanups and include more comments that have been already in code into doxygen docs

This commit is contained in:
Dirk Ziegelmeier 2016-08-07 10:05:34 +02:00
parent cf66233873
commit 8d07629b71
19 changed files with 190 additions and 254 deletions

View File

@ -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"
*/

View File

@ -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 <adam@sics.se>
*/
/**
* @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 */

View File

@ -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 */

View File

@ -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

View File

@ -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 */

View File

@ -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 */

View File

@ -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) <your_htons>
* #define LWIP_PLATFORM_HTONL(x) <your_htonl>
*
* Note ntohs() and ntohl() are merely references to the htonx counterparts.
*/
#if (LWIP_PLATFORM_BYTESWAP == 0) && (BYTE_ORDER == LITTLE_ENDIAN)
/**

View File

@ -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 <stddef.h>
#include <string.h>
/* 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.
*/
#ifndef LWIP_CHKSUM
# define LWIP_CHKSUM lwip_standard_chksum
# ifndef LWIP_CHKSUM_ALGORITHM

View File

@ -35,29 +35,6 @@
* Author: Adam Dunkels <adam@sics.se>
*/
/**
* @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"

View File

@ -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

View File

@ -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 <kontakt@dspies.de>
*
* 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
* <kontakt@dspies.de>
*/
/*******************************************************************************
* 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"

View File

@ -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 <leon.woestenberg@gmx.net>
*
* 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
* <leon.woestenberg@gmx.net>
*
* 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"

View File

@ -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

View File

@ -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 @@
* <delamer@inicotech.com>
*/
/**
* @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"

View File

@ -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"

View File

@ -1,6 +1,9 @@
/**
* @file
* lwIP network interface abstraction
*
* @defgroup netif Network interface (NETIF)
* @ingroup callbackstyle_api
*/
/*
@ -34,11 +37,6 @@
* Author: Adam Dunkels <adam@sics.se>
*/
/**
* @defgroup netif Network interface (NETIF)
* @ingroup callbackstyle_api
*/
#include "lwip/opt.h"
#include "lwip/def.h"

View File

@ -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 */

View File

@ -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 */

View File

@ -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'!
*/