/**
\mainpage The uIP TCP/IP stack
\author Adam Dunkels, http://www.sics.se/~adam/
The uIP TCP/IP stack is intended to make it possible to communicate
using the TCP/IP protocol suite even on small 8-bit
micro-controllers. Despite being small and simple, uIP do not require
their peers to have complex, full-size stacks, but can communicate
with peers running a similarly light-weight stack. The code size is on
the order of a few kilobytes and RAM usage can be configured to be as
low as a few hundred bytes.
uIP can be found at the uIP web page: http://www.sics.se/~adam/uip/
\sa \ref apps "Application programs"
\sa \ref uipopt "Compile-time configuration options"
\sa \ref uipconffunc "Run-time configuration functions"
\sa \ref uipinit "Initialization functions"
\sa \ref uipdevfunc "Device driver interface" and
\ref uipdrivervars "variables used by device drivers"
\sa \ref uipappfunc "uIP functions called from application programs"
(see below) and the \ref psock "protosockets API" and their underlying
\ref pt "protothreads"
\section uIPIntroduction Introduction
With the success of the Internet, the TCP/IP protocol suite has become
a global standard for communication. TCP/IP is the underlying protocol
used for web page transfers, e-mail transmissions, file transfers, and
peer-to-peer networking over the Internet. For embedded systems, being
able to run native TCP/IP makes it possible to connect the system
directly to an intranet or even the global Internet. Embedded devices
with full TCP/IP support will be first-class network citizens, thus
being able to fully communicate with other hosts in the network.
Traditional TCP/IP implementations have required far too much
resources both in terms of code size and memory usage to be useful in
small 8 or 16-bit systems. Code size of a few hundred kilobytes and
RAM requirements of several hundreds of kilobytes have made it
impossible to fit the full TCP/IP stack into systems with a few tens
of kilobytes of RAM and room for less than 100 kilobytes of
code.
The uIP implementation is designed to have only the absolute minimal
set of features needed for a full TCP/IP stack. It can only handle a
single network interface and contains the IP, ICMP, UDP and TCP
protocols. uIP is written in the C programming language.
Many other TCP/IP implementations for small systems assume that the
embedded device always will communicate with a full-scale TCP/IP
implementation running on a workstation-class machine. Under this
assumption, it is possible to remove certain TCP/IP mechanisms that
are very rarely used in such situations. Many of those mechanisms are
essential, however, if the embedded device is to communicate with
another equally limited device, e.g., when running distributed
peer-to-peer services and protocols. uIP is designed to be RFC
compliant in order to let the embedded devices to act as first-class
network citizens. The uIP TCP/IP implementation that is not tailored
for any specific application.
\section tcpip TCP/IP Communication
The full TCP/IP suite consists of numerous protocols, ranging from low
level protocols such as ARP which translates IP addresses to MAC
addresses, to application level protocols such as SMTP that is used to
transfer e-mail. The uIP is mostly concerned with the TCP and IP
protocols and upper layer protocols will be referred to as "the
application". Lower layer protocols are often implemented in hardware
or firmware and will be referred to as "the network device" that are
controlled by the network device driver.
TCP provides a reliable byte stream to the upper layer protocols. It
breaks the byte stream into appropriately sized segments and each
segment is sent in its own IP packet. The IP packets are sent out on
the network by the network device driver. If the destination is not on
the physically connected network, the IP packet is forwarded onto
another network by a router that is situated between the two
networks. If the maximum packet size of the other network is smaller
than the size of the IP packet, the packet is fragmented into smaller
packets by the router. If possible, the size of the TCP segments are
chosen so that fragmentation is minimized. The final recipient of the
packet will have to reassemble any fragmented IP packets before they
can be passed to higher layers.
The formal requirements for the protocols in the TCP/IP stack is
specified in a number of RFC documents published by the Internet
Engineering Task Force, IETF. Each of the protocols in the stack is
defined in one more RFC documents and RFC1122 collects
all requirements and updates the previous RFCs.
The RFC1122 requirements can be divided into two categories; those
that deal with the host to host communication and those that deal with
communication between the application and the networking stack. An
example of the first kind is "A TCP MUST be able to receive a TCP
option in any segment" and an example of the second kind is "There
MUST be a mechanism for reporting soft TCP error conditions to the
application." A TCP/IP implementation that violates requirements of
the first kind may not be able to communicate with other TCP/IP
implementations and may even lead to network failures. Violation of
the second kind of requirements will only affect the communication
within the system and will not affect host-to-host communication.
In uIP, all RFC requirements that affect host-to-host communication
are implemented. However, in order to reduce code size, we have
removed certain mechanisms in the interface between the application
and the stack, such as the soft error reporting mechanism and
dynamically configurable type-of-service bits for TCP
connections. Since there are only very few applications that make use
of those features they can be removed without loss of generality.
\section mainloop Main Control Loop
The uIP stack can be run either as a task in a multitasking system, or
as the main program in a singletasking system. In both cases, the main
control loop does two things repeatedly:
- Check if a packet has arrived from the network.
- Check if a periodic timeout has occurred.
If a packet has arrived, the input handler function, uip_input(),
should be invoked by the main control loop. The input handler function
will never block, but will return at once. When it returns, the stack
or the application for which the incoming packet was intended may have
produced one or more reply packets which should be sent out. If so,
the network device driver should be called to send out these packets.
Periodic timeouts are used to drive TCP mechanisms that depend on
timers, such as delayed acknowledgments, retransmissions and
round-trip time estimations. When the main control loop infers that
the periodic timer should fire, it should invoke the timer handler
function uip_periodic(). Because the TCP/IP stack may perform
retransmissions when dealing with a timer event, the network device
driver should called to send out the packets that may have been produced.
\section arch Architecture Specific Functions
uIP requires a few functions to be implemented specifically for the
architecture on which uIP is intended to run. These functions should
be hand-tuned for the particular architecture, but generic C
implementations are given as part of the uIP distribution.
\subsection checksums Checksum Calculation
The TCP and IP protocols implement a checksum that covers the data and
header portions of the TCP and IP packets. Since the calculation of
this checksum is made over all bytes in every packet being sent and
received it is important that the function that calculates the
checksum is efficient. Most often, this means that the checksum
calculation must be fine-tuned for the particular architecture on
which the uIP stack runs.
While uIP includes a generic checksum function, it also leaves it open
for an architecture specific implementation of the two functions
uip_ipchksum() and uip_tcpchksum(). The checksum calculation
评论3