README
1INTRODUCTION
2
3lwIP is a small independent implementation of the TCP/IP protocol
4suite that has been developed by Adam Dunkels at the Computer and
5Networks Architectures (CNA) lab at the Swedish Institute of Computer
6Science (SICS).
7
8The focus of the lwIP TCP/IP implementation is to reduce the RAM usage
9while still having a full scale TCP. This making lwIP suitable for use
10in embedded systems with tens of kilobytes of free RAM and room for
11around 40 kilobytes of code ROM.
12
13FEATURES
14
15 * IP (Internet Protocol) including packet forwarding over multiple network
16 interfaces
17 * ICMP (Internet Control Message Protocol) for network maintenance and debugging
18 * IGMP (Internet Group Management Protocol) for multicast traffic management
19 * UDP (User Datagram Protocol) including experimental UDP-lite extensions
20 * TCP (Transmission Control Protocol) with congestion control, RTT estimation
21 and fast recovery/fast retransmit
22 * Specialized raw/native API for enhanced performance
23 * Optional Berkeley-like socket API
24 * DNS (Domain names resolver)
25 * SNMP (Simple Network Management Protocol)
26 * DHCP (Dynamic Host Configuration Protocol)
27 * AUTOIP (for IPv4, conform with RFC 3927)
28 * PPP (Point-to-Point Protocol)
29 * ARP (Address Resolution Protocol) for Ethernet
30
31LICENSE
32
33lwIP is freely available under a BSD license.
34
35DEVELOPMENT
36
37lwIP has grown into an excellent TCP/IP stack for embedded devices,
38and developers using the stack often submit bug fixes, improvements,
39and additions to the stack to further increase its usefulness.
40
41Development of lwIP is hosted on Savannah, a central point for
42software development, maintenance and distribution. Everyone can
43help improve lwIP by use of Savannah's interface, CVS and the
44mailing list. A core team of developers will commit changes to the
45CVS source tree.
46
47The lwIP TCP/IP stack is maintained in the 'lwip' CVS module and
48contributions (such as platform ports) are in the 'contrib' module.
49
50See doc/savannah.txt for details on CVS server access for users and
51developers.
52
53Last night's CVS tar ball can be downloaded from:
54 http://savannah.gnu.org/cvs.backups/lwip.tar.gz [CHANGED - NEEDS FIXING]
55
56The current CVS trees are web-browsable:
57 http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/lwip/
58 http://savannah.nongnu.org/cgi-bin/viewcvs/lwip/contrib/
59
60Submit patches and bugs via the lwIP project page:
61 http://savannah.nongnu.org/projects/lwip/
62
63
64DOCUMENTATION
65
66The original out-dated homepage of lwIP and Adam Dunkels' papers on
67lwIP are at the official lwIP home page:
68 http://www.sics.se/~adam/lwip/
69
70Self documentation of the source code is regularly extracted from the
71current CVS sources and is available from this web page:
72 http://www.nongnu.org/lwip/
73
74There is now a constantly growin wiki about lwIP at
75 http://lwip.scribblewiki.com/
76
77Also, there are mailing lists you can subscribe at
78 http://savannah.nongnu.org/mail/?group=lwip
79plus searchable archives:
80 http://lists.nongnu.org/archive/html/lwip-users/
81 http://lists.nongnu.org/archive/html/lwip-devel/
82
83Reading Adam's papers, the files in docs/, browsing the source code
84documentation and browsing the mailing list archives is a good way to
85become familiar with the design of lwIP.
86
87Adam Dunkels <adam@sics.se>
88Leon Woestenberg <leon.woestenberg@gmx.net>
89
90
README.barrelfish
1Name: lwIP
2Description: A Lightweight TCP/IP stack
3URL: http://savannah.nongnu.org/projects/lwip/
4License: BSD
5Version: 1.3.1 (18 Aug 2009)
6
7Usage and known issues
8----------------------
9* See //README_NETWORKING which covers general aspects of the network stack.
10
11* lwIP needs to be initialized before usage:
12 1. Call 'lwip_init_auto' or one of its variants.
13 2. Start a thread running 'network_polling_loop' or make sure to regularly
14 service events on 'lwip_waitset'.
15 Look at 'network_setup_helper' in //usr/net-test.
16
17 A common culprit of neglecting to do this is that socket calls return an
18 invalid handle (fd = -1) or fail with the error "out of memory in pool
19 NETCONN".
20
21* For a high-level overview of lwIP consider reading:
22 Dunkels, Adam. "Design and Implementation of the lwIP TCP/IP Stack."
23 Swedish Institute of Computer Science 2 (2001): 77.
24 Last seen at:
25 http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.109.1795
26
27 Some information in that document may be outdated so it is also a good idea
28 to complement this by reading the latest manual:
29 http://lwip.wikia.com/
30
31* lwIP exposes three different levels of APIs:
32 - 'Raw': event-based, directly interface with internal stack (supports
33 zero-copy), bypasses OS support layer but only one thread can run the
34 packet processing loop and perform socket operations.
35 - 'Netconn': sequential API, designed to be easier to use but preserve
36 zero-copy, provides more abstraction and thread synchronisation.
37 - 'Sockets': BSD-style, blocking calls.
38 More details can be found in:
39 http://lwip.wikia.com/wiki/Application_API_layers
40 http://www.actel.com/documents/A2F_AC365_AN.pdf
41
42* BSD-style sockets are available (see posixcompat) but these are known to have
43 problems. Small scale tests work fine but in a multi-threaded environment,
44 assertion failures can be triggered in lwIP's core/API layer.
45
46 Applications are recommended to use the event-based 'raw' API if possible:
47 http://git.savannah.gnu.org/cgit/lwip.git/tree/doc/rawapi.txt
48 http://lwip.wikia.com/wiki/Raw/native_API
49 http://lwip.wikia.com/wiki/Raw/TCP
50 For example usage see //usr/netfile and //usr/webserver.
51
52 (Note: failure reason is not known but the sockets API should be thread-safe.
53 http://lists.gnu.org/archive/html/lwip-users/2010-04/msg00055.html)
54
55* Possible deadlock when using the loopback interface:
56 https://lists.inf.ethz.ch/pipermail/barrelfish-users/2013-February/000908.html
57
58Modifications
59-------------
60* Some of the components added to the Barrelfish port:
61 - include/lwip/barrelfish.h, src/barrelfish/*
62
63 - src/sys_arch.c
64 OS-specific emulation layer which implements semaphores, mailboxes and
65 thread support.
66 http://git.savannah.gnu.org/cgit/lwip.git/tree/doc/sys_arch.txt
67 http://lwip.wikia.com/wiki/Porting_for_an_OS
68 http://git.savannah.gnu.org/cgit/lwip/lwip-contrib.git/tree/ports
69
70 - include/netif/bfeth.h, src/netif/bfeth.c
71 Transmits packets to and from the network driver.
72
73 - include/lwip/sock_serialise.h
74 Copies socket handles. Used for inheritance of file descriptors in a newly
75 spawned dispatcher.
76
77* lwIP needs to be invoked at regular intervals so it can handle tasks such as
78 TCP retransmissions. In the Barrelfish port this is done by registering a
79 periodic event during lwIP initialisation which calls 'tcp_tmr' every 250 ms.
80 For this to work, the application needs to service lwIP's own waitset.
81
82* Operations which are ordinarily handled by lwIP are instead performed
83 centrally by the network daemon (netd):
84 - Port number allocations; see 'tcp_bind', idc_net_control.c and net_ports.if
85 - ARP lookups; see ARP_lookup_client.c and net_ARP.if
86
87* lwIP requests memory from the OS and divvies this up internally.
88 - The backing buffers for these memory pools are created from frame
89 capabilities so they can be passed to device drivers
90 (see src/barrelfish/mem_barrelfish.c)
91 - The default pool sizes should suffice but you may need to increase them
92 (see //include/lwip/opt.h)
93
94* Support for PPP (Point-to-Point Protocol) has been removed:
95 include/netif/ppp_oe.h
96 src/netif/ppp/*
97
98* Code style has been modified extensively. To compare against upstream version,
99 first build a recent version of LLVM/Clang, normalize formatting of both
100 codebases and then run the diff:
101 $ find . -name '*.[ch]' -exec clang-format -i {} \;
102