uip/doc/uip-doc.txt

/**
\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 calculations in those
functions can be written in highly optimized assembler rather than
generic C code.

\subsection longarith 32-bit Arithmetic

The TCP protocol uses 32-bit sequence numbers, and a TCP
implementation will have to do a number of 32-bit additions as part of
the normal protocol processing. Since 32-bit arithmetic is not
natively available on many of the platforms for which uIP is intended,
uIP leaves the 32-bit additions to be implemented by the architecture
specific module and does not make use of any 32-bit arithmetic in the
main code base.

While uIP implements a generic 32-bit addition, there is support for
having an architecture specific implementation of the uip_add32()
function.


\section memory Memory Management

In the architectures for which uIP is intended, RAM is the most
scarce resource. With only a few kilobytes of RAM available for the
TCP/IP stack to use, mechanisms used in traditional TCP/IP cannot be
directly applied.


The uIP stack does not use explicit dynamic memory
allocation. Instead, it uses a single global buffer for holding
packets and has a fixed table for holding connection state. The global
packet buffer is large enough to contain one packet of maximum
size. When a packet arrives from the network, the device driver places
it in the global buffer and calls the TCP/IP stack. If the packet
contains data, the TCP/IP stack will notify the corresponding
application. Because the data in the buffer will be overwritten by the
next incoming packet, the application will either have to act
immediately on the data or copy the data into a secondary buffer for
later processing. The packet buffer will not be overwritten by new
packets before the application has processed the data. Packets that
arrive when the application is processing the data must be queued,
either by the network device or by the device driver. Most single-chip
Ethernet controllers have on-chip buffers that are large enough to
contain at least 4 maximum sized Ethernet frames. Devices that are
handled by the processor, such as RS-232 ports, can copy incoming
bytes to a separate buffer during application processing. If the
buffers are full, the incoming packet is dropped. This will cause
performance degradation, but only when multiple connections are
running in parallel. This is because uIP advertises a very small
receiver window, which means that only a single TCP segment will be in
the network per connection.

In uIP, the same global packet buffer that is used for incoming
packets is also used for the TCP/IP headers of outgoing data. If the
application sends dynamic data, it may use the parts of the global
packet buffer that are not used for headers as a temporary storage
buffer. To send the data, the application passes a pointer to the data
as well as the length of the data to the stack. The TCP/IP headers are
written into the global buffer and once the headers have been
produced, the device driver sends the headers and the application data
out on the network. The data is not queued for
retransmissions. Instead, the application will have to reproduce the
data if a retransmission is necessary.

The total amount of memory usage for uIP depends heavily on the
applications of the particular device in which the implementations are
to be run. The memory configuration determines both the amount of
traffic the system should be able to handle and the maximum amount of
simultaneous connections. A device that will be sending large e-mails
while at the same time running a web server with highly dynamic web
pages and multiple simultaneous clients, will require more RAM than a
simple Telnet server. It is possible to run the uIP implementation
with as little as 200 bytes of RAM, but such a configuration will
provide extremely low throughput and will only allow a small number of
simultaneous connections.

\section api Application Program Interface (API)


The Application Program Interface (API) defines the way the
application program interacts with the TCP/IP stack. The most commonly
used API for TCP/IP is the BSD socket API which is used in most Unix
systems and has heavily influenced the Microsoft Windows WinSock
API. Because the socket API uses stop-and-wait semantics, it requires
support from an underlying multitasking operating system. Since the
overhead of task management, context switching and allocation of stack
space for the tasks might be too high in the intended uIP target
architectures, the BSD socket interface is not suitable for our
purposes.

uIP provides two APIs to programmers: protosockets, a BSD socket-like
API without the overhead of full multi-threading, and a "raw"
event-based API that is nore low-level than protosockets but uses less
memory.

\sa \ref psock
\sa \ref pt


\subsection rawapi The uIP raw API

The "raw" uIP API uses an event driven interface where the application is
invoked in response to certain events. An application running on top
of uIP is implemented as a C function that is called by uIP in
response to certain events. uIP calls the application when data is
received, when data has been successfully delivered to the other end
of the connection, when a new connection has been set up, or when data
has to be retransmitted. The application is also periodically polled
for new data. The application program provides only one callback
function; it is up to the application to deal with mapping different
network services to different ports and connections. Because the
application is able to act on incoming data and connection requests as
soon as the TCP/IP stack receives the packet, low response times can
be achieved even in low-end systems.

uIP is different from other TCP/IP stacks in that it requires help
from the application when doing retransmissions. Other TCP/IP stacks
buffer the transmitted data in memory until the data is known to be
successfully delivered to the remote end of the connection. If the
data needs to be retransmitted, the stack takes care of the
retransmission without notifying the application. With this approach,
the data has to be buffered in memory while waiting for an
acknowledgment even if the application might be able to quickly
regenerate the data if a retransmission has to be made.

In order to reduce memory usage, uIP utilizes the fact that the
application may be able to regenerate sent data and lets the
application take part in retransmissions. uIP does not keep track of
packet contents after they have been sent by the device driver, and
uIP requires that the application takes an active part in performing
the retransmission. When uIP decides that a segment should be
retransmitted, it calls the application with a flag set indicating
that a retransmission is required. The application checks the
retransmission flag and produces the same data that was previously
sent. From the application's standpoint, performing a retransmission
is not different from how the data originally was sent. Therefore the
application can be written in such a way that the same code is used
both for sending data and retransmitting data. Also, it is important
to note that even though the actual retransmission operation is
carried out by the application, it is the responsibility of the stack
to know when the retransmission should be made. Thus the complexity of
the application does not necessarily increase because it takes an
active part in doing retransmissions.

\subsubsection appevents Application Events

The application must be implemented as a C function, UIP_APPCALL(),
that uIP calls whenever an event occurs. Each event has a corresponding
test function that is used to distinguish between different
events. The functions are implemented as C macros that will evaluate
to either zero or non-zero. Note that certain events can happen in
conjunction with each other (i.e., new data can arrive at the same
time as data is acknowledged).

\subsubsection connstate The Connection Pointer

When the application is called by uIP, the global variable uip_conn is
set to point to the uip_conn structure for the connection that
currently is handled, and is called the "current connection". The
fields in the uip_conn structure for the current connection can be
used, e.g., to distinguish between different services, or to check to
which IP address the connection is connected. One typical use would be
to inspect the uip_conn->lport (the local TCP port number) to decide
which service the connection should provide. For instance, an
application might decide to act as an HTTP server if the value of
uip_conn->lport is equal to 80 and act as a TELNET server if the value
is 23.

\subsubsection recvdata Receiving Data

If the uIP test function uip_newdata() is non-zero, the remote host of
the connection has sent new data. The uip_appdata pointer point to the
actual data. The size of the data is obtained through the uIP function
uip_datalen(). The data is not buffered by uIP, but will be
overwritten after the application function returns, and the
application will therefor have to either act directly on the incoming
data, or by itself copy the incoming data into a buffer for later
processing.

\subsubsection senddata Sending Data

When sending data, uIP adjusts the length of the data sent by the
application according to the available buffer space and the current
TCP window advertised by the receiver. The amount of buffer space is
dictated by the memory configuration. It is therefore possible that
all data sent from the application does not arrive at the receiver,
and the application may use the uip_mss() function to see how much
data that actually will be sent by the stack.

The application sends data by using the uIP function uip_send(). The
uip_send() function takes two arguments; a pointer to the data to be
sent and the length of the data. If the application needs RAM space
for producing the actual data that should be sent, the packet buffer
(pointed to by the uip_appdata pointer) can be used for this purpose.

The application can send only one chunk of data at a time on a
connection and it is not possible to call uip_send() more than once
per application invocation; only the data from the last call will be
sent.

\subsubsection rexmitdata Retransmitting Data

Retransmissions are driven by the periodic TCP timer. Every time the
periodic timer is invoked, the retransmission timer for each
connection is decremented. If the timer reaches zero, a retransmission
should be made. As uIP does not keep track of packet contents after they have
been sent by the device driver, uIP requires that the
application takes an active part in performing the
retransmission. When uIP decides that a segment should be
retransmitted, the application function is called with the
uip_rexmit() flag set, indicating that a retransmission is
required.

The application must check the uip_rexmit() flag and produce the same
data that was previously sent. From the application's standpoint,
performing a retransmission is not different from how the data
originally was sent. Therefor, the application can be written in such
a way that the same code is used both for sending data and
retransmitting data. Also, it is important to note that even though
the actual retransmission operation is carried out by the application,
it is the responsibility of the stack to know when the retransmission
should be made. Thus the complexity of the application does not
necessarily increase because it takes an active part in doing
retransmissions.

\subsubsection closing Closing Connections

The application closes the current connection by calling the
uip_close() during an application call. This will cause the connection
to be cleanly closed. In order to indicate a fatal error, the
application might want to abort the connection and does so by calling
the uip_abort() function.

If the connection has been closed by the remote end, the test function
uip_closed() is true. The application may then do any necessary
cleanups.

\subsubsection errors Reporting Errors

There are two fatal errors that can happen to a connection, either
that the connection was aborted by the remote host, or that the
connection retransmitted the last data too many times and has been
aborted. uIP reports this by calling the application function. The
application can use the two test functions uip_aborted() and
uip_timedout() to test for those error conditions.

\subsubsection polling Polling

When a connection is idle, uIP polls the application every time the
periodic timer fires. The application uses the test function
uip_poll() to check if it is being polled by uIP.

The polling event has two purposes. The first is to let the
application periodically know that a connection is idle, which allows
the application to close connections that have been idle for too
long. The other purpose is to let the application send new data that
has been produced. The application can only send data when invoked by
uIP, and therefore the poll event is the only way to send data on an
otherwise idle connection.

\subsubsection listen Listening Ports

uIP maintains a list of listening TCP ports. A new port is opened for
listening with the uip_listen() function. When a connection request
arrives on a listening port, uIP creates a new connection and calls
the application function. The test function uip_connected() is true if
the application was invoked because a new connection was created.

The application can check the lport field in the uip_conn structure to
check to which port the new connection was connected.

\subsubsection connect Opening Connections

New connections can be opened from within
uIP by the function uip_connect(). This function
allocates a new connection and sets a flag in the connection state
which will open a TCP connection to the specified IP address and port
the next time the connection is polled by uIP. The uip_connect()
function returns
a pointer to the uip_conn structure for the new
connection. If there are no free connection slots, the function
returns NULL.

The function uip_ipaddr() may be used to pack an IP address into the
two element 16-bit array used by uIP to represent IP addresses.

Two examples of usage are shown below. The first example shows how to
open a connection to TCP port 8080 of the remote end of the current
connection. If there are not enough TCP connection slots to allow a
new connection to be opened, the uip_connect() function returns NULL
and the current connection is aborted by uip_abort().

\code
void connect_example1_app(void) {
   if(uip_connect(uip_conn->ripaddr, HTONS(8080)) == NULL) {
      uip_abort();
   }
}
\endcode

The second example shows how to open a new connection to a specific IP
address. No error checks are made in this example.

\code
void connect_example2(void) {
   u16_t ipaddr[2];

   uip_ipaddr(ipaddr, 192,168,0,1);
   uip_connect(ipaddr, HTONS(8080));
}
\endcode

\section examples Examples

This section presents a number of very simple uIP applications. The
uIP code distribution contains several more complex applications.

\subsection example1 A Very Simple Application

This first example shows a very simple application. The application
listens for incoming connections on port 1234. When a connection has
been established, the application replies to all data sent to it by
saying "ok"

The implementation of this application is shown below. The application
is initialized with the function called example1_init() and the uIP
callback function is called example1_app(). For this application, the
configuration variable UIP_APPCALL should be defined to be
example1_app().

\code
void example1_init(void) {
   uip_listen(HTONS(1234));
}

void example1_app(void) {
   if(uip_newdata() || uip_rexmit()) {
      uip_send("ok\n", 3);
   }
}
\endcode

The initialization function calls the uIP function uip_listen() to
register a listening port. The actual application function
example1_app() uses the test functions uip_newdata() and uip_rexmit()
to determine why it was called. If the application was called because
the remote end has sent it data, it responds with an "ok". If the
application function was called because data was lost in the network
and has to be retransmitted, it also sends an "ok".  Note that this
example actually shows a complete uIP application. It is not required
for an application to deal with all types of events such as
uip_connected() or uip_timedout().

\subsection example2 A More Advanced Application

This second example is slightly more advanced than the previous one,
and shows how the application state field in the uip_conn structure is
used.

This application is similar to the first application in that it
listens to a port for incoming connections and responds to data sent
to it with a single "ok". The big difference is that this application
prints out a welcoming "Welcome!" message when the connection has been
established.

This seemingly small change of operation makes a big difference in how
the application is implemented. The reason for the increase in
complexity is that if data should be lost in the network, the
application must know what data to retransmit. If the "Welcome!"
message was lost, the application must retransmit the welcome and if
one of the "ok" messages is lost, the application must send a new
"ok".

The application knows that as long as the "Welcome!" message has not
been acknowledged by the remote host, it might have been dropped in
the network. But once the remote host has sent an acknowledgment
back, the application can be sure that the welcome has been received
and knows that any lost data must be an "ok" message. Thus the
application can be in either of two states: either in the WELCOME-SENT
state where the "Welcome!" has been sent but not acknowledged, or in
the WELCOME-ACKED state where the "Welcome!" has been acknowledged.

When a remote host connects to the application, the application sends
the "Welcome!" message and sets it's state to WELCOME-SENT. When the
welcome message is acknowledged, the application moves to the
WELCOME-ACKED state. If the application receives any new data from the
remote host, it responds by sending an "ok" back.

If the application is requested to retransmit the last message, it
looks at in which state the application is. If the application is in
the WELCOME-SENT state, it sends a "Welcome!"  message since it
knows that the previous welcome message hasn't been acknowledged. If
the application is in the WELCOME-ACKED state, it knows that the last
message was an "ok" message and sends such a message.

The implementation of this application is seen below. This
configuration settings for the application is follows after its
implementation.

\code
struct example2_state {
   enum {WELCOME_SENT, WELCOME_ACKED} state;
};

void example2_init(void) {
   uip_listen(HTONS(2345));
}

void example2_app(void) {
   struct example2_state *s;

   s = (struct example2_state *)uip_conn->appstate;

   if(uip_connected()) {
      s->state = WELCOME_SENT;
      uip_send("Welcome!\n", 9);
      return;
   }

   if(uip_acked() && s->state == WELCOME_SENT) {
      s->state = WELCOME_ACKED;
   }

   if(uip_newdata()) {
      uip_send("ok\n", 3);
   }

   if(uip_rexmit()) {
      switch(s->state) {
      case WELCOME_SENT:
         uip_send("Welcome!\n", 9);
         break;
      case WELCOME_ACKED:
         uip_send("ok\n", 3);
         break;
      }
   }
}
\endcode

The configuration for the application:

\code
#define UIP_APPCALL       example2_app
#define UIP_APPSTATE_SIZE sizeof(struct example2_state)
\endcode

\subsection example3 Differentiating Between Applications

If the system should run multiple applications, one technique to
differentiate between them is to use the TCP port number of either the
remote end or the local end of the connection. The example below shows
how the two examples above can be combined into one application.

\code
void example3_init(void) {
   example1_init();
   example2_init();
}

void example3_app(void) {
   switch(uip_conn->lport) {
   case HTONS(1234):
      example1_app();
      break;
   case HTONS(2345):
      example2_app();
      break;
   }
}
\endcode

\subsection example4 Utilizing TCP Flow Control

This example shows a simple application that connects to a host, sends
an HTTP request for a file and downloads it to a slow device such a
disk drive. This shows how to use the flow control functions of uIP.

\code
void example4_init(void) {
   u16_t ipaddr[2];
   uip_ipaddr(ipaddr, 192,168,0,1);
   uip_connect(ipaddr, HTONS(80));
}

void example4_app(void) {
   if(uip_connected() || uip_rexmit()) {
      uip_send("GET /file HTTP/1.0\r\nServer:192.186.0.1\r\n\r\n",
               48);
      return;
   }

   if(uip_newdata()) {
      device_enqueue(uip_appdata, uip_datalen());
      if(device_queue_full()) {
         uip_stop();
      }
   }

   if(uip_poll() && uip_stopped()) {
      if(!device_queue_full()) {
         uip_restart();
      }
   }
}
\endcode

When the connection has been established, an HTTP request is sent to
the server. Since this is the only data that is sent, the application
knows that if it needs to retransmit any data, it is that request that
should be retransmitted. It is therefore possible to combine these two
events as is done in the example.

When the application receives new data from the remote host, it sends
this data to the device by using the function device_enqueue(). It is
important to note that this example assumes that this function copies
the data into its own buffers. The data in the uip_appdata buffer will
be overwritten by the next incoming packet.

If the device's queue is full, the application stops the data from the
remote host by calling the uIP function uip_stop(). The application
can then be sure that it will not receive any new data until
uip_restart() is called. The application polling event is used to
check if the device's queue is no longer full and if so, the data flow
is restarted with uip_restart().

\subsection example5 A Simple Web Server

This example shows a very simple file server application that listens
to two ports and uses the port number to determine which file to
send. If the files are properly formatted, this simple application can
be used as a web server with static pages. The implementation follows.

\code
struct example5_state {
   char *dataptr;
   unsigned int dataleft;
};

void example5_init(void) {
   uip_listen(HTONS(80));
   uip_listen(HTONS(81));
}

void example5_app(void) {
   struct example5_state *s;
   s = (struct example5_state)uip_conn->appstate;

   if(uip_connected()) {
      switch(uip_conn->lport) {
      case HTONS(80):
         s->dataptr = data_port_80;
         s->dataleft = datalen_port_80;
         break;
      case HTONS(81):
         s->dataptr = data_port_81;
         s->dataleft = datalen_port_81;
         break;
      }
      uip_send(s->dataptr, s->dataleft);
      return;
   }

   if(uip_acked()) {
      if(s->dataleft < uip_mss()) {
         uip_close();
         return;
      }
      s->dataptr += uip_conn->len;
      s->dataleft -= uip_conn->len;
      uip_send(s->dataptr, s->dataleft);
   }
}
\endcode

The application state consists of a pointer to the data that should be
sent and the size of the data that is left to send. When a remote host
connects to the application, the local port number is used to
determine which file to send. The first chunk of data is sent using
uip_send(). uIP makes sure that no more than MSS bytes of data is
actually sent, even though s->dataleft may be larger than the MSS.

The application is driven by incoming acknowledgments. When data has
been acknowledged, new data can be sent. If there is no more data to
send, the connection is closed using uip_close().

\subsection example6 Structured Application Program Design

When writing larger programs using uIP it is useful to be able to
utilize the uIP API in a structured way. The following example
provides a structured design that has showed itself to be useful for
writing larger protocol implementations than the previous examples
showed here. The program is divided into an uIP event handler function
that calls seven application handler functions that process new data,
act on acknowledged data, send new data, deal with connection
establishment or closure events and handle errors. The functions are
called newdata(), acked(), senddata(), connected(), closed(),
aborted(), and timedout(), and needs to be written specifically for
the protocol that is being implemented.

The uIP event handler function is shown below.

\code
void example6_app(void) {
  if(uip_aborted()) {
    aborted();
  }
  if(uip_timedout()) {
    timedout();
  }
  if(uip_closed()) {
    closed();
  }
  if(uip_connected()) {
    connected();
  }
  if(uip_acked()) {
    acked();
  }
  if(uip_newdata()) {
    newdata();
  }
  if(uip_rexmit() ||
     uip_newdata() ||
     uip_acked() ||
     uip_connected() ||
     uip_poll()) {
    senddata();
  }
}
\endcode

The function starts with dealing with any error conditions that might
have happened by checking if uip_aborted() or uip_timedout() are
true. If so, the appropriate error function is called. Also, if the
connection has been closed, the closed() function is called to the it
deal with the event.

Next, the function checks if the connection has just been established
by checking if uip_connected() is true. The connected() function is
called and is supposed to do whatever needs to be done when the
connection is established, such as intializing the application state
for the connection. Since it may be the case that data should be sent
out, the senddata() function is called to deal with the outgoing data.

The following very simple application serves as an example of how the
application handler functions might look. This application simply
waits for any data to arrive on the connection, and responds to the
data by sending out the message "Hello world!". To illustrate how to
develop an application state machine, this message is sent in two
parts, first the "Hello" part and then the "world!" part.

\code
#define STATE_WAITING 0
#define STATE_HELLO   1
#define STATE_WORLD   2

struct example6_state {
  u8_t state;
  char *textptr;
  int  textlen;
};

static void aborted(void) {}
static void timedout(void) {}
static void closed(void) {}

static void connected(void) {
  struct example6_state *s = (struct example6_state *)uip_conn->appstate;

  s->state   = STATE_WAITING;
  s->textlen = 0;
}

static void newdata(void) {
  struct example6_state *s = (struct example6_state *)uip_conn->appstate;

  if(s->state == STATE_WAITING) {
    s->state   = STATE_HELLO;
    s->textptr = "Hello ";
    s->textlen = 6;
  }
}

static void acked(void) {
  struct example6_state *s = (struct example6_state *)uip_conn->appstate;

  s->textlen -= uip_conn->len;
  s->textptr += uip_conn->len;
  if(s->textlen == 0) {
    switch(s->state) {
    case STATE_HELLO:
      s->state   = STATE_WORLD;
      s->textptr = "world!\n";
      s->textlen = 7;
      break;
    case STATE_WORLD:
      uip_close();
      break;
    }
  }
}

static void senddata(void) {
  struct example6_state *s = (struct example6_state *)uip_conn->appstate;

  if(s->textlen > 0) {
    uip_send(s->textptr, s->textlen);
  }
}
\endcode

The application state consists of a "state" variable, a "textptr"
pointer to a text message and the "textlen" length of the text
message. The "state" variable can be either "STATE_WAITING", meaning
that the application is waiting for data to arrive from the network,
"STATE_HELLO", in which the application is sending the "Hello" part of
the message, or "STATE_WORLD", in which the application is sending the
"world!" message.

The application does not handle errors or connection closing events,
and therefore the aborted(), timedout() and closed() functions are
implemented as empty functions.

The connected() function will be called when a connection has been
established, and in this case sets the "state" variable to be
"STATE_WAITING" and the "textlen" variable to be zero, indicating that
there is no message to be sent out.

When new data arrives from the network, the newdata() function will be
called by the event handler function. The newdata() function will
check if the connection is in the "STATE_WAITING" state, and if so
switches to the "STATE_HELLO" state and registers a 6 byte long "Hello
" message with the connection. This message will later be sent out by
the senddata() function.

The acked() function is called whenever data that previously was sent
has been acknowleged by the receiving host. This acked() function
first reduces the amount of data that is left to send, by subtracting
the length of the previously sent data (obtained from "uip_conn->len")
from the "textlen" variable, and also adjusts the "textptr" pointer
accordingly. It then checks if the "textlen" variable now is zero,
which indicates that all data now has been successfully received, and
if so changes application state. If the application was in the
"STATE_HELLO" state, it switches state to "STATE_WORLD" and sets up a
7 byte "world!\n" message to be sent. If the application was in the
"STATE_WORLD" state, it closes the connection.

Finally, the senddata() function takes care of actually sending the
data that is to be sent. It is called by the event handler function
when new data has been received, when data has been acknowledged, when
a new connection has been established, when the connection is polled
because of inactivity, or when a retransmission should be made. The
purpose of the senddata() function is to optionally format the data
that is to be sent, and to call the uip_send() function to actually
send out the data. In this particular example, the function simply
calls uip_send() with the appropriate arguments if data is to be sent,
after checking if data should be sent out or not as indicated by the
"textlen" variable.

It is important to note that the senddata() function never should
affect the application state; this should only be done in the acked()
and newdata() functions.

\section protoimpl Protocol Implementations

The protocols in the TCP/IP protocol suite are designed in a layered
fashion where each protocol performs a specific function and the
interactions between the protocol layers are strictly defined. While
the layered approach is a good way to design protocols, it is not
always the best way to implement them. In uIP, the protocol
implementations are tightly coupled in order to save code space.

This section gives detailed information on the specific protocol
implementations in uIP.

\subsection ip IP --- Internet Protocol

When incoming packets are processed by uIP, the IP layer is the first
protocol that examines the packet. The IP layer does a few simple
checks such as if the destination IP address of the incoming packet
matches any of the local IP address and verifies the IP header
checksum. Since there are no IP options that are strictly required and
because they are very uncommon, any IP options in received packets are
dropped.

\subsubsection ipreass IP Fragment Reassembly

IP fragment reassembly is implemented using a separate buffer that
holds the packet to be reassembled. An incoming fragment is copied
into the right place in the buffer and a bit map is used to keep track
of which fragments have been received. Because the first byte of an IP
fragment is aligned on an 8-byte boundary, the bit map requires a
small amount of memory. When all fragments have been reassembled, the
resulting IP packet is passed to the transport layer. If all fragments
have not been received within a specified time frame, the packet is
dropped.

The current implementation only has a single buffer for holding
packets to be reassembled, and therefore does not support simultaneous
reassembly of more than one packet. Since fragmented packets are
uncommon, this ought to be a reasonable decision. Extending the
implementation to support multiple buffers would be straightforward,
however.

\subsubsection ipbroadcast Broadcasts and Multicasts

IP has the ability to broadcast and multicast packets on the local
network. Such packets are addressed to special broadcast and multicast
addresses. Broadcast is used heavily in many UDP based protocols such
as the Microsoft Windows file-sharing SMB protocol. Multicast is
primarily used in protocols used for multimedia distribution such as
RTP. TCP is a point-to-point protocol and does not use broadcast or
multicast packets. uIP current supports broadcast packets as well as
sending multicast packets. Joining multicast groups (IGMP) and
receiving non-local multicast packets is not currently supported.

\subsection icmp ICMP --- Internet Control Message Protocol

The ICMP protocol is used for reporting soft error conditions and for
querying host parameters. Its main use is, however, the echo mechanism
which is used by the "ping" program.

The ICMP implementation in uIP is very simple as itis restricted to
only implement ICMP echo messages. Replies to echo messages are
constructed by simply swapping the source and destination IP addresses
of incoming echo requests and rewriting the ICMP header with the
Echo-Reply message type. The ICMP checksum is adjusted using standard
techniques (see RFC1624).

Since only the ICMP echo message is implemented, there is no support
for Path MTU discovery or ICMP redirect messages. Neither of these is
strictly required for interoperability; they are performance
enhancement mechanisms.

\subsection tcp TCP --- Transmission Control Protocol

The TCP implementation in uIP is driven by incoming packets and timer
events. Incoming packets are parsed by TCP and if the packet contains
data that is to be delivered to the application, the application is
invoked by the means of the application function call. If the incoming
packet acknowledges previously sent data, the connection state is
updated and the application is informed, allowing it to send out new
data.

\subsubsection listeb Listening Connections

TCP allows a connection to listen for incoming connection requests. In
uIP, a listening connection is identified by the 16-bit port number
and incoming connection requests are checked against the list of
listening connections. This list of listening connections is dynamic
and can be altered by the applications in the system.

\subsubsection slidingwindow Sliding Window

Most TCP implementations use a sliding window mechanism for sending
data. Multiple data segments are sent in succession without waiting
for an acknowledgment for each segment.

The sliding window algorithm uses a lot of 32-bit operations and
because 32-bit arithmetic is fairly expensive on most 8-bit CPUs, uIP
does not implement it. Also, uIP does not buffer sent packets and a
sliding window implementation that does not buffer sent packets will have
to be supported by a complex application layer. Instead, uIP allows
only a single TCP segment per connection to be unacknowledged at any
given time.

It is important to note that even though most TCP implementations use
the sliding window algorithm, it is not required by the TCP
specifications. Removing the sliding window mechanism does not affect
interoperability in any way.

\subsubsection rttest Round-Trip Time Estimation

TCP continuously estimates the current Round-Trip Time (RTT) of every
active connection in order to find a suitable value for the
retransmission time-out.

The RTT estimation in uIP is implemented using TCP's periodic
timer. Each time the periodic timer fires, it increments a counter for
each connection that has unacknowledged data in the network. When an
acknowledgment is received, the current value of the counter is used
as a sample of the RTT. The sample is used together with Van
Jacobson's standard TCP RTT estimation function to calculate an
estimate of the RTT. Karn's algorithm is used to ensure that
retransmissions do not skew the estimates.

\subsubsection rexmit Retransmissions

Retransmissions are driven by the periodic TCP timer. Every time the
periodic timer is invoked, the retransmission timer for each
connection is decremented. If the timer reaches zero, a retransmission
should be made.

As uIP does not keep track of packet contents after they have
been sent by the device driver, uIP requires that the
application takes an active part in performing the
retransmission. When uIP decides that a segment should be
retransmitted, it calls the application with a flag set indicating
that a retransmission is required. The application checks the
retransmission flag and produces the same data that was previously
sent. From the application's standpoint, performing a retransmission
is not different from how the data originally was sent. Therefore the
application can be written in such a way that the same code is used
both for sending data and retransmitting data. Also, it is important
to note that even though the actual retransmission operation is
carried out by the application, it is the responsibility of the stack
to know when the retransmission should be made. Thus the complexity of
the application does not necessarily increase because it takes an
active part in doing retransmissions.

\subsubsection flowcontrol Flow Control

The purpose of TCP's flow control mechanisms is to allow communication
between hosts with wildly varying memory dimensions. In each TCP
segment, the sender of the segment indicates its available buffer
space. A TCP sender must not send more data than the buffer space
indicated by the receiver.

In uIP, the application cannot send more data than the receiving host
can buffer. And application cannot send more data than the amount of
bytes it is allowed to send by the receiving host. If the remote host
cannot accept any data at all, the stack initiates the zero window
probing mechanism.

\subsubsection congestioncontrol Congestion Control

The congestion control mechanisms limit the number of simultaneous TCP
segments in the network. The algorithms used for congestion control
are designed to be simple to implement and require only a few lines of
code.

Since uIP only handles one in-flight TCP segment per connection,
the amount of simultaneous segments cannot be further limited, thus
the congestion control mechanisms are not needed.

\subsubsection urgdata Urgent Data

TCP's urgent data mechanism provides an application-to-application
notification mechanism, which can be used by an application to mark
parts of the data stream as being more urgent than the normal
stream. It is up to the receiving application to interpret the meaning
of the urgent data.

In many TCP implementations, including the BSD implementation, the
urgent data feature increases the complexity of the implementation
because it requires an asynchronous notification mechanism in an
otherwise synchronous API. As uIP already use an asynchronous event
based API, the implementation of the urgent data feature does not lead
to increased complexity.

\section performance Performance

In TCP/IP implementations for high-end systems, processing time is
dominated by the checksum calculation loop, the operation of copying
packet data and context switching. Operating systems for high-end
systems often have multiple protection domains for protecting kernel
data from user processes and user processes from each other. Because
the TCP/IP stack is run in the kernel, data has to be copied between
the kernel space and the address space of the user processes and a
context switch has to be performed once the data has been
copied. Performance can be enhanced by combining the copy operation
with the checksum calculation. Because high-end systems usually have
numerous active connections, packet demultiplexing is also an
expensive operation.

A small embedded device does not have the necessary processing power
to have multiple protection domains and the power to run a
multitasking operating system. Therefore there is no need to copy
data between the TCP/IP stack and the application program. With an
event based API there is no context switch between the TCP/IP stack
and the applications.

In such limited systems, the TCP/IP processing overhead is dominated
by the copying of packet data from the network device to host memory,
and checksum calculation. Apart from the checksum calculation and
copying, the TCP processing done for an incoming packet involves only
updating a few counters and flags before handing the data over to the
application. Thus an estimate of the CPU overhead of our TCP/IP
implementations can be obtained by calculating the amount of CPU
cycles needed for the checksum calculation and copying of a maximum
sized packet.

\subsection delack The Impact of Delayed Acknowledgments

Most TCP receivers implement the delayed acknowledgment algorithm for
reducing the number of pure acknowledgment packets sent. A TCP
receiver using this algorithm will only send acknowledgments for every
other received segment. If no segment is received within a specific
time-frame, an acknowledgment is sent. The time-frame can be as high
as 500 ms but typically is 200 ms.

A TCP sender such as uIP that only handles a single outstanding TCP
segment will interact poorly with the delayed acknowledgment
algorithm. Because the receiver only receives a single segment at a
time, it will wait as much as 500 ms before an acknowledgment is
sent. This means that the maximum possible throughput is severely
limited by the 500 ms idle time.

Thus the maximum throughput equation when sending data from uIP will
be $p = s / (t + t_d)$ where $s$ is the segment size and $t_d$ is the
delayed acknowledgment timeout, which typically is between 200 and
500 ms. With a segment size of 1000 bytes, a round-trip time of 40 ms
and a delayed acknowledgment timeout of 200 ms, the maximum
throughput will be 4166 bytes per second. With the delayed acknowledgment
algorithm disabled at the receiver, the maximum throughput would be
25000 bytes per second.

It should be noted, however, that since small systems running uIP are
not very likely to have large amounts of data to send, the delayed
acknowledgmen t throughput degradation of uIP need not be very
severe. Small amounts of data sent by such a system will not span more
than a single TCP segment, and would therefore not be affected by the
throughput degradation anyway.

The maximum throughput when uIP acts as a receiver is not affected by
the delayed acknowledgment throughput degradation.


*/


/** @} */