hi, On Thu, Jan 17, 2013 at 03:56:45PM +0100, chrysn wrote: > * an updated online documentation would be great, possibly in a new > subdirctory reflecting the version, so we can have documentation for > 1.3.0 (seems to be widespread still?), 1.4.1 and development at the > same time.
i've created a new Doxyfile that is supposed to give usable results with 1.4.1. unfortunately, it seems that the state of doxygenized docstrings has been rotting along, probably due to the doxygen docs often not being built by developers. examples thereof are missing @file specifiers for per-file comments (which get added to the comments of the next documentable entity), missing doxygen marks around @todo items or non-doxygen comments for batch #define lines (eg the ERR_* section). functions being documented at the implementation and the header is a decision i understand (and sometimes even like), but it requres doxygen to go through the *.c files too. that's not a problem per se (doxygen merges the descriptions from the *.c and *.h files, if there are any), but the functions end up being described in both places, and users might easily find their interface documentation on the same page as the internal constants and data structures of that module, and not find the #define lines from the respective header files there. to combat that, i'd put @defgroup commands in all of the header files. thus, the user accessible functions are described neatly in a tree-like structure in the "modules" section of the resulting doxygen files. the implementation details are still accessible via doxygen, and the functions stay linked from there. the results of having doxigenified README, doc/* and the UDP, DNS and error subsystems (at least superficially) can be viewed for the time being at [1]. the patch attached can be applied to the 1.4.1 version, and generated that with doxygen 1.8.1.2. currently, quite many graphs are enabled, i'd hav to see which are actually useful. those for structs are, in my opinion; the call graphs will be more useful when a user lwipopts.h can be applied, because then they'll show what's actually happening stack-wise. best regards chrysn [1] http://downloads.amsuess.com/lwip-1.4.1/html/ -- To use raw power is to make yourself infinitely vulnerable to greater powers. -- Bene Gesserit axiom
diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..ad7ad04 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,110 @@ +# Doxyfile 1.8.1.2 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. + +PROJECT_NAME = "lwIP" +PROJECT_NUMBER = "1.4.1" + +OUTPUT_DIRECTORY = "doxygen" + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C +# sources only. Doxygen will then generate output that is more tailored for C. +# For instance, some of the names that are used will be different. The list +# of all members will be omitted, etc. + +OPTIMIZE_OUTPUT_FOR_C = YES + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given extension. +# Doxygen has a built-in mapping, but you can override or extend it using this +# tag. The format is ext=language, where ext is a file extension, and language +# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, +# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make +# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C +# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions +# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. + +EXTENSION_MAPPING = c=C h=C txt=md + +# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# documentation are documented, even if no documentation was available. +# Private class members and static file members will be hidden unless +# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES + +EXTRACT_ALL = YES + +# The INPUT tag can be used to specify the files and/or directories that contain +# documented source files. You may enter file names like "myfile.cpp" or +# directories like "/usr/src/myproject". Separate the files or directories +# with spaces. + +INPUT = src/ doc/ README.txt + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp +# and *.h) to filter out the source-files in the directories. If left +# blank the following patterns are tested: +# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh +# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py +# *.f90 *.f *.for *.vhd *.vhdl + +FILE_PATTERNS = *.c *.h *.txt + +# The RECURSIVE tag can be used to turn specify whether or not subdirectories +# should be searched for input files as well. Possible values are YES and NO. +# If left blank NO is used. + +RECURSIVE = YES + +# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will +# generate Latex output. + +GENERATE_LATEX = NO + + +# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro +# names in the source code. If set to NO (the default) only conditional +# compilation will be performed. Macro expansion can be done in a controlled +# way by setting EXPAND_ONLY_PREDEF to YES. + +MACRO_EXPANSION = YES + +# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES +# then the macro expansion is limited to the macros specified with the +# PREDEFINED and EXPAND_AS_DEFINED tags. + +EXPAND_ONLY_PREDEF = YES + +# The INCLUDE_PATH tag can be used to specify one or more directories that +# contain include files that are not input files but should be processed by +# the preprocessor. + +INCLUDE_PATH = src/include/ src/include/ipv4/ src/include/ipv6/ + +# The PREDEFINED tag can be used to specify one or more macro names that +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are +# omitted =1 is assumed. To prevent a macro definition from being +# undefined via #undef or recursively expanded use the := operator +# instead of the = operator. + +# this list was created by goting through opt.h and using gut feeling to enable stuff that could potentially affect documentation. LWIP_DEBUG was added because it was needed for src/api/err.c. the PACK_STRUCT_* are usually defined in sys_arch.c and don't need to do much for doxygen, but they need to disappear. +PREDEFINED = SYS_LIGHTWEIGHT_PROT MEM_USE_POOLS IP_FORWARD LWIP_DHCP LWIP_AUTOIP LWIP_SNMP LWIP_IGMP LWIP_DNS LWIP_UDPLITE LWIP_HAVE_LOOPIF LWIP_HAVE_SLIPIF LWIP_TCP_KEEPALIVE LWIP_STATS_DISPLAY MEMP_STATS SYS_STATS PPP_SUPPORT PPPOE_SUPPORT PAP_SUPPORT CHAP_SUPPORT MSCHAP_SUPPORT CBCP_SUPPORT CCP_SUPPORT VJ_SUPPORT MD5_SUPPORT LWIP_DEBUG PACK_STRUCT_BEGIN:= PACK_STRUCT_END:= PACK_STRUCT_STRUCT:= PACK_STRUCT_FIELD(x):=x + + +# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is +# available from the path. This tool is part of Graphviz, a graph visualization +# toolkit from AT&T and Lucent Bell Labs. The other options in this section +# have no effect if this option is set to NO (the default) + +HAVE_DOT = YES + +# If the CALL_GRAPH and HAVE_DOT options are set to YES then +# doxygen will generate a call dependency graph for every global function +# or class method. Note that enabling this option will significantly increase +# the time of a run. So in most cases it will be better to enable call graphs +# for selected functions only using the \callgraph command. + +CALL_GRAPH = YES diff --git a/README b/README deleted file mode 100644 index a62cc4f..0000000 --- a/README +++ /dev/null @@ -1,89 +0,0 @@ -INTRODUCTION - -lwIP is a small independent implementation of the TCP/IP protocol -suite that has been developed by Adam Dunkels at the Computer and -Networks Architectures (CNA) lab at the Swedish Institute of Computer -Science (SICS). - -The focus of the lwIP TCP/IP implementation is to reduce the RAM usage -while still having a full scale TCP. This making lwIP suitable for use -in embedded systems with tens of kilobytes of free RAM and room for -around 40 kilobytes of code ROM. - -FEATURES - - * IP (Internet Protocol) including packet forwarding over multiple network - interfaces - * ICMP (Internet Control Message Protocol) for network maintenance and debugging - * IGMP (Internet Group Management Protocol) for multicast traffic management - * UDP (User Datagram Protocol) including experimental UDP-lite extensions - * TCP (Transmission Control Protocol) with congestion control, RTT estimation - and fast recovery/fast retransmit - * Specialized raw/native API for enhanced performance - * Optional Berkeley-like socket API - * DNS (Domain names resolver) - * SNMP (Simple Network Management Protocol) - * DHCP (Dynamic Host Configuration Protocol) - * AUTOIP (for IPv4, conform with RFC 3927) - * PPP (Point-to-Point Protocol) - * ARP (Address Resolution Protocol) for Ethernet - -LICENSE - -lwIP is freely available under a BSD license. - -DEVELOPMENT - -lwIP has grown into an excellent TCP/IP stack for embedded devices, -and developers using the stack often submit bug fixes, improvements, -and additions to the stack to further increase its usefulness. - -Development of lwIP is hosted on Savannah, a central point for -software development, maintenance and distribution. Everyone can -help improve lwIP by use of Savannah's interface, CVS and the -mailing list. A core team of developers will commit changes to the -CVS source tree. - -The lwIP TCP/IP stack is maintained in the 'lwip' CVS module and -contributions (such as platform ports) are in the 'contrib' module. - -See doc/savannah.txt for details on CVS server access for users and -developers. - -Last night's CVS tar ball can be downloaded from: - http://savannah.gnu.org/cvs.backups/lwip.tar.gz [CHANGED - NEEDS FIXING] - -The current CVS trees are web-browsable: - http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/lwip/ - http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/contrib/ - -Submit patches and bugs via the lwIP project page: - http://savannah.nongnu.org/projects/lwip/ - - -DOCUMENTATION - -The original out-dated homepage of lwIP and Adam Dunkels' papers on -lwIP are at the official lwIP home page: - http://www.sics.se/~adam/lwip/ - -Self documentation of the source code is regularly extracted from the -current CVS sources and is available from this web page: - http://www.nongnu.org/lwip/ - -There is now a constantly growin wiki about lwIP at - http://lwip.wikia.com/wiki/LwIP_Wiki - -Also, there are mailing lists you can subscribe at - http://savannah.nongnu.org/mail/?group=lwip -plus searchable archives: - http://lists.nongnu.org/archive/html/lwip-users/ - http://lists.nongnu.org/archive/html/lwip-devel/ - -Reading Adam's papers, the files in docs/, browsing the source code -documentation and browsing the mailing list archives is a good way to -become familiar with the design of lwIP. - -Adam Dunkels <[email protected]> -Leon Woestenberg <[email protected]> - diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..6f6adc4 --- /dev/null +++ b/README.txt @@ -0,0 +1,106 @@ +About lwIP {#mainpage} +========== + +Introduction +------------ + +lwIP is a small independent implementation of the TCP/IP protocol +suite that has been developed by Adam Dunkels at the Computer and +Networks Architectures (CNA) lab at the Swedish Institute of Computer +Science (SICS). + +The focus of the lwIP TCP/IP implementation is to reduce the RAM usage +while still having a full scale TCP. This making lwIP suitable for use +in embedded systems with tens of kilobytes of free RAM and room for +around 40 kilobytes of code ROM. + +Features +-------- + +* IP (Internet Protocol) including packet forwarding over multiple network + interfaces +* ICMP (Internet Control Message Protocol) for network maintenance and debugging +* IGMP (Internet Group Management Protocol) for multicast traffic management +* [UDP](@ref UDP) (User Datagram Protocol) including experimental UDP-lite extensions +* TCP (Transmission Control Protocol) with congestion control, RTT estimation + and fast recovery/fast retransmit +* Specialized raw/native API for enhanced performance +* Optional Berkeley-like socket API +* [DNS](@ref DNS) (Domain names resolver) +* SNMP (Simple Network Management Protocol) +* DHCP (Dynamic Host Configuration Protocol) +* AUTOIP (for IPv4, conform with RFC 3927) +* PPP (Point-to-Point Protocol) +* ARP (Address Resolution Protocol) for Ethernet + +License +------- + +lwIP is freely available under a BSD license. + +Development +----------- + +lwIP has grown into an excellent TCP/IP stack for embedded devices, +and developers using the stack often submit bug fixes, improvements, +and additions to the stack to further increase its usefulness. + +Development of lwIP is hosted on Savannah, a central point for +software development, maintenance and distribution. Everyone can +help improve lwIP by use of Savannah's interface, CVS and the +mailing list. A core team of developers will commit changes to the +CVS source tree. + +The lwIP TCP/IP stack is maintained in the 'lwip' CVS module and +contributions (such as platform ports) are in the 'contrib' module. + +See [doc/savannah.txt](@ref md_savannah) for details on CVS server access for users and +developers. + +Last night's CVS tar ball can be downloaded from: + + http://savannah.gnu.org/cvs.backups/lwip.tar.gz [CHANGED - NEEDS FIXING] + +The current CVS trees are web-browsable: + + http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/lwip/ + http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/contrib/ + +Submit patches and bugs via the lwIP project page: + + http://savannah.nongnu.org/projects/lwip/ + + +Documentation +------------- + +The original out-dated homepage of lwIP and Adam Dunkels' papers on +lwIP are at the official lwIP home page: + + http://www.sics.se/~adam/lwip/ + +Self documentation of the source code is regularly extracted from the +current CVS sources and is available from this web page: + + http://www.nongnu.org/lwip/ + +There is now a constantly growin wiki about lwIP at + + http://lwip.wikia.com/wiki/LwIP_Wiki + +Also, there are mailing lists you can subscribe at + + http://savannah.nongnu.org/mail/?group=lwip + +plus searchable archives: + + http://lists.nongnu.org/archive/html/lwip-users/ + http://lists.nongnu.org/archive/html/lwip-devel/ + +Reading Adam's papers, the files in [doc/](pages.html), browsing the source code +documentation and browsing the mailing list archives is a good way to +become familiar with the design of lwIP. + +Adam Dunkels <[email protected]> +Leon Woestenberg <[email protected]> + diff --git a/doc/contrib.txt b/doc/contrib.txt index 39596fc..ff22931 100644 --- a/doc/contrib.txt +++ b/doc/contrib.txt @@ -1,9 +1,14 @@ +Contributing to the lwIP development +==================================== + 1 Introduction +============== This document describes some guidelines for people participating in lwIP development. 2 How to contribute to lwIP +=========================== Here is a short list of suggestions to anybody working with lwIP and trying to contribute bug reports, fixes, enhancements, platform ports etc. @@ -12,6 +17,7 @@ to fixes or questions might often come late. Hopefully the bug and patch trackin features of Savannah help us not lose users' input. 2.1 Source code style: +---------------------- 1. do not use tabs. 2. indentation is two spaces per level (i.e. per tab). @@ -25,6 +31,7 @@ features of Savannah help us not lose users' input. 10. use current source code style as further reference. 2.2 Source code documentation style: +------------------------------------ 1. JavaDoc compliant and Doxygen compatible. 2. Function documentation above functions in .c files, not .h files. @@ -32,6 +39,7 @@ features of Savannah help us not lose users' input. 3. Use current documentation style as further reference. 2.3 Bug reports and patches: +---------------------------- 1. Make sure you are reporting bugs or send patches against the latest sources. (From the latest release and/or the current CVS sources.) @@ -56,8 +64,9 @@ features of Savannah help us not lose users' input. if it's not to the point and long :) so the chances for it to be applied are greater. 2.4 Platform porters: +--------------------- 1. If you have ported lwIP to a platform (an OS, a uC/processor or a combination of these) and you think it could benefit others[1] you might want discuss this on the mailing list. You can also ask for CVS access to submit and maintain your port in the contrib CVS module. - \ No newline at end of file + diff --git a/doc/rawapi.txt b/doc/rawapi.txt index 8c19030..38198ea 100644 --- a/doc/rawapi.txt +++ b/doc/rawapi.txt @@ -1,4 +1,5 @@ Raw TCP/IP interface for lwIP +============================= Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons diff --git a/doc/savannah.txt b/doc/savannah.txt index 409905b..b7385c9 100644 --- a/doc/savannah.txt +++ b/doc/savannah.txt @@ -1,4 +1,5 @@ Daily Use Guide for using Savannah for lwIP +=========================================== Table of Contents: @@ -15,15 +16,17 @@ Table of Contents: To perform an anonymous CVS checkout of the main trunk (this is where bug fixes and incremental enhancements occur), do this: -cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout lwip + cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout lwip Or, obtain a stable branch (updated with bug fixes only) as follows: -cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ - -r STABLE-0_7 -d lwip-0.7 lwip + + cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ + -r STABLE-0_7 -d lwip-0.7 lwip Or, obtain a specific (fixed) release as follows: -cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ - -r STABLE-0_7_0 -d lwip-0.7.0 lwip + + cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ + -r STABLE-0_7_0 -d lwip-0.7.0 lwip 3 Committers/developers CVS access using SSH -------------------------------------------- @@ -32,7 +35,7 @@ The Savannah server uses SSH (Secure Shell) protocol 2 authentication and encryp As such, CVS commits to the server occur through a SSH tunnel for project members. To create a SSH2 key pair in UNIX-like environments, do this: -ssh-keygen -t dsa + ssh-keygen -t dsa Under Windows, a recommended SSH client is "PuTTY", freely available with good documentation and a graphic user interface. Use its key generator. @@ -42,18 +45,18 @@ a while so that Savannah can update its configuration (This can take minutes). Try to login using SSH: -ssh -v [email protected] + ssh -v [email protected] If it tells you: -Authenticating with public key "your_key_name"... -Server refused to allocate pty + Authenticating with public key "your_key_name"... + Server refused to allocate pty then you could login; Savannah refuses to give you a shell - which is OK, as we are allowed to use SSH for CVS only. Now, you should be able to do this: -export CVS_RSH=ssh -cvs -z3 -d:ext:[email protected]:/sources/lwip co lwip + export CVS_RSH=ssh + cvs -z3 -d:ext:[email protected]:/sources/lwip co lwip after which you can edit your local files with bug fixes or new features and commit them. Make sure you know what you are doing when using CVS to make @@ -82,18 +85,20 @@ MERGE ACTION (REPLACING EXISTING TAGS WITH THE SAME NAME). Merge all changes in DEVEL since our last merge to main: In the working copy of the main trunk: -cvs update -P -jmerged_from_DEVEL_to_main -jDEVEL + + cvs update -P -jmerged_from_DEVEL_to_main -jDEVEL (This will apply the changes between 'merged_from_DEVEL_to_main' and 'DEVEL' to your work set of files) We can now commit the merge result. -cvs commit -R -m "Merged from DEVEL to main." + + cvs commit -R -m "Merged from DEVEL to main." If this worked out OK, we now move the tag in the DEVEL branch to this merge point, so we can use this point for future merges: -cvs rtag -F -r DEVEL merged_from_DEVEL_to_main lwip + cvs rtag -F -r DEVEL merged_from_DEVEL_to_main lwip 4 How to release lwIP --------------------- @@ -105,26 +110,27 @@ Login CVS using pserver authentication, then export a clean copy of the tagged tree. Export is similar to a checkout, except that the CVS metadata is not created locally. -export CVS_RSH=ssh -cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ - -r STABLE-0_6_3 -d lwip-0.6.3 lwip + export CVS_RSH=ssh + cvs -z3 -d:pserver:[email protected]:/sources/lwip checkout \ + -r STABLE-0_6_3 -d lwip-0.6.3 lwip Archive this directory using tar, gzip'd, bzip2'd and zip'd. -tar czvf lwip-0.6.3.tar.gz lwip-0.6.3 -tar cjvf lwip-0.6.3.tar.bz2 lwip-0.6.3 -zip -r lwip-0.6.3.zip lwip-0.6.3 + tar czvf lwip-0.6.3.tar.gz lwip-0.6.3 + tar cjvf lwip-0.6.3.tar.bz2 lwip-0.6.3 + zip -r lwip-0.6.3.zip lwip-0.6.3 Now, sign the archives with a detached GPG binary signature as follows: -gpg -b lwip-0.6.3.tar.gz -gpg -b lwip-0.6.3.tar.bz2 -gpg -b lwip-0.6.3.zip + gpg -b lwip-0.6.3.tar.gz + gpg -b lwip-0.6.3.tar.bz2 + gpg -b lwip-0.6.3.zip Upload these files using anonymous FTP: -ncftp ftp://savannah.gnu.org/incoming/savannah/lwip -ncftp>mput *0.6.3.* + ncftp ftp://savannah.gnu.org/incoming/savannah/lwip + + ~ncftp>mput *0.6.3.* Additionally, you may post a news item on Savannah, like this: @@ -132,4 +138,4 @@ A new 0.6.3 release is now available here: http://savannah.nongnu.org/files/?group=lwip&highlight=0.6.3 You will have to submit this via the user News interface, then approve -this via the Administrator News interface. \ No newline at end of file +this via the Administrator News interface. diff --git a/doc/snmp_agent.txt b/doc/snmp_agent.txt index 2653230..817f8ca 100644 --- a/doc/snmp_agent.txt +++ b/doc/snmp_agent.txt @@ -1,4 +1,5 @@ SNMPv1 agent for lwIP +===================== Author: Christiaan Simons @@ -7,7 +8,7 @@ Note the agent uses the raw-API UDP interface so you may also want to read rawapi.txt to gain a better understanding of the SNMP message handling. 0 Agent Capabilities -==================== +-------------------- SNMPv1 per RFC1157 This is an old(er) standard but is still widely supported. @@ -52,7 +53,7 @@ Large SNMP message support local requirement. 1 Building the Agent -==================== +-------------------- First of all you'll need to add the following define to your local lwipopts.h: @@ -66,7 +67,7 @@ Note you'll might need to adapt you network driver to update the mib2 variables for your interface. 2 Running the Agent -=================== +------------------- The following function calls must be made in your program to actually get the SNMP agent running. @@ -109,7 +110,7 @@ snmp_get_sysuptime). 3 Private MIBs -============== +-------------- If want to extend the agent with your own private MIB you'll need to add the following define to your local lwipopts.h: @@ -141,7 +142,7 @@ The next chapter gives a more detailed description of the MIB-2 tree and the optional private MIB. 4 The Gory Details -================== +------------------ 4.0 Object identifiers and the MIB tree. @@ -178,4 +179,4 @@ turn use dynamically allocated index trees from RAM. These trees are updated by e.g. the etharp code when new entries are made or removed form the ARP cache. -/** @todo more gory details */ +@todo more gory details diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt index 847cd77..03fbca2 100644 --- a/doc/sys_arch.txt +++ b/doc/sys_arch.txt @@ -1,4 +1,5 @@ sys_arch interface for lwIP 0.6++ +================================= Author: Adam Dunkels @@ -223,24 +224,28 @@ cc.h - Architecture environment, some compiler specific, some to sys_arch.h.) Typedefs for the types used by lwip - - u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t + + u8_t, s8_t, u16_t, s16_t, u32_t, s32_t, mem_ptr_t Compiler hints for packing lwip's structures - - PACK_STRUCT_FIELD(x) - PACK_STRUCT_STRUCT - PACK_STRUCT_BEGIN - PACK_STRUCT_END + + PACK_STRUCT_FIELD(x) + PACK_STRUCT_STRUCT + PACK_STRUCT_BEGIN + PACK_STRUCT_END Platform specific diagnostic output - - LWIP_PLATFORM_DIAG(x) - non-fatal, print a message. - LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution. - Portability defines for printf formatters: - U16_F, S16_F, X16_F, U32_F, S32_F, X32_F, SZT_F + + LWIP_PLATFORM_DIAG(x) - non-fatal, print a message. + LWIP_PLATFORM_ASSERT(x) - fatal, print message and abandon execution. + Portability defines for printf formatters: + U16_F, S16_F, X16_F, U32_F, S32_F, X32_F, SZT_F "lightweight" synchronization mechanisms - - SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable. - SYS_ARCH_PROTECT(x) - enter protection mode. - SYS_ARCH_UNPROTECT(x) - leave protection mode. + + SYS_ARCH_DECL_PROTECT(x) - declare a protection state variable. + SYS_ARCH_PROTECT(x) - enter protection mode. + SYS_ARCH_UNPROTECT(x) - leave protection mode. If the compiler does not provide memset() this file must include a definition of it, or include a file which defines it. @@ -251,17 +256,23 @@ cc.h - Architecture environment, some compiler specific, some perf.h - Architecture specific performance measurement. + Measurement calls made throughout lwip, these can be defined to nothing. - PERF_START - start measuring something. - PERF_STOP(x) - stop measuring something, and record the result. + + PERF_START - start measuring something. + PERF_STOP(x) - stop measuring something, and record the result. sys_arch.h - Tied to sys_arch.c Arch dependent types for the following objects: - sys_sem_t, sys_mbox_t, sys_thread_t, + + sys_sem_t, sys_mbox_t, sys_thread_t, + And, optionally: - sys_prot_t + + sys_prot_t Defines to set vars of sys_mbox_t and sys_sem_t to NULL. - SYS_MBOX_NULL NULL - SYS_SEM_NULL NULL + + SYS_MBOX_NULL NULL + SYS_SEM_NULL NULL diff --git a/src/core/dns.c b/src/core/dns.c index d633612..e8f9416 100644 --- a/src/core/dns.c +++ b/src/core/dns.c @@ -2,15 +2,14 @@ * @file * DNS - host name to IP address resolver. * - */ - -/** * This file implements a DNS host name to IP address resolver. * Port to lwIP from uIP * by Jim Pettinato April 2007 + */ +/* * uIP version Copyright (c) 2002-2003, Adam Dunkels. * All rights reserved. * @@ -64,9 +63,11 @@ * RFC 2181 - Clarifications to the DNS Specification *----------------------------------------------------------------------------*/ -/** @todo: define good default values (rfc compliance) */ -/** @todo: improve answer parsing, more checkings... */ -/** @todo: check RFC1035 - 7.3. Processing responses */ +/** @file + * @todo define good default values (rfc compliance) + * @todo improve answer parsing, more checkings... + * @todo check RFC1035 - 7.3. Processing responses + */ /*----------------------------------------------------------------------------- * Includes diff --git a/src/core/udp.c b/src/core/udp.c index 32c7d38..92d31e5 100644 --- a/src/core/udp.c +++ b/src/core/udp.c @@ -37,13 +37,12 @@ */ -/* udp.c +/** @file + * udp.c * * The code for the User Datagram Protocol UDP & UDPLite (RFC 3828). * - */ - -/* @todo Check the use of '(struct udp_pcb).chksum_len_rx'! + * @todo Check the use of '(struct udp_pcb).chksum_len_rx'! */ #include "lwip/opt.h" diff --git a/src/include/lwip/dns.h b/src/include/lwip/dns.h index 6c7d9b0..6d71433 100644 --- a/src/include/lwip/dns.h +++ b/src/include/lwip/dns.h @@ -1,11 +1,14 @@ -/** +/** @file + * * lwip DNS resolver header file. * Author: Jim Pettinato * April 2007 * ported from uIP resolv.c Copyright (c) 2002-2003, Adam Dunkels. - * + */ + +/* * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: @@ -38,6 +41,9 @@ #if LWIP_DNS /* don't build if not configured for use in lwipopts.h */ +/** @defgroup DNS DNS Subsystem + * @{ */ + #ifdef __cplusplus extern "C" { #endif @@ -45,30 +51,34 @@ extern "C" { /** DNS timer period */ #define DNS_TMR_INTERVAL 1000 -/** DNS field TYPE used for "Resource Records" */ -#define DNS_RRTYPE_A 1 /* a host address */ -#define DNS_RRTYPE_NS 2 /* an authoritative name server */ -#define DNS_RRTYPE_MD 3 /* a mail destination (Obsolete - use MX) */ -#define DNS_RRTYPE_MF 4 /* a mail forwarder (Obsolete - use MX) */ -#define DNS_RRTYPE_CNAME 5 /* the canonical name for an alias */ -#define DNS_RRTYPE_SOA 6 /* marks the start of a zone of authority */ -#define DNS_RRTYPE_MB 7 /* a mailbox domain name (EXPERIMENTAL) */ -#define DNS_RRTYPE_MG 8 /* a mail group member (EXPERIMENTAL) */ -#define DNS_RRTYPE_MR 9 /* a mail rename domain name (EXPERIMENTAL) */ -#define DNS_RRTYPE_NULL 10 /* a null RR (EXPERIMENTAL) */ -#define DNS_RRTYPE_WKS 11 /* a well known service description */ -#define DNS_RRTYPE_PTR 12 /* a domain name pointer */ -#define DNS_RRTYPE_HINFO 13 /* host information */ -#define DNS_RRTYPE_MINFO 14 /* mailbox or mail list information */ -#define DNS_RRTYPE_MX 15 /* mail exchange */ -#define DNS_RRTYPE_TXT 16 /* text strings */ - -/** DNS field CLASS used for "Resource Records" */ -#define DNS_RRCLASS_IN 1 /* the Internet */ -#define DNS_RRCLASS_CS 2 /* the CSNET class (Obsolete - used only for examples in some obsolete RFCs) */ -#define DNS_RRCLASS_CH 3 /* the CHAOS class */ -#define DNS_RRCLASS_HS 4 /* Hesiod [Dyer 87] */ -#define DNS_RRCLASS_FLUSH 0x800 /* Flush bit */ +/** @defgroup DNS_type DNS field TYPE used for "Resource Records" + * @{ */ +#define DNS_RRTYPE_A 1 /**< a host address */ +#define DNS_RRTYPE_NS 2 /**< an authoritative name server */ +#define DNS_RRTYPE_MD 3 /**< a mail destination (Obsolete - use MX) */ +#define DNS_RRTYPE_MF 4 /**< a mail forwarder (Obsolete - use MX) */ +#define DNS_RRTYPE_CNAME 5 /**< the canonical name for an alias */ +#define DNS_RRTYPE_SOA 6 /**< marks the start of a zone of authority */ +#define DNS_RRTYPE_MB 7 /**< a mailbox domain name (EXPERIMENTAL) */ +#define DNS_RRTYPE_MG 8 /**< a mail group member (EXPERIMENTAL) */ +#define DNS_RRTYPE_MR 9 /**< a mail rename domain name (EXPERIMENTAL) */ +#define DNS_RRTYPE_NULL 10 /**< a null RR (EXPERIMENTAL) */ +#define DNS_RRTYPE_WKS 11 /**< a well known service description */ +#define DNS_RRTYPE_PTR 12 /**< a domain name pointer */ +#define DNS_RRTYPE_HINFO 13 /**< host information */ +#define DNS_RRTYPE_MINFO 14 /**< mailbox or mail list information */ +#define DNS_RRTYPE_MX 15 /**< mail exchange */ +#define DNS_RRTYPE_TXT 16 /**< text strings */ +/** @} */ + +/** @defgroup DNS_class DNS field CLASS used for "Resource Records" + * @{ */ +#define DNS_RRCLASS_IN 1 /**< the Internet */ +#define DNS_RRCLASS_CS 2 /**< the CSNET class (Obsolete - used only for examples in some obsolete RFCs) */ +#define DNS_RRCLASS_CH 3 /**< the CHAOS class */ +#define DNS_RRCLASS_HS 4 /**< Hesiod [Dyer 87] */ +#define DNS_RRCLASS_FLUSH 0x800 /**< Flush bit */ +/** @} */ /* The size used for the next line is rather a hack, but it prevents including socket.h in all files that include memp.h, and that would possibly break portability (since socket.h defines some types @@ -119,6 +129,8 @@ err_t dns_local_addhost(const char *hostname, const ip_addr_t *addr); } #endif +/** @} */ + #endif /* LWIP_DNS */ #endif /* __LWIP_DNS_H__ */ diff --git a/src/include/lwip/err.h b/src/include/lwip/err.h index ac90772..7ecddeb 100644 --- a/src/include/lwip/err.h +++ b/src/include/lwip/err.h @@ -32,6 +32,9 @@ #ifndef __LWIP_ERR_H__ #define __LWIP_ERR_H__ +/** @defgroup ERR Error handling + * @{ */ + #include "lwip/opt.h" #include "lwip/arch.h" @@ -49,27 +52,27 @@ typedef s8_t err_t; /* Definitions for error constants. */ -#define ERR_OK 0 /* No error, everything OK. */ -#define ERR_MEM -1 /* Out of memory error. */ -#define ERR_BUF -2 /* Buffer error. */ -#define ERR_TIMEOUT -3 /* Timeout. */ -#define ERR_RTE -4 /* Routing problem. */ -#define ERR_INPROGRESS -5 /* Operation in progress */ -#define ERR_VAL -6 /* Illegal value. */ -#define ERR_WOULDBLOCK -7 /* Operation would block. */ -#define ERR_USE -8 /* Address in use. */ -#define ERR_ISCONN -9 /* Already connected. */ +#define ERR_OK 0 /**< No error, everything OK. */ +#define ERR_MEM -1 /**< Out of memory error. */ +#define ERR_BUF -2 /**< Buffer error. */ +#define ERR_TIMEOUT -3 /**< Timeout. */ +#define ERR_RTE -4 /**< Routing problem. */ +#define ERR_INPROGRESS -5 /**< Operation in progress */ +#define ERR_VAL -6 /**< Illegal value. */ +#define ERR_WOULDBLOCK -7 /**< Operation would block. */ +#define ERR_USE -8 /**< Address in use. */ +#define ERR_ISCONN -9 /**< Already connected. */ #define ERR_IS_FATAL(e) ((e) < ERR_ISCONN) -#define ERR_ABRT -10 /* Connection aborted. */ -#define ERR_RST -11 /* Connection reset. */ -#define ERR_CLSD -12 /* Connection closed. */ -#define ERR_CONN -13 /* Not connected. */ +#define ERR_ABRT -10 /**< Connection aborted. */ +#define ERR_RST -11 /**< Connection reset. */ +#define ERR_CLSD -12 /**< Connection closed. */ +#define ERR_CONN -13 /**< Not connected. */ -#define ERR_ARG -14 /* Illegal argument. */ +#define ERR_ARG -14 /**< Illegal argument. */ -#define ERR_IF -15 /* Low-level netif error */ +#define ERR_IF -15 /**< Low-level netif error */ #ifdef LWIP_DEBUG @@ -82,4 +85,6 @@ extern const char *lwip_strerr(err_t err); } #endif +/** @} */ + #endif /* __LWIP_ERR_H__ */ diff --git a/src/include/lwip/udp.h b/src/include/lwip/udp.h index f1e6d3f..0cc08bd 100644 --- a/src/include/lwip/udp.h +++ b/src/include/lwip/udp.h @@ -36,6 +36,9 @@ #if LWIP_UDP /* don't build if not configured for use in lwipopts.h */ +/** @defgroup UDP UDP Subsystem + * @{ */ + #include "lwip/pbuf.h" #include "lwip/netif.h" #include "lwip/ip_addr.h" @@ -166,6 +169,8 @@ void udp_debug_print(struct udp_hdr *udphdr); } #endif +/** @} */ + #endif /* LWIP_UDP */ #endif /* __LWIP_UDP_H__ */
signature.asc
Description: Digital signature
_______________________________________________ lwip-users mailing list [email protected] https://lists.nongnu.org/mailman/listinfo/lwip-users
