uip-doc.txt

uIP0.9版本

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.

\subsection 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.

\subsection 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.

\subsection 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.

\subsection 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 drivers uIP device drivers

From the network device driver's standpoint, uIP consists of two C
functions: uip_input() and uip_periodic(). The uip_input() function
should be called by the device driver when an IP packet has been
received and put into the uip_buf packet buffer. The uip_input()
function will process the packet, and when it returns an outbound
packet may have been placed in the same uip_buf packet buffer
(indicated by the uip_len variable being non-zero). The device driver
should then send out this packet onto the network.

The uip_periodic() function should be invoked periodically once per
connection by the device driver, typically one per second. This
function is used by uIP to drive protocol timers and retransmissions,
and when it returns it may have placed an outbound packet in the
uip_buf buffer.

\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.

Because of this, uIP does not implement a generic checksum function,
but leaves this to the architecture specific files which must
implement 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.

An example C implementation of the checksum function is provided in
the uIP distribution.

\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.

The architecture specific code must implement a function uip_add32()
which does a 32-bit addition and stores the result in a global
variable uip_acc32. 

\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.