| Raw TCP/IP interface for lwIP |
| |
| Authors: Adam Dunkels, Leon Woestenberg |
| |
| lwIP provides two Application Program's Interfaces (APIs) for programs |
| to use for communication with the TCP/IP code: |
| * low-level "core" / "callback" or "raw" API. |
| * higher-level "sequential" API. |
| |
| The sequential API provides a way for ordinary, sequential, programs |
| to use the lwIP stack. It is quite similar to the BSD socket API. The |
| model of execution is based on the blocking open-read-write-close |
| paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP |
| code and the application program must reside in different execution |
| contexts (threads). |
| |
| ** The remainder of this document discusses the "raw" API. ** |
| |
| The raw TCP/IP interface allows the application program to integrate |
| better with the TCP/IP code. Program execution is event based by |
| having callback functions being called from within the TCP/IP |
| code. The TCP/IP code and the application program both run in the same |
| thread. The sequential API has a much higher overhead and is not very |
| well suited for small systems since it forces a multithreaded paradigm |
| on the application. |
| |
| The raw TCP/IP interface is not only faster in terms of code execution |
| time but is also less memory intensive. The drawback is that program |
| development is somewhat harder and application programs written for |
| the raw TCP/IP interface are more difficult to understand. Still, this |
| is the preferred way of writing applications that should be small in |
| code size and memory usage. |
| |
| Both APIs can be used simultaneously by different application |
| programs. In fact, the sequential API is implemented as an application |
| program using the raw TCP/IP interface. |
| |
| --- Callbacks |
| |
| Program execution is driven by callbacks. Each callback is an ordinary |
| C function that is called from within the TCP/IP code. Every callback |
| function is passed the current TCP or UDP connection state as an |
| argument. Also, in order to be able to keep program specific state, |
| the callback functions are called with a program specified argument |
| that is independent of the TCP/IP state. |
| |
| The function for setting the application connection state is: |
| |
| - void tcp_arg(struct tcp_pcb *pcb, void *arg) |
| |
| Specifies the program specific state that should be passed to all |
| other callback functions. The "pcb" argument is the current TCP |
| connection control block, and the "arg" argument is the argument |
| that will be passed to the callbacks. |
| |
| |
| --- TCP connection setup |
| |
| The functions used for setting up connections is similar to that of |
| the sequential API and of the BSD socket API. A new TCP connection |
| identifier (i.e., a protocol control block - PCB) is created with the |
| tcp_new() function. This PCB can then be either set to listen for new |
| incoming connections or be explicitly connected to another host. |
| |
| - struct tcp_pcb *tcp_new(void) |
| |
| Creates a new connection identifier (PCB). If memory is not |
| available for creating the new pcb, NULL is returned. |
| |
| - err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr, |
| u16_t port) |
| |
| Binds the pcb to a local IP address and port number. The IP address |
| can be specified as IP_ADDR_ANY in order to bind the connection to |
| all local IP addresses. |
| |
| If another connection is bound to the same port, the function will |
| return ERR_USE, otherwise ERR_OK is returned. |
| |
| - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb) |
| |
| Commands a pcb to start listening for incoming connections. When an |
| incoming connection is accepted, the function specified with the |
| tcp_accept() function will be called. The pcb will have to be bound |
| to a local port with the tcp_bind() function. |
| |
| The tcp_listen() function returns a new connection identifier, and |
| the one passed as an argument to the function will be |
| deallocated. The reason for this behavior is that less memory is |
| needed for a connection that is listening, so tcp_listen() will |
| reclaim the memory needed for the original connection and allocate a |
| new smaller memory block for the listening connection. |
| |
| tcp_listen() may return NULL if no memory was available for the |
| listening connection. If so, the memory associated with the pcb |
| passed as an argument to tcp_listen() will not be deallocated. |
| |
| - void tcp_accept(struct tcp_pcb *pcb, |
| err_t (* accept)(void *arg, struct tcp_pcb *newpcb, |
| err_t err)) |
| |
| Specified the callback function that should be called when a new |
| connection arrives on a listening connection. |
| |
| - err_t tcp_connect(struct tcp_pcb *pcb, struct ip_addr *ipaddr, |
| u16_t port, err_t (* connected)(void *arg, |
| struct tcp_pcb *tpcb, |
| err_t err)); |
| |
| Sets up the pcb to connect to the remote host and sends the |
| initial SYN segment which opens the connection. |
| |
| The tcp_connect() function returns immediately; it does not wait for |
| the connection to be properly setup. Instead, it will call the |
| function specified as the fourth argument (the "connected" argument) |
| when the connection is established. If the connection could not be |
| properly established, either because the other host refused the |
| connection or because the other host didn't answer, the "connected" |
| function will be called with an the "err" argument set accordingly. |
| |
| The tcp_connect() function can return ERR_MEM if no memory is |
| available for enqueueing the SYN segment. If the SYN indeed was |
| enqueued successfully, the tcp_connect() function returns ERR_OK. |
| |
| |
| --- Sending TCP data |
| |
| TCP data is sent by enqueueing the data with a call to |
| tcp_write(). When the data is successfully transmitted to the remote |
| host, the application will be notified with a call to a specified |
| callback function. |
| |
| - err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len, |
| u8_t copy) |
| |
| Enqueues the data pointed to by the argument dataptr. The length of |
| the data is passed as the len parameter. The copy argument is either |
| 0 or 1 and indicates whether the new memory should be allocated for |
| the data to be copied into. If the argument is 0, no new memory |
| should be allocated and the data should only be referenced by |
| pointer. |
| |
| The tcp_write() function will fail and return ERR_MEM if the length |
| of the data exceeds the current send buffer size or if the length of |
| the queue of outgoing segment is larger than the upper limit defined |
| in lwipopts.h. The number of bytes available in the output queue can |
| be retrieved with the tcp_sndbuf() function. |
| |
| The proper way to use this function is to call the function with at |
| most tcp_sndbuf() bytes of data. If the function returns ERR_MEM, |
| the application should wait until some of the currently enqueued |
| data has been successfully received by the other host and try again. |
| |
| - void tcp_sent(struct tcp_pcb *pcb, |
| err_t (* sent)(void *arg, struct tcp_pcb *tpcb, |
| u16_t len)) |
| |
| Specifies the callback function that should be called when data has |
| successfully been received (i.e., acknowledged) by the remote |
| host. The len argument passed to the callback function gives the |
| amount bytes that was acknowledged by the last acknowledgment. |
| |
| |
| --- Receiving TCP data |
| |
| TCP data reception is callback based - an application specified |
| callback function is called when new data arrives. When the |
| application has taken the data, it has to call the tcp_recved() |
| function to indicate that TCP can advertise increase the receive |
| window. |
| |
| - void tcp_recv(struct tcp_pcb *pcb, |
| err_t (* recv)(void *arg, struct tcp_pcb *tpcb, |
| struct pbuf *p, err_t err)) |
| |
| Sets the callback function that will be called when new data |
| arrives. The callback function will be passed a NULL pbuf to |
| indicate that the remote host has closed the connection. |
| |
| - void tcp_recved(struct tcp_pcb *pcb, u16_t len) |
| |
| Must be called when the application has received the data. The len |
| argument indicates the length of the received data. |
| |
| |
| --- Application polling |
| |
| When a connection is idle (i.e., no data is either transmitted or |
| received), lwIP will repeatedly poll the application by calling a |
| specified callback function. This can be used either as a watchdog |
| timer for killing connections that have stayed idle for too long, or |
| as a method of waiting for memory to become available. For instance, |
| if a call to tcp_write() has failed because memory wasn't available, |
| the application may use the polling functionality to call tcp_write() |
| again when the connection has been idle for a while. |
| |
| - void tcp_poll(struct tcp_pcb *pcb, u8_t interval, |
| err_t (* poll)(void *arg, struct tcp_pcb *tpcb)) |
| |
| Specifies the polling interval and the callback function that should |
| be called to poll the application. The interval is specified in |
| number of TCP coarse grained timer shots, which typically occurs |
| twice a second. An interval of 10 means that the application would |
| be polled every 5 seconds. |
| |
| |
| --- Closing and aborting connections |
| |
| - err_t tcp_close(struct tcp_pcb *pcb) |
| |
| Closes the connection. The function may return ERR_MEM if no memory |
| was available for closing the connection. If so, the application |
| should wait and try again either by using the acknowledgment |
| callback or the polling functionality. If the close succeeds, the |
| function returns ERR_OK. |
| |
| The pcb is deallocated by the TCP code after a call to tcp_close(). |
| |
| - void tcp_abort(struct tcp_pcb *pcb) |
| |
| Aborts the connection by sending a RST (reset) segment to the remote |
| host. The pcb is deallocated. This function never fails. |
| |
| If a connection is aborted because of an error, the application is |
| alerted of this event by the err callback. Errors that might abort a |
| connection are when there is a shortage of memory. The callback |
| function to be called is set using the tcp_err() function. |
| |
| - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg, |
| err_t err)) |
| |
| The error callback function does not get the pcb passed to it as a |
| parameter since the pcb may already have been deallocated. |
| |
| |
| --- Lower layer TCP interface |
| |
| TCP provides a simple interface to the lower layers of the |
| system. During system initialization, the function tcp_init() has |
| to be called before any other TCP function is called. When the system |
| is running, the two timer functions tcp_fasttmr() and tcp_slowtmr() |
| must be called with regular intervals. The tcp_fasttmr() should be |
| called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and |
| tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds. |
| |
| |
| --- UDP interface |
| |
| The UDP interface is similar to that of TCP, but due to the lower |
| level of complexity of UDP, the interface is significantly simpler. |
| |
| - struct udp_pcb *udp_new(void) |
| |
| Creates a new UDP pcb which can be used for UDP communication. The |
| pcb is not active until it has either been bound to a local address |
| or connected to a remote address. |
| |
| - void udp_remove(struct udp_pcb *pcb) |
| |
| Removes and deallocates the pcb. |
| |
| - err_t udp_bind(struct udp_pcb *pcb, struct ip_addr *ipaddr, |
| u16_t port) |
| |
| Binds the pcb to a local address. The IP-address argument "ipaddr" |
| can be IP_ADDR_ANY to indicate that it should listen to any local IP |
| address. The function currently always return ERR_OK. |
| |
| - err_t udp_connect(struct udp_pcb *pcb, struct ip_addr *ipaddr, |
| u16_t port) |
| |
| Sets the remote end of the pcb. This function does not generate any |
| network traffic, but only set the remote address of the pcb. |
| |
| - err_t udp_disconnect(struct udp_pcb *pcb) |
| |
| Remove the remote end of the pcb. This function does not generate |
| any network traffic, but only removes the remote address of the pcb. |
| |
| - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p) |
| |
| Sends the pbuf p. The pbuf is not deallocated. |
| |
| - void udp_recv(struct udp_pcb *pcb, |
| void (* recv)(void *arg, struct udp_pcb *upcb, |
| struct pbuf *p, |
| struct ip_addr *addr, |
| u16_t port), |
| void *recv_arg) |
| |
| Specifies a callback function that should be called when a UDP |
| datagram is received. |