1 Raw TCP/IP interface for lwIP
3 Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
5 lwIP provides two Application Program's Interfaces (APIs) for programs
6 to use for communication with the TCP/IP code:
7 * low-level "core" / "callback" or "raw" API.
8 * higher-level "sequential" API.
10 The sequential API provides a way for ordinary, sequential, programs
11 to use the lwIP stack. It is quite similar to the BSD socket API. The
12 model of execution is based on the blocking open-read-write-close
13 paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
14 code and the application program must reside in different execution
17 ** The remainder of this document discusses the "raw" API. **
19 The raw TCP/IP interface allows the application program to integrate
20 better with the TCP/IP code. Program execution is event based by
21 having callback functions being called from within the TCP/IP
22 code. The TCP/IP code and the application program both run in the same
23 thread. The sequential API has a much higher overhead and is not very
24 well suited for small systems since it forces a multithreaded paradigm
27 The raw TCP/IP interface is not only faster in terms of code execution
28 time but is also less memory intensive. The drawback is that program
29 development is somewhat harder and application programs written for
30 the raw TCP/IP interface are more difficult to understand. Still, this
31 is the preferred way of writing applications that should be small in
32 code size and memory usage.
34 Both APIs can be used simultaneously by different application
35 programs. In fact, the sequential API is implemented as an application
36 program using the raw TCP/IP interface.
40 Program execution is driven by callbacks. Each callback is an ordinary
41 C function that is called from within the TCP/IP code. Every callback
42 function is passed the current TCP or UDP connection state as an
43 argument. Also, in order to be able to keep program specific state,
44 the callback functions are called with a program specified argument
45 that is independent of the TCP/IP state.
47 The function for setting the application connection state is:
49 - void tcp_arg(struct tcp_pcb *pcb, void *arg)
51 Specifies the program specific state that should be passed to all
52 other callback functions. The "pcb" argument is the current TCP
53 connection control block, and the "arg" argument is the argument
54 that will be passed to the callbacks.
57 --- TCP connection setup
59 The functions used for setting up connections is similar to that of
60 the sequential API and of the BSD socket API. A new TCP connection
61 identifier (i.e., a protocol control block - PCB) is created with the
62 tcp_new() function. This PCB can then be either set to listen for new
63 incoming connections or be explicitly connected to another host.
65 - struct tcp_pcb *tcp_new(void)
67 Creates a new connection identifier (PCB). If memory is not
68 available for creating the new pcb, NULL is returned.
70 - err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
73 Binds the pcb to a local IP address and port number. The IP address
74 can be specified as IP_ADDR_ANY in order to bind the connection to
75 all local IP addresses.
77 If another connection is bound to the same port, the function will
78 return ERR_USE, otherwise ERR_OK is returned.
80 - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
82 Commands a pcb to start listening for incoming connections. When an
83 incoming connection is accepted, the function specified with the
84 tcp_accept() function will be called. The pcb will have to be bound
85 to a local port with the tcp_bind() function.
87 The tcp_listen() function returns a new connection identifier, and
88 the one passed as an argument to the function will be
89 deallocated. The reason for this behavior is that less memory is
90 needed for a connection that is listening, so tcp_listen() will
91 reclaim the memory needed for the original connection and allocate a
92 new smaller memory block for the listening connection.
94 tcp_listen() may return NULL if no memory was available for the
95 listening connection. If so, the memory associated with the pcb
96 passed as an argument to tcp_listen() will not be deallocated.
98 - void tcp_accept(struct tcp_pcb *pcb,
99 err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
102 Specified the callback function that should be called when a new
103 connection arrives on a listening connection.
105 - err_t tcp_connect(struct tcp_pcb *pcb, struct ip_addr *ipaddr,
106 u16_t port, err_t (* connected)(void *arg,
107 struct tcp_pcb *tpcb,
110 Sets up the pcb to connect to the remote host and sends the
111 initial SYN segment which opens the connection.
113 The tcp_connect() function returns immediately; it does not wait for
114 the connection to be properly setup. Instead, it will call the
115 function specified as the fourth argument (the "connected" argument)
116 when the connection is established. If the connection could not be
117 properly established, either because the other host refused the
118 connection or because the other host didn't answer, the "connected"
119 function will be called with an the "err" argument set accordingly.
121 The tcp_connect() function can return ERR_MEM if no memory is
122 available for enqueueing the SYN segment. If the SYN indeed was
123 enqueued successfully, the tcp_connect() function returns ERR_OK.
128 TCP data is sent by enqueueing the data with a call to
129 tcp_write(). When the data is successfully transmitted to the remote
130 host, the application will be notified with a call to a specified
133 - err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len,
136 Enqueues the data pointed to by the argument dataptr. The length of
137 the data is passed as the len parameter. The copy argument is either
138 0 or 1 and indicates whether the new memory should be allocated for
139 the data to be copied into. If the argument is 0, no new memory
140 should be allocated and the data should only be referenced by
143 The tcp_write() function will fail and return ERR_MEM if the length
144 of the data exceeds the current send buffer size or if the length of
145 the queue of outgoing segment is larger than the upper limit defined
146 in lwipopts.h. The number of bytes available in the output queue can
147 be retrieved with the tcp_sndbuf() function.
149 The proper way to use this function is to call the function with at
150 most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
151 the application should wait until some of the currently enqueued
152 data has been successfully received by the other host and try again.
154 - void tcp_sent(struct tcp_pcb *pcb,
155 err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
158 Specifies the callback function that should be called when data has
159 successfully been received (i.e., acknowledged) by the remote
160 host. The len argument passed to the callback function gives the
161 amount bytes that was acknowledged by the last acknowledgment.
164 --- Receiving TCP data
166 TCP data reception is callback based - an application specified
167 callback function is called when new data arrives. When the
168 application has taken the data, it has to call the tcp_recved()
169 function to indicate that TCP can advertise increase the receive
172 - void tcp_recv(struct tcp_pcb *pcb,
173 err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
174 struct pbuf *p, err_t err))
176 Sets the callback function that will be called when new data
177 arrives. The callback function will be passed a NULL pbuf to
178 indicate that the remote host has closed the connection.
180 - void tcp_recved(struct tcp_pcb *pcb, u16_t len)
182 Must be called when the application has received the data. The len
183 argument indicates the length of the received data.
186 --- Application polling
188 When a connection is idle (i.e., no data is either transmitted or
189 received), lwIP will repeatedly poll the application by calling a
190 specified callback function. This can be used either as a watchdog
191 timer for killing connections that have stayed idle for too long, or
192 as a method of waiting for memory to become available. For instance,
193 if a call to tcp_write() has failed because memory wasn't available,
194 the application may use the polling functionality to call tcp_write()
195 again when the connection has been idle for a while.
197 - void tcp_poll(struct tcp_pcb *pcb, u8_t interval,
198 err_t (* poll)(void *arg, struct tcp_pcb *tpcb))
200 Specifies the polling interval and the callback function that should
201 be called to poll the application. The interval is specified in
202 number of TCP coarse grained timer shots, which typically occurs
203 twice a second. An interval of 10 means that the application would
204 be polled every 5 seconds.
207 --- Closing and aborting connections
209 - err_t tcp_close(struct tcp_pcb *pcb)
211 Closes the connection. The function may return ERR_MEM if no memory
212 was available for closing the connection. If so, the application
213 should wait and try again either by using the acknowledgment
214 callback or the polling functionality. If the close succeeds, the
215 function returns ERR_OK.
217 The pcb is deallocated by the TCP code after a call to tcp_close().
219 - void tcp_abort(struct tcp_pcb *pcb)
221 Aborts the connection by sending a RST (reset) segment to the remote
222 host. The pcb is deallocated. This function never fails.
224 If a connection is aborted because of an error, the application is
225 alerted of this event by the err callback. Errors that might abort a
226 connection are when there is a shortage of memory. The callback
227 function to be called is set using the tcp_err() function.
229 - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,
232 The error callback function does not get the pcb passed to it as a
233 parameter since the pcb may already have been deallocated.
236 --- Lower layer TCP interface
238 TCP provides a simple interface to the lower layers of the
239 system. During system initialization, the function tcp_init() has
240 to be called before any other TCP function is called. When the system
241 is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
242 must be called with regular intervals. The tcp_fasttmr() should be
243 called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
244 tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
249 The UDP interface is similar to that of TCP, but due to the lower
250 level of complexity of UDP, the interface is significantly simpler.
252 - struct udp_pcb *udp_new(void)
254 Creates a new UDP pcb which can be used for UDP communication. The
255 pcb is not active until it has either been bound to a local address
256 or connected to a remote address.
258 - void udp_remove(struct udp_pcb *pcb)
260 Removes and deallocates the pcb.
262 - err_t udp_bind(struct udp_pcb *pcb, struct ip_addr *ipaddr,
265 Binds the pcb to a local address. The IP-address argument "ipaddr"
266 can be IP_ADDR_ANY to indicate that it should listen to any local IP
267 address. The function currently always return ERR_OK.
269 - err_t udp_connect(struct udp_pcb *pcb, struct ip_addr *ipaddr,
272 Sets the remote end of the pcb. This function does not generate any
273 network traffic, but only set the remote address of the pcb.
275 - err_t udp_disconnect(struct udp_pcb *pcb)
277 Remove the remote end of the pcb. This function does not generate
278 any network traffic, but only removes the remote address of the pcb.
280 - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
282 Sends the pbuf p. The pbuf is not deallocated.
284 - void udp_recv(struct udp_pcb *pcb,
285 void (* recv)(void *arg, struct udp_pcb *upcb,
287 struct ip_addr *addr,
291 Specifies a callback function that should be called when a UDP
292 datagram is received.
295 --- System initalization
297 A truly complete and generic sequence for initializing the lwip stack
298 cannot be given because it depends on the build configuration (lwipopts.h)
299 and additional initializations for your runtime environment (e.g. timers).
301 We can give you some idea on how to proceed when using the raw API.
302 We assume a configuration using a single Ethernet netif and the
303 UDP and TCP transport layers, IPv4 and the DHCP client.
305 Call these functions in the order of appearance:
309 Clears the structure where runtime statistics are gathered.
313 Not of much use since we set the NO_SYS 1 option in lwipopts.h,
314 to be called for easy configuration changes.
318 Initializes the dynamic memory heap defined by MEM_SIZE.
322 Initializes the memory pools defined by MEMP_NUM_x.
326 Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
330 Initializes the ARP table and queue.
331 Note: you must call etharp_tmr at a 10 second regular interval
332 after this initialization.
336 Doesn't do much, it should be called to handle future changes.
340 Clears the UDP PCB list.
344 Clears the TCP PCB list and clears some internal TCP timers.
345 Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
346 predefined regular intervals after this initialization.
348 - netif_add(struct netif *netif, struct ip_addr *ipaddr,
349 struct ip_addr *netmask, struct ip_addr *gw,
350 void *state, err_t (* init)(struct netif *netif),
351 err_t (* input)(struct pbuf *p, struct netif *netif))
353 Adds your network interface to the netif_list. Allocate a struct
354 netif and pass a pointer to this structure as the first argument.
355 Give pointers to cleared ip_addr structures when using DHCP,
356 or fill them with sane numbers otherwise. The state pointer may be NULL.
358 The init function pointer must point to a initialization function for
359 your ethernet netif interface. The following code illustrates it's use.
361 err_t netif_if_init(struct netif *netif)
365 for(i = 0; i < 6; i++) netif->hwaddr[i] = some_eth_addr[i];
366 init_my_eth_device();
370 The input function pointer must point to the lwip ip_input().
372 - netif_set_default(struct netif *netif)
374 Registers the default network interface.
376 - netif_set_up(struct netif *netif)
378 When the netif is fully configured this function must be called.
380 - dhcp_start(struct netif *netif)
382 Creates a new DHCP client for this interface on the first call.
383 Note: you must call dhcp_fine_tmr() and dhcp_coarse_tmr() at
384 the predefined regular intervals after starting the client.
386 You can peek in the netif->dhcp struct for the actual DHCP status.