[lwip-users] [lwip] RFC - Raw API for lwIP 0.5

[Adam Dunkels]

Hi!

There has been a lack of documentation for the lwIP "raw API", i.e., the 
callback based way of interfacing lwIP. This is the preferred way of writing 
applications that should be small in code size and memory usage. The 
sequential API that is documented in the PDF file on the homepage has a much 
higher overhead and is not very well suited for small systems since it forces 
a multithreaded paradigm on the application. By using the callback based API, 
more efficient applications is possible.

I have been writing some small documention for it, and would really like to 
hear your comments on it.

---8<---8<---8<---8<---8<---8<---8<---
New raw TCP/IP interface for lwIP 0.5 (Request For Comments)

lwIP provides two Application Program's Interfaces (APIs) for programs
to use for communication with the TCP/IP code: the sequential API
(often just called "the API") and the raw TCP/IP interface. This
document is intended as a description of the latter. For lwIP versions
lower than 0.5, this API was not documented.

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

---8<---8<---8<---8<---8<---8<---8<---
-- 
Adam Dunkels <address@hidden>
http://www.sics.se/~adam
[This message was sent through the lwip discussion list.]