/**\defgroup uip The uIP TCP/IP stack@{*//**\mainpage The uIP TCP/IP stack\author Adam Dunkels <adam@dunkels.com>The uIP TCP/IP stack is intended to make it possible to communicateusing the TCP/IP protocol suite even on small 8-bitmicro-controllers. Despite being small and simple, uIP do not requiretheir peers to have complex, full-size stacks, but can communicatewith peers running a similarly light-weight stack. The code size is onthe order of a few kilobytes and RAM usage can be configured to be aslow as a few hundred bytes.\section uIPIntroduction uIP introductionWith the success of the Internet, the TCP/IP protocol suite has becomea global standard for communication. TCP/IP is the underlying protocolused for web page transfers, e-mail transmissions, file transfers, andpeer-to-peer networking over the Internet. For embedded systems, beingable to run native TCP/IP makes it possible to connect the systemdirectly to an intranet or even the global Internet. Embedded deviceswith full TCP/IP support will be first-class network citizens, thusbeing able to fully communicate with other hosts in the network.Traditional TCP/IP implementations have required far too muchresources both in terms of code size and memory usage to be useful insmall 8 or 16-bit systems. Code size of a few hundred kilobytes andRAM requirements of several hundreds of kilobytes have made itimpossible to fit the full TCP/IP stack into systems with a few tensof kilobytes of RAM and room for less than 100 kilobytes ofcode.The uIP implementation is designed to have only the absolute minimalset of features needed for a full TCP/IP stack. It can only handle asingle network interface and contains only a rudimentary UDPimplementation, but focuses on the IP, ICMP and TCP protocols. uIP iswritten in the C programming language.Many other TCP/IP implementations for small systems assume that theembedded device always will communicate with a full-scale TCP/IPimplementation running on a workstation-class machine. Under thisassumption, it is possible to remove certain TCP/IP mechanisms thatare very rarely used in such situations. Many of those mechanisms areessential, however, if the embedded device is to communicate withanother equally limited device, e.g., when running distributedpeer-to-peer services and protocols. uIP is designed to be RFCcompliant in order to let the embedded devices to act as first-classnetwork citizens. The uIP TCP/IP implementation that is not tailoredfor any specific application.\section tcpip TCP/IP communicationThe full TCP/IP suite consists of numerous protocols, ranging from lowlevel protocols such as ARP which translates IP addresses to MACaddresses, to application level protocols such as SMTP that is used totransfer e-mail. The uIP is mostly concerned with the TCP and IPprotocols and upper layer protocols will be referred to as "theapplication". Lower layer protocols are often implemented in hardwareor firmware and will be referred to as "the network device" that arecontrolled by the network device driver.TCP provides a reliable byte stream to the upper layer protocols. Itbreaks the byte stream into appropriately sized segments and eachsegment is sent in its own IP packet. The IP packets are sent out onthe network by the network device driver. If the destination is not onthe physically connected network, the IP packet is forwarded ontoanother network by a router that is situated between the twonetworks. If the maximum packet size of the other network is smallerthan the size of the IP packet, the packet is fragmented into smallerpackets by the router. If possible, the size of the TCP segments arechosen so that fragmentation is minimized. The final recipient of thepacket will have to reassemble any fragmented IP packets before theycan be passed to higher layers.The formal requirements for the protocols in the TCP/IP stack isspecified in a number of RFC documents published by the InternetEngineering Task Force, IETF. Each of the protocols in the stack isdefined in one more RFC documents and RFC1122 collectsall requirements and updates the previous RFCs. The RFC1122 requirements can be divided into two categories; thosethat deal with the host to host communication and those that deal withcommunication between the application and the networking stack. Anexample of the first kind is "A TCP MUST be able to receive a TCPoption in any segment" and an example of the second kind is "ThereMUST be a mechanism for reporting soft TCP error conditions to theapplication." A TCP/IP implementation that violates requirements ofthe first kind may not be able to communicate with other TCP/IPimplementations and may even lead to network failures. Violation ofthe second kind of requirements will only affect the communicationwithin the system and will not affect host-to-host communication.In uIP, all RFC requirements that affect host-to-host communicationare implemented. However, in order to reduce code size, we haveremoved certain mechanisms in the interface between the applicationand the stack, such as the soft error reporting mechanism anddynamically configurable type-of-service bits for TCPconnections. Since there are only very few applications that make useof those features they can be removed without loss of generality.\section memory Memory managementIn the architectures for which uIP is intended, RAM is the mostscarce resource. With only a few kilobytes of RAM available for theTCP/IP stack to use, mechanisms used in traditional TCP/IP cannot bedirectly applied.The uIP stack does not use explicit dynamic memoryallocation. Instead, it uses a single global buffer for holdingpackets and has a fixed table for holding connection state. The globalpacket buffer is large enough to contain one packet of maximumsize. When a packet arrives from the network, the device driver placesit in the global buffer and calls the TCP/IP stack. If the packetcontains data, the TCP/IP stack will notify the correspondingapplication. Because the data in the buffer will be overwritten by thenext incoming packet, the application will either have to actimmediately on the data or copy the data into a secondary buffer forlater processing. The packet buffer will not be overwritten by newpackets before the application has processed the data. Packets thatarrive when the application is processing the data must be queued,either by the network device or by the device driver. Most single-chipEthernet controllers have on-chip buffers that are large enough tocontain at least 4 maximum sized Ethernet frames. Devices that arehandled by the processor, such as RS-232 ports, can copy incomingbytes to a separate buffer during application processing. If thebuffers are full, the incoming packet is dropped. This will causeperformance degradation, but only when multiple connections arerunning in parallel. This is because uIP advertises a very smallreceiver window, which means that only a single TCP segment will be inthe network per connection.In uIP, the same global packet buffer that is used for incomingpackets is also used for the TCP/IP headers of outgoing data. If theapplication sends dynamic data, it may use the parts of the globalpacket buffer that are not used for headers as a temporary storagebuffer. To send the data, the application passes a pointer to the dataas well as the length of the data to the stack. The TCP/IP headers arewritten into the global buffer and once the headers have beenproduced, the device driver sends the headers and the application dataout on the network. The data is not queued forretransmissions. Instead, the application will have to reproduce thedata if a retransmission is necessary.The total amount of memory usage for uIP depends heavily on theapplications of the particular device in which the implementations areto be run. The memory configuration determines both the amount oftraffic the system should be able to handle and the maximum amount ofsimultaneous connections. A device that will be sending large e-mailswhile at the same time running a web server with highly dynamic webpages and multiple simultaneous clients, will require more RAM than asimple Telnet server. It is possible to run the uIP implementationwith as little as 200 bytes of RAM, but such a configuration willprovide extremely low throughput and will only allow a small number ofsimultaneous connections.\section api Application program interface (API)The Application Program Interface (API) defines the way theapplication program interacts with the TCP/IP stack. The most commonlyused API for TCP/IP is the BSD socket API which is used in most Unixsystems and has heavily influenced the Microsoft Windows WinSockAPI. Because the socket API uses stop-and-wait semantics, it requiressupport from an underlying multitasking operating system. Since theoverhead of task management, context switching and allocation of stackspace for the tasks might be too high in the intended uIP targetarchitectures, the BSD socket interface is not suitable for ourpurposes.Instead, uIP uses an event driven interface where the application isinvoked in response to certain events. An application running on topof uIP is implemented as a C function that is called by uIP inresponse to certain events. uIP calls the application when data isreceived, when data has been successfully delivered to the other endof the connection, when a new connection has been set up, or when datahas to be retransmitted. The application is also periodically polledfor new data. The application program provides only one callbackfunction; it is up to the application to deal with mapping differentnetwork services to different ports and connections. Because theapplication is able to act on incoming data and connection requests assoon as the TCP/IP stack receives the packet, low response times canbe achieved even in low-end systems.uIP is different from other TCP/IP stacks in that it requires helpfrom the application when doing retransmissions. Other TCP/IP stacksbuffer the transmitted data in memory until the data is known to besuccessfully delivered to the remote end of the connection. If thedata needs to be retransmitted, the stack takes care of theretransmission without notifying the application. With this approach,the data has to be buffered in memory while waiting for anacknowledgment even if the application might be able to quicklyregenerate the data if a retransmission has to be made.In order to reduce memory usage, uIP utilizes the fact that theapplication may be able to regenerate sent data and lets theapplication take part in retransmissions. uIP does not keep track ofpacket contents after they have been sent by the device driver, anduIP requires that the application takes an active part in performingthe retransmission. When uIP decides that a segment should beretransmitted, it calls the application with a flag set indicatingthat a retransmission is required. The application checks theretransmission flag and produces the same data that was previouslysent. From the application's standpoint, performing a retransmissionis not different from how the data originally was sent. Therefore theapplication can be written in such a way that the same code is usedboth for sending data and retransmitting data. Also, it is importantto note that even though the actual retransmission operation iscarried out by the application, it is the responsibility of the stackto know when the retransmission should be made. Thus the complexity ofthe application does not necessarily increase because it takes anactive part in doing retransmissions.\subsection appevents Application eventsThe application must be implemented as a C function, UIP_APPCALL(),that uIP calls whenever an event occurs. Each event has a correspondingtest function that is used to distinguish between differentevents. The functions are implemented as C macros that will evaluateto either zero or non-zero. Note that certain events can happen inconjunction with each other (i.e., new data can arrive at the sametime as data is acknowledged).\subsection connstate The connection pointerWhen the application is called by uIP, the global variable uip_conn isset to point to the uip_conn structure for the connection thatcurrently is handled, and is called the "current connection". Thefields in the uip_conn structure for the current connection can beused, e.g., to distinguish between different services, or to check towhich IP address the connection is connected. One typical use would beto inspect the uip_conn->lport (the local TCP port number) to decidewhich service the connection should provide. For instance, anapplication might decide to act as an HTTP server if the value ofuip_conn->lport is equal to 80 and act as a TELNET server if the valueis 23. \subsection recvdata Receiving dataIf the uIP test function uip_newdata() is non-zero, the remote host ofthe connection has sent new data. The uip_appdata pointer point to theactual data. The size of the data is obtained through the uIP functionuip_datalen(). The data is not buffered by uIP, but will beoverwritten after the application function returns, and theapplication will therefor have to either act directly on the incomingdata, or by itself copy the incoming data into a buffer for laterprocessing.\subsection senddata Sending dataWhen sending data, uIP adjusts the length of the data sent by theapplication according to the available buffer space and the currentTCP window advertised by the receiver. The amount of buffer space isdictated by the memory configuration. It is therefore possible thatall data sent from the application does not arrive at the receiver,and the application may use the uip_mss() function to see how muchdata that actually will be sent by the stack.The application sends data by using the uIP function uip_send(). Theuip_send() function takes two arguments; a pointer to the data to besent and the length of the data. If the application needs RAM spacefor 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 aconnection and it is not possible to call uip_send() more than onceper application invocation; only the data from the last call will besent.\subsection rexmitdata Retransmitting dataRetransmissions are driven by the periodic TCP timer. Every time theperiodic timer is invoked, the retransmission timer for eachconnection is decremented. If the timer reaches zero, a retransmissionshould be made. As uIP does not keep track of packet contents after they havebeen sent by the device driver, uIP requires that theapplication takes an active part in performing theretransmission. When uIP decides that a segment should beretransmitted, the application function is called with theuip_rexmit() flag set, indicating that a retransmission isrequired.The application must check the uip_rexmit() flag and produce the samedata that was previously sent. From the application's standpoint,performing a retransmission is not different from how the dataoriginally was sent. Therefor, the application can be written in sucha way that the same code is used both for sending data andretransmitting data. Also, it is important to note that even thoughthe actual retransmission operation is carried out by the application,it is the responsibility of the stack to know when the retransmissionshould be made. Thus the complexity of the application does notnecessarily increase because it takes an active part in doingretransmissions.\subsection closing Closing connectionsThe application closes the current connection by calling theuip_close() during an application call. This will cause the connectionto be cleanly closed. In order to indicate a fatal error, the