Travis Geiselbrecht | 1d0df69 | 2008-09-01 02:26:09 -0700 | [diff] [blame^] | 1 | Raw TCP/IP interface for lwIP |
| 2 | |
| 3 | Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons |
| 4 | |
| 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. |
| 9 | |
| 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 |
| 15 | contexts (threads). |
| 16 | |
| 17 | ** The remainder of this document discusses the "raw" API. ** |
| 18 | |
| 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 |
| 25 | on the application. |
| 26 | |
| 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. |
| 33 | |
| 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. |
| 37 | |
| 38 | --- Callbacks |
| 39 | |
| 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. |
| 46 | |
| 47 | The function for setting the application connection state is: |
| 48 | |
| 49 | - void tcp_arg(struct tcp_pcb *pcb, void *arg) |
| 50 | |
| 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. |
| 55 | |
| 56 | |
| 57 | --- TCP connection setup |
| 58 | |
| 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. |
| 64 | |
| 65 | - struct tcp_pcb *tcp_new(void) |
| 66 | |
| 67 | Creates a new connection identifier (PCB). If memory is not |
| 68 | available for creating the new pcb, NULL is returned. |
| 69 | |
| 70 | - err_t tcp_bind(struct tcp_pcb *pcb, struct ip_addr *ipaddr, |
| 71 | u16_t port) |
| 72 | |
| 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. |
| 76 | |
| 77 | If another connection is bound to the same port, the function will |
| 78 | return ERR_USE, otherwise ERR_OK is returned. |
| 79 | |
| 80 | - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb) |
| 81 | |
| 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. |
| 86 | |
| 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. |
| 93 | |
| 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. |
| 97 | |
| 98 | - void tcp_accept(struct tcp_pcb *pcb, |
| 99 | err_t (* accept)(void *arg, struct tcp_pcb *newpcb, |
| 100 | err_t err)) |
| 101 | |
| 102 | Specified the callback function that should be called when a new |
| 103 | connection arrives on a listening connection. |
| 104 | |
| 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, |
| 108 | err_t err)); |
| 109 | |
| 110 | Sets up the pcb to connect to the remote host and sends the |
| 111 | initial SYN segment which opens the connection. |
| 112 | |
| 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. |
| 120 | |
| 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. |
| 124 | |
| 125 | |
| 126 | --- Sending TCP data |
| 127 | |
| 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 |
| 131 | callback function. |
| 132 | |
| 133 | - err_t tcp_write(struct tcp_pcb *pcb, void *dataptr, u16_t len, |
| 134 | u8_t copy) |
| 135 | |
| 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 |
| 141 | pointer. |
| 142 | |
| 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. |
| 148 | |
| 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. |
| 153 | |
| 154 | - void tcp_sent(struct tcp_pcb *pcb, |
| 155 | err_t (* sent)(void *arg, struct tcp_pcb *tpcb, |
| 156 | u16_t len)) |
| 157 | |
| 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. |
| 162 | |
| 163 | |
| 164 | --- Receiving TCP data |
| 165 | |
| 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 |
| 170 | window. |
| 171 | |
| 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)) |
| 175 | |
| 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. |
| 179 | |
| 180 | - void tcp_recved(struct tcp_pcb *pcb, u16_t len) |
| 181 | |
| 182 | Must be called when the application has received the data. The len |
| 183 | argument indicates the length of the received data. |
| 184 | |
| 185 | |
| 186 | --- Application polling |
| 187 | |
| 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. |
| 196 | |
| 197 | - void tcp_poll(struct tcp_pcb *pcb, u8_t interval, |
| 198 | err_t (* poll)(void *arg, struct tcp_pcb *tpcb)) |
| 199 | |
| 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. |
| 205 | |
| 206 | |
| 207 | --- Closing and aborting connections |
| 208 | |
| 209 | - err_t tcp_close(struct tcp_pcb *pcb) |
| 210 | |
| 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. |
| 216 | |
| 217 | The pcb is deallocated by the TCP code after a call to tcp_close(). |
| 218 | |
| 219 | - void tcp_abort(struct tcp_pcb *pcb) |
| 220 | |
| 221 | Aborts the connection by sending a RST (reset) segment to the remote |
| 222 | host. The pcb is deallocated. This function never fails. |
| 223 | |
| 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. |
| 228 | |
| 229 | - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg, |
| 230 | err_t err)) |
| 231 | |
| 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. |
| 234 | |
| 235 | |
| 236 | --- Lower layer TCP interface |
| 237 | |
| 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. |
| 245 | |
| 246 | |
| 247 | --- UDP interface |
| 248 | |
| 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. |
| 251 | |
| 252 | - struct udp_pcb *udp_new(void) |
| 253 | |
| 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. |
| 257 | |
| 258 | - void udp_remove(struct udp_pcb *pcb) |
| 259 | |
| 260 | Removes and deallocates the pcb. |
| 261 | |
| 262 | - err_t udp_bind(struct udp_pcb *pcb, struct ip_addr *ipaddr, |
| 263 | u16_t port) |
| 264 | |
| 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. |
| 268 | |
| 269 | - err_t udp_connect(struct udp_pcb *pcb, struct ip_addr *ipaddr, |
| 270 | u16_t port) |
| 271 | |
| 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. |
| 274 | |
| 275 | - err_t udp_disconnect(struct udp_pcb *pcb) |
| 276 | |
| 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. |
| 279 | |
| 280 | - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p) |
| 281 | |
| 282 | Sends the pbuf p. The pbuf is not deallocated. |
| 283 | |
| 284 | - void udp_recv(struct udp_pcb *pcb, |
| 285 | void (* recv)(void *arg, struct udp_pcb *upcb, |
| 286 | struct pbuf *p, |
| 287 | struct ip_addr *addr, |
| 288 | u16_t port), |
| 289 | void *recv_arg) |
| 290 | |
| 291 | Specifies a callback function that should be called when a UDP |
| 292 | datagram is received. |
| 293 | |
| 294 | |
| 295 | --- System initalization |
| 296 | |
| 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). |
| 300 | |
| 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. |
| 304 | |
| 305 | Call these functions in the order of appearance: |
| 306 | |
| 307 | - stats_init() |
| 308 | |
| 309 | Clears the structure where runtime statistics are gathered. |
| 310 | |
| 311 | - sys_init() |
| 312 | |
| 313 | Not of much use since we set the NO_SYS 1 option in lwipopts.h, |
| 314 | to be called for easy configuration changes. |
| 315 | |
| 316 | - mem_init() |
| 317 | |
| 318 | Initializes the dynamic memory heap defined by MEM_SIZE. |
| 319 | |
| 320 | - memp_init() |
| 321 | |
| 322 | Initializes the memory pools defined by MEMP_NUM_x. |
| 323 | |
| 324 | - pbuf_init() |
| 325 | |
| 326 | Initializes the pbuf memory pool defined by PBUF_POOL_SIZE. |
| 327 | |
| 328 | - etharp_init() |
| 329 | |
| 330 | Initializes the ARP table and queue. |
| 331 | Note: you must call etharp_tmr at a 10 second regular interval |
| 332 | after this initialization. |
| 333 | |
| 334 | - ip_init() |
| 335 | |
| 336 | Doesn't do much, it should be called to handle future changes. |
| 337 | |
| 338 | - udp_init() |
| 339 | |
| 340 | Clears the UDP PCB list. |
| 341 | |
| 342 | - tcp_init() |
| 343 | |
| 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. |
| 347 | |
| 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)) |
| 352 | |
| 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. |
| 357 | |
| 358 | The init function pointer must point to a initialization function for |
| 359 | your ethernet netif interface. The following code illustrates it's use. |
| 360 | |
| 361 | err_t netif_if_init(struct netif *netif) |
| 362 | { |
| 363 | u8_t i; |
| 364 | |
| 365 | for(i = 0; i < 6; i++) netif->hwaddr[i] = some_eth_addr[i]; |
| 366 | init_my_eth_device(); |
| 367 | return ERR_OK; |
| 368 | } |
| 369 | |
| 370 | The input function pointer must point to the lwip ip_input(). |
| 371 | |
| 372 | - netif_set_default(struct netif *netif) |
| 373 | |
| 374 | Registers the default network interface. |
| 375 | |
| 376 | - netif_set_up(struct netif *netif) |
| 377 | |
| 378 | When the netif is fully configured this function must be called. |
| 379 | |
| 380 | - dhcp_start(struct netif *netif) |
| 381 | |
| 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. |
| 385 | |
| 386 | You can peek in the netif->dhcp struct for the actual DHCP status. |