# The uIP TCP/IP stack

## Detailed Description

uIP is an implementation of the TCP/IP protocol stack intended for small 8-bit and 16-bit microcontrollers.

uIP provides the necessary protocols for Internet communication, with a very small code footprint and RAM requirements - the uIP code size is on the order of a few kilobytes and RAM usage is on the order of a few hundred bytes.

## Files

file | uip.h
| Header file for the uIP TCP/IP stack.

file | uip.c
| The uIP TCP/IP stack code.

## Modules

| uIP configuration functions
| The uIP configuration functions are used for setting run-time parameters in uIP such as IP addresses.

| uIP initialization functions
| The uIP initialization functions are used for booting uIP.

| uIP device driver functions
| These functions are used by a network device driver for interacting with uIP.

| uIP application functions
| Functions used by an application running of top of uIP.

| uIP conversion functions
| These functions can be used for converting between different data formats used by uIP.

| Variables used in uIP device drivers
| uIP has a few global variables that are used in device drivers for uIP.

| uIP Address Resolution Protocol
| The Address Resolution Protocol ARP is used for mapping between IP addresses and link level addresses such as the Ethernet MAC addresses.

| uIP TCP throughput booster hack
| The basic uIP TCP implementation only allows each TCP connection to have a single TCP segment in flight at any given time.

| Architecture specific uIP functions
| The functions in the architecture specific module implement the IP check sum and 32-bit additions.

## Data Structures

struct | uip_conn
| Representation of a uIP TCP connection. More...
struct | uip_udp_conn
| Representation of a uIP UDP connection. More...
struct | uip_stats
| The structure holding the TCP/IP statistics that are gathered if UIP_STATISTICS is set to 1. More...
struct | uip_tcpip_hdr
struct | uip_icmpip_hdr
struct | uip_udpip_hdr
struct | uip_eth_addr
| Representation of a 48-bit Ethernet address. More...

## Defines

#define | UIP_ACKDATA 1
#define | UIP_NEWDATA 2
#define | UIP_REXMIT 4
#define | UIP_POLL 8
#define | UIP_CLOSE 16
#define | UIP_ABORT 32
#define | UIP_CONNECTED 64
#define | UIP_TIMEDOUT 128
#define | UIP_DATA 1
#define | UIP_TIMER 2
#define | UIP_POLL_REQUEST 3
#define | UIP_UDP_SEND_CONN 4
#define | UIP_UDP_TIMER 5
#define | UIP_CLOSED 0
#define | UIP_SYN_RCVD 1
#define | UIP_SYN_SENT 2
#define | UIP_ESTABLISHED 3
#define | UIP_FIN_WAIT_1 4
#define | UIP_FIN_WAIT_2 5
#define | UIP_CLOSING 6
#define | UIP_TIME_WAIT 7
#define | UIP_LAST_ACK 8
#define | UIP_TS_MASK 15
#define | UIP_STOPPED 16
#define | UIP_APPDATA_SIZE
| The buffer size available for user data in the uip_buf buffer.
#define | UIP_PROTO_ICMP 1
#define | UIP_PROTO_TCP 6
#define | UIP_PROTO_UDP 17
#define | UIP_PROTO_ICMP6 58
#define | UIP_IPH_LEN 20
#define | UIP_UDPH_LEN 8
#define | UIP_TCPH_LEN 20
#define | UIP_IPUDPH_LEN (UIP_UDPH_LEN + UIP_IPH_LEN)
#define | UIP_IPTCPH_LEN (UIP_TCPH_LEN + UIP_IPH_LEN)
#define | UIP_TCPIP_HLEN UIP_IPTCPH_LEN
#define | TCP_FIN 0x01
#define | TCP_SYN 0x02
#define | TCP_RST 0x04
#define | TCP_PSH 0x08
#define | TCP_ACK 0x10
#define | TCP_URG 0x20
#define | TCP_CTL 0x3f
#define | TCP_OPT_END 0
#define | TCP_OPT_NOOP 1
#define | TCP_OPT_MSS 2
#define | TCP_OPT_MSS_LEN 4
#define | ICMP_ECHO_REPLY 0
#define | ICMP_ECHO 8
#define | ICMP6_ECHO_REPLY 129
#define | ICMP6_ECHO 128
#define | ICMP6_NEIGHBOR_SOLICITATION 135
#define | ICMP6_NEIGHBOR_ADVERTISEMENT 136
#define | ICMP6_FLAG_S (1 << 6)
#define | ICMP6_OPTION_SOURCE_LINK_ADDRESS 1
#define | ICMP6_OPTION_TARGET_LINK_ADDRESS 2
#define | BUF ((struct uip_tcpip_hdr *)&uip_buf[UIP_LLH_LEN])
#define | FBUF ((struct uip_tcpip_hdr *)&uip_reassbuf[0])
#define | ICMPBUF ((struct uip_icmpip_hdr *)&uip_buf[UIP_LLH_LEN])
#define | UDPBUF ((struct uip_udpip_hdr *)&uip_buf[UIP_LLH_LEN])
#define | UIP_STAT(s)
#define | UIP_LOG(m)

## Typedefs

typedef u16_t | uip_ip4addr_t [2]
| Repressentation of an IP address.
typedef u16_t | uip_ip6addr_t [8]
typedef uip_ip4addr_t | uip_ipaddr_t

## Functions

void | uip_process (u8_t flag)
u16_t | uip_chksum (u16_t *buf, u16_t len)
| Calculate the Internet checksum over a buffer.
u16_t | uip_ipchksum (void)
| Calculate the IP header checksum of the packet header in uip_buf.
u16_t | uip_tcpchksum (void)
| Calculate the TCP checksum of the packet in uip_buf and uip_appdata.
u16_t | uip_udpchksum (void)
| Calculate the UDP checksum of the packet in uip_buf and uip_appdata.
void | uip_setipid (u16_t id)
| uIP initialization function.
void | uip_add32 (u8_t *op32, u16_t op16)
| Carry out a 32-bit addition.
void | uip_init (void)
| uIP initialization function.
uip_conn * | uip_connect (uip_ipaddr_t *ripaddr, u16_t rport)
| Connect to a remote host using TCP.
uip_udp_conn * | uip_udp_new (uip_ipaddr_t *ripaddr, u16_t rport)
| Set up a new UDP connection.
void | uip_unlisten (u16_t port)
| Stop listening to the specified port.
void | uip_listen (u16_t port)
| Start listening to the specified port.
u16_t | htons (u16_t val)
| Convert 16-bit quantity from host byte order to network byte order.
void | uip_send (const void *data, int len)
| Send data on the current connection.

## Variables

void * | uip_appdata
| Pointer to the application data in the packet buffer.
uip_conn * | uip_conn
| Pointer to the current TCP connection.
uip_conn | uip_conns [UIP_CONNS]
uip_udp_conn * | uip_udp_conn
| The current UDP connection.
uip_udp_conn | uip_udp_conns [UIP_UDP_CONNS]
uip_stats | uip_stat
| The uIP TCP/IP statistics.
u8_t | uip_flags
uip_ipaddr_t | uip_hostaddr
uip_ipaddr_t | uip_netmask
uip_ipaddr_t | uip_draddr
uip_ipaddr_t | uip_hostaddr
uip_ipaddr_t | uip_draddr
uip_ipaddr_t | uip_netmask
uip_eth_addr | uip_ethaddr = {{0,0,0,0,0,0}}
u8_t | uip_buf [UIP_BUFSIZE+2]
| The uIP packet buffer.
void * | uip_appdata
| Pointer to the application data in the packet buffer.
void * | uip_sappdata
u16_t | uip_len
| The length of the packet in the uip_buf buffer.
u16_t | uip_slen
u8_t | uip_flags
uip_conn * | uip_conn
| Pointer to the current TCP connection.
uip_conn | uip_conns [UIP_CONNS]
u16_t | uip_listenports [UIP_LISTENPORTS]
uip_udp_conn * | uip_udp_conn
| The current UDP connection.
uip_udp_conn | uip_udp_conns [UIP_UDP_CONNS]
u8_t | uip_acc32 [4]
| 4-byte array used for the 32-bit sequence number calculations.

## Define Documentation

#define UIP_APPDATA_SIZE

The buffer size available for user data in the uip_buf buffer.

This macro holds the available size for user data in the uip_buf buffer. The macro is intended to be used for checking bounds of available user data.

Example:

     snprintf(uip_appdata, UIP_APPDATA_SIZE, "%u\n", i);

Definition at line 1506 of file uip.h.

## Function Documentation

u16_t htons | ( | u16_t | val | ) |

Convert 16-bit quantity from host byte order to network byte order.

This function is primarily used for converting variables from host byte order to network byte order. For converting constants to network byte order, use the HTONS() macro instead.

Definition at line 1882 of file uip.c.

References HTONS.

Referenced by uip_chksum(), uip_connect(), uip_ipchksum(), uip_udp_new(), and webclient_get().

void uip_add32 | ( | u8_t * | op32,
|  | u16_t | op16
| ) |

Carry out a 32-bit addition.

Because not all architectures for which uIP is intended has native 32-bit arithmetic, uIP uses an external C function for doing the required 32-bit additions in the TCP protocol processing. This function should add the two arguments and place the result in the global variable uip_acc32.

Note:
  The 32-bit integer pointed to by the op32 parameter and the result in the uip_acc32 variable are in network byte order (big endian).

Parameters:

  | op32 | A pointer to a 4-byte array representing a 32-bit integer in network byte order (big endian).
  | op16 | A 16-bit integer in host byte order.

Definition at line 249 of file uip.c.

Referenced by uip_split_output().

u16_t uip_chksum | ( | u16_t * | buf,
|  | u16_t | len
| ) |

Calculate the Internet checksum over a buffer.

The Internet checksum is the one's complement of the one's complement sum of all 16-bit words in the buffer.

See RFC1071.

Parameters:

  | buf | A pointer to the buffer over which the checksum is to be computed.
  | len | The length of the buffer over which the checksum is to be computed.

Returns:
  The Internet checksum of the buffer.

Definition at line 311 of file uip.c.

References htons().

struct uip_conn* uip_connect | ( | uip_ipaddr_t * | ripaddr,
|  | u16_t | port
| ) |

Connect to a remote host using TCP.

This function is used to start a new connection to the specified port on the specied host. It allocates a new connection identifier, sets the connection to the SYN_SENT state and sets the retransmission timer to 0. This will cause a TCP SYN segment to be sent out the next time this connection is periodically processed, which usually is done within 0.5 seconds after the call to uip_connect().

Note:
  This function is avaliable only if support for active open has been configured by defining UIP_ACTIVE_OPEN to 1 in uipopt.h.

  Since this function requires the port number to be in network byte order, a conversion using HTONS() or htons() is necessary.

     uip_ipaddr_t ipaddr;

     uip_ipaddr(&ipaddr, 192,168,1,2);
     uip_connect(&ipaddr, HTONS(80));

Parameters:

  | ripaddr | The IP address of the remote hot.
  | port | A 16-bit port number in network byte order.

Returns:
  A pointer to the uIP connection identifier for the new connection, or NULL if no connection could be allocated.

Definition at line 407 of file uip.c.

References htons(), uip_conn::lport, uip_conn::tcpstateflags, UIP_CLOSED, uip_conn, uip_conns, and UIP_CONNS.

Referenced by smtp_send(), and webclient_get().

void uip_init | ( | void |  | ) |

| uIP initialization function. This function should be called at boot up to initilize the uIP TCP/IP stack. Definition at line 379 of file uip.c. References UIP_LISTENPORTS.

u16_t uip_ipchksum | ( | void |  | ) |

Calculate the IP header checksum of the packet header in uip_buf.

The IP header checksum is the Internet checksum of the 20 bytes of the IP header.

Returns:
  The IP header checksum of the IP header in the uip_buf buffer.

Definition at line 318 of file uip.c.

References DEBUG_PRINTF, htons(), UIP_IPH_LEN, and UIP_LLH_LEN.

Referenced by uip_process(), and uip_split_output().

void uip_listen | ( | u16_t | port | ) |

Start listening to the specified port.

Note:
  Since this function expects the port number in network byte order, a conversion using HTONS() or htons() is necessary.

     uip_listen(HTONS(80));

Parameters:

  | port | A 16-bit port number in network byte order.

Definition at line 529 of file uip.c.

References UIP_LISTENPORTS.

Referenced by hello_world_init(), and httpd_init().

void uip_send | ( | const void * | data,
|  | int | len
| ) |

Send data on the current connection.

This function is used to send out a single segment of TCP data. Only applications that have been invoked by uIP for event processing can send data.

The amount of data that actually is sent out after a call to this funcion is determined by the maximum amount of data TCP allows. uIP will automatically crop the data so that only the appropriate amount of data is sent. The function uip_mss() can be used to query uIP for the amount of data that actually will be sent.

Note:
  This function does not guarantee that the sent data will arrive at the destination. If the data is lost in the network, the application will be invoked with the uip_rexmit() event being set. The application will then have to resend the data using this function.

Parameters:

  | data | A pointer to the data which is to be sent.
  | len | The maximum amount of data bytes to be sent.

Definition at line 1888 of file uip.c.

References uip_sappdata, and uip_slen.

void uip_setipid | ( | u16_t | id | ) |

| uIP initialization function. This function may be used at boot time to set the initial ip_id. Definition at line 181 of file uip.c.

u16_t uip_tcpchksum | ( | void |  | ) |

Calculate the TCP checksum of the packet in uip_buf and uip_appdata.

The TCP checksum is the Internet checksum of data contents of the TCP segment, and a pseudo-header as defined in RFC793.

Returns:
  The TCP checksum of the TCP segment in uip_buf and pointed to by uip_appdata.

Definition at line 364 of file uip.c.

References UIP_PROTO_TCP.

Referenced by uip_split_output().

struct uip_udp_conn* uip_udp_new | ( | uip_ipaddr_t * | ripaddr,
|  | u16_t | rport
| ) |

Set up a new UDP connection.

This function sets up a new UDP connection. The function will automatically allocate an unused local port for the new connection. However, another port can be chosen by using the uip_udp_bind() call, after the uip_udp_new() function has been called.

Example:

     uip_ipaddr_t addr;
     struct uip_udp_conn *c;

     uip_ipaddr(&addr, 192,168,2,1);
     c = uip_udp_new(&addr, HTONS(12345));
     if(c != NULL) {
       uip_udp_bind(c, HTONS(12344));
     }

Parameters:

  | ripaddr | The IP address of the remote host.
  | rport | The remote port number in network byte order.

Returns:
  The uip_udp_conn structure for the new connection or NULL if no connection could be allocated.

Definition at line 473 of file uip.c.

References htons(), uip_udp_conn::lport, uip_udp_conn, uip_udp_conns, and UIP_UDP_CONNS.

Referenced by resolv_conf().

u16_t uip_udpchksum | ( | void |  | ) |

Calculate the UDP checksum of the packet in uip_buf and uip_appdata.

The UDP checksum is the Internet checksum of data contents of the UDP segment, and a pseudo-header as defined in RFC768.

Returns:
  The UDP checksum of the UDP segment in uip_buf and pointed to by uip_appdata.

Referenced by uip_process().

void uip_unlisten | ( | u16_t | port | ) |

Stop listening to the specified port.

Note:
  Since this function expects the port number in network byte order, a conversion using HTONS() or htons() is necessary.

     uip_unlisten(HTONS(80));

Parameters:

  | port | A 16-bit port number in network byte order.

Definition at line 518 of file uip.c.

References UIP_LISTENPORTS.

## Variable Documentation

void* uip_appdata

| Pointer to the application data in the packet buffer. This pointer points to the application data when the application is called. If the application wishes to send data, the application may use this space to write the data into before calling uip_send(). Definition at line 143 of file uip.c. Referenced by uip_process(), and uip_split_output().

void* uip_appdata

Pointer to the application data in the packet buffer.

This pointer points to the application data when the application is called. If the application wishes to send data, the application may use this space to write the data into before calling uip_send().

Examples:
  dhcpc.c, resolv.c, telnetd.c, and webclient.c.

Definition at line 143 of file uip.c.

Referenced by uip_process(), and uip_split_output().

u8_t uip_buf[UIP_BUFSIZE+2]

The uIP packet buffer.

The uip_buf array is used to hold incoming and outgoing packets. The device driver should place incoming data into this buffer. When sending data, the device driver should read the link level headers and the TCP/IP headers from this buffer. The size of the link level headers is configured by the UIP_LLH_LEN define.

Note:
  The application data need not be placed in this buffer, so the device driver must read it from the place pointed to by the uip_appdata pointer as illustrated by the following example:

       void
       devicedriver_send(void)
       {
          hwsend(&uip_buf[0], UIP_LLH_LEN);
          if(uip_len <= UIP_LLH_LEN + UIP_TCPIP_HLEN) {
            hwsend(&uip_buf[UIP_LLH_LEN], uip_len - UIP_LLH_LEN);
          } else {
            hwsend(&uip_buf[UIP_LLH_LEN], UIP_TCPIP_HLEN);
            hwsend(uip_appdata, uip_len - UIP_TCPIP_HLEN - UIP_LLH_LEN);
          }
       }

Definition at line 139 of file uip.c.

Referenced by uip_process().

struct uip_conn* uip_conn

| Pointer to the current TCP connection. The uip_conn pointer can be used to access the current TCP connection. Definition at line 163 of file uip.c. Referenced by uip_connect().

struct uip_conn* uip_conn

Pointer to the current TCP connection.

The uip_conn pointer can be used to access the current TCP connection.

Examples:
  hello-world.c, smtp.c, and webclient.c.

Definition at line 163 of file uip.c.

Referenced by uip_connect().

u16_t uip_len

The length of the packet in the uip_buf buffer.

The global variable uip_len holds the length of the packet in the uip_buf buffer.

When the network device driver calls the uIP input function, uip_len should be set to the length of the packet in the uip_buf buffer.

When sending packets, the device driver should use the contents of the uip_len variable to determine the length of the outgoing packet.

Definition at line 155 of file uip.c.

Referenced by uip_arp_arpin(), uip_process(), and uip_split_output().

struct uip_stats uip_stat

| The uIP TCP/IP statistics. This is the variable in which the uIP TCP/IP statistics are gathered. Referenced by uip_process().