Daniel Vizcaya / Mbed OS 04_RTOS_Embebidos

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

mbed-os/features/FEATURE_LWIP/lwip-interface/lwip/doc/rawapi.txt@0:6ad07c9019fd, 2018-05-30 (annotated)

Committer:
Bethory
Date:
Wed May 30 00:01:50 2018 +0000
Revision:
0:6ad07c9019fd
Codigo de tales para todos los pasculaes

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Bethory 0:6ad07c9019fd 1 Raw TCP/IP interface for lwIP
Bethory 0:6ad07c9019fd 2
Bethory 0:6ad07c9019fd 3 Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
Bethory 0:6ad07c9019fd 4
Bethory 0:6ad07c9019fd 5 lwIP provides three Application Program's Interfaces (APIs) for programs
Bethory 0:6ad07c9019fd 6 to use for communication with the TCP/IP code:
Bethory 0:6ad07c9019fd 7 * low-level "core" / "callback" or "raw" API.
Bethory 0:6ad07c9019fd 8 * higher-level "sequential" API.
Bethory 0:6ad07c9019fd 9 * BSD-style socket API.
Bethory 0:6ad07c9019fd 10
Bethory 0:6ad07c9019fd 11 The raw API (sometimes called native API) is an event-driven API designed
Bethory 0:6ad07c9019fd 12 to be used without an operating system that implements zero-copy send and
Bethory 0:6ad07c9019fd 13 receive. This API is also used by the core stack for interaction between
Bethory 0:6ad07c9019fd 14 the various protocols. It is the only API available when running lwIP
Bethory 0:6ad07c9019fd 15 without an operating system.
Bethory 0:6ad07c9019fd 16
Bethory 0:6ad07c9019fd 17 The sequential API provides a way for ordinary, sequential, programs
Bethory 0:6ad07c9019fd 18 to use the lwIP stack. It is quite similar to the BSD socket API. The
Bethory 0:6ad07c9019fd 19 model of execution is based on the blocking open-read-write-close
Bethory 0:6ad07c9019fd 20 paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
Bethory 0:6ad07c9019fd 21 code and the application program must reside in different execution
Bethory 0:6ad07c9019fd 22 contexts (threads).
Bethory 0:6ad07c9019fd 23
Bethory 0:6ad07c9019fd 24 The socket API is a compatibility API for existing applications,
Bethory 0:6ad07c9019fd 25 currently it is built on top of the sequential API. It is meant to
Bethory 0:6ad07c9019fd 26 provide all functions needed to run socket API applications running
Bethory 0:6ad07c9019fd 27 on other platforms (e.g. unix / windows etc.). However, due to limitations
Bethory 0:6ad07c9019fd 28 in the specification of this API, there might be incompatibilities
Bethory 0:6ad07c9019fd 29 that require small modifications of existing programs.
Bethory 0:6ad07c9019fd 30
Bethory 0:6ad07c9019fd 31 ** Multithreading
Bethory 0:6ad07c9019fd 32
Bethory 0:6ad07c9019fd 33 lwIP started targeting single-threaded environments. When adding multi-
Bethory 0:6ad07c9019fd 34 threading support, instead of making the core thread-safe, another
Bethory 0:6ad07c9019fd 35 approach was chosen: there is one main thread running the lwIP core
Bethory 0:6ad07c9019fd 36 (also known as the "tcpip_thread"). When running in a multithreaded
Bethory 0:6ad07c9019fd 37 environment, raw API functions MUST only be called from the core thread
Bethory 0:6ad07c9019fd 38 since raw API functions are not protected from concurrent access (aside
Bethory 0:6ad07c9019fd 39 from pbuf- and memory management functions). Application threads using
Bethory 0:6ad07c9019fd 40 the sequential- or socket API communicate with this main thread through
Bethory 0:6ad07c9019fd 41 message passing.
Bethory 0:6ad07c9019fd 42
Bethory 0:6ad07c9019fd 43 As such, the list of functions that may be called from
Bethory 0:6ad07c9019fd 44 other threads or an ISR is very limited! Only functions
Bethory 0:6ad07c9019fd 45 from these API header files are thread-safe:
Bethory 0:6ad07c9019fd 46 - api.h
Bethory 0:6ad07c9019fd 47 - netbuf.h
Bethory 0:6ad07c9019fd 48 - netdb.h
Bethory 0:6ad07c9019fd 49 - netifapi.h
Bethory 0:6ad07c9019fd 50 - pppapi.h
Bethory 0:6ad07c9019fd 51 - sockets.h
Bethory 0:6ad07c9019fd 52 - sys.h
Bethory 0:6ad07c9019fd 53
Bethory 0:6ad07c9019fd 54 Additionaly, memory (de-)allocation functions may be
Bethory 0:6ad07c9019fd 55 called from multiple threads (not ISR!) with NO_SYS=0
Bethory 0:6ad07c9019fd 56 since they are protected by SYS_LIGHTWEIGHT_PROT and/or
Bethory 0:6ad07c9019fd 57 semaphores.
Bethory 0:6ad07c9019fd 58
Bethory 0:6ad07c9019fd 59 Netconn or Socket API functions are thread safe against the
Bethory 0:6ad07c9019fd 60 core thread but they are not reentrant at the control block
Bethory 0:6ad07c9019fd 61 granularity level. That is, a UDP or TCP control block must
Bethory 0:6ad07c9019fd 62 not be shared among multiple threads without proper locking.
Bethory 0:6ad07c9019fd 63
Bethory 0:6ad07c9019fd 64 If SYS_LIGHTWEIGHT_PROT is set to 1 and
Bethory 0:6ad07c9019fd 65 LWIP_ALLOW_MEM_FREE_FROM_OTHER_CONTEXT is set to 1,
Bethory 0:6ad07c9019fd 66 pbuf_free() may also be called from another thread or
Bethory 0:6ad07c9019fd 67 an ISR (since only then, mem_free - for PBUF_RAM - may
Bethory 0:6ad07c9019fd 68 be called from an ISR: otherwise, the HEAP is only
Bethory 0:6ad07c9019fd 69 protected by semaphores).
Bethory 0:6ad07c9019fd 70
Bethory 0:6ad07c9019fd 71
Bethory 0:6ad07c9019fd 72 ** The remainder of this document discusses the "raw" API. **
Bethory 0:6ad07c9019fd 73
Bethory 0:6ad07c9019fd 74 The raw TCP/IP interface allows the application program to integrate
Bethory 0:6ad07c9019fd 75 better with the TCP/IP code. Program execution is event based by
Bethory 0:6ad07c9019fd 76 having callback functions being called from within the TCP/IP
Bethory 0:6ad07c9019fd 77 code. The TCP/IP code and the application program both run in the same
Bethory 0:6ad07c9019fd 78 thread. The sequential API has a much higher overhead and is not very
Bethory 0:6ad07c9019fd 79 well suited for small systems since it forces a multithreaded paradigm
Bethory 0:6ad07c9019fd 80 on the application.
Bethory 0:6ad07c9019fd 81
Bethory 0:6ad07c9019fd 82 The raw TCP/IP interface is not only faster in terms of code execution
Bethory 0:6ad07c9019fd 83 time but is also less memory intensive. The drawback is that program
Bethory 0:6ad07c9019fd 84 development is somewhat harder and application programs written for
Bethory 0:6ad07c9019fd 85 the raw TCP/IP interface are more difficult to understand. Still, this
Bethory 0:6ad07c9019fd 86 is the preferred way of writing applications that should be small in
Bethory 0:6ad07c9019fd 87 code size and memory usage.
Bethory 0:6ad07c9019fd 88
Bethory 0:6ad07c9019fd 89 All APIs can be used simultaneously by different application
Bethory 0:6ad07c9019fd 90 programs. In fact, the sequential API is implemented as an application
Bethory 0:6ad07c9019fd 91 program using the raw TCP/IP interface.
Bethory 0:6ad07c9019fd 92
Bethory 0:6ad07c9019fd 93 Do not confuse the lwIP raw API with raw Ethernet or IP sockets.
Bethory 0:6ad07c9019fd 94 The former is a way of interfacing the lwIP network stack (including
Bethory 0:6ad07c9019fd 95 TCP and UDP), the later refers to processing raw Ethernet or IP data
Bethory 0:6ad07c9019fd 96 instead of TCP connections or UDP packets.
Bethory 0:6ad07c9019fd 97
Bethory 0:6ad07c9019fd 98 Raw API applications may never block since all packet processing
Bethory 0:6ad07c9019fd 99 (input and output) as well as timer processing (TCP mainly) is done
Bethory 0:6ad07c9019fd 100 in a single execution context.
Bethory 0:6ad07c9019fd 101
Bethory 0:6ad07c9019fd 102 --- Callbacks
Bethory 0:6ad07c9019fd 103
Bethory 0:6ad07c9019fd 104 Program execution is driven by callbacks functions, which are then
Bethory 0:6ad07c9019fd 105 invoked by the lwIP core when activity related to that application
Bethory 0:6ad07c9019fd 106 occurs. A particular application may register to be notified via a
Bethory 0:6ad07c9019fd 107 callback function for events such as incoming data available, outgoing
Bethory 0:6ad07c9019fd 108 data sent, error notifications, poll timer expiration, connection
Bethory 0:6ad07c9019fd 109 closed, etc. An application can provide a callback function to perform
Bethory 0:6ad07c9019fd 110 processing for any or all of these events. Each callback is an ordinary
Bethory 0:6ad07c9019fd 111 C function that is called from within the TCP/IP code. Every callback
Bethory 0:6ad07c9019fd 112 function is passed the current TCP or UDP connection state as an
Bethory 0:6ad07c9019fd 113 argument. Also, in order to be able to keep program specific state,
Bethory 0:6ad07c9019fd 114 the callback functions are called with a program specified argument
Bethory 0:6ad07c9019fd 115 that is independent of the TCP/IP state.
Bethory 0:6ad07c9019fd 116
Bethory 0:6ad07c9019fd 117 The function for setting the application connection state is:
Bethory 0:6ad07c9019fd 118
Bethory 0:6ad07c9019fd 119 - void tcp_arg(struct tcp_pcb *pcb, void *arg)
Bethory 0:6ad07c9019fd 120
Bethory 0:6ad07c9019fd 121 Specifies the program specific state that should be passed to all
Bethory 0:6ad07c9019fd 122 other callback functions. The "pcb" argument is the current TCP
Bethory 0:6ad07c9019fd 123 connection control block, and the "arg" argument is the argument
Bethory 0:6ad07c9019fd 124 that will be passed to the callbacks.
Bethory 0:6ad07c9019fd 125
Bethory 0:6ad07c9019fd 126
Bethory 0:6ad07c9019fd 127 --- TCP connection setup
Bethory 0:6ad07c9019fd 128
Bethory 0:6ad07c9019fd 129 The functions used for setting up connections is similar to that of
Bethory 0:6ad07c9019fd 130 the sequential API and of the BSD socket API. A new TCP connection
Bethory 0:6ad07c9019fd 131 identifier (i.e., a protocol control block - PCB) is created with the
Bethory 0:6ad07c9019fd 132 tcp_new() function. This PCB can then be either set to listen for new
Bethory 0:6ad07c9019fd 133 incoming connections or be explicitly connected to another host.
Bethory 0:6ad07c9019fd 134
Bethory 0:6ad07c9019fd 135 - struct tcp_pcb *tcp_new(void)
Bethory 0:6ad07c9019fd 136
Bethory 0:6ad07c9019fd 137 Creates a new connection identifier (PCB). If memory is not
Bethory 0:6ad07c9019fd 138 available for creating the new pcb, NULL is returned.
Bethory 0:6ad07c9019fd 139
Bethory 0:6ad07c9019fd 140 - err_t tcp_bind(struct tcp_pcb *pcb, ip_addr_t *ipaddr,
Bethory 0:6ad07c9019fd 141 u16_t port)
Bethory 0:6ad07c9019fd 142
Bethory 0:6ad07c9019fd 143 Binds the pcb to a local IP address and port number. The IP address
Bethory 0:6ad07c9019fd 144 can be specified as IP_ADDR_ANY in order to bind the connection to
Bethory 0:6ad07c9019fd 145 all local IP addresses.
Bethory 0:6ad07c9019fd 146
Bethory 0:6ad07c9019fd 147 If another connection is bound to the same port, the function will
Bethory 0:6ad07c9019fd 148 return ERR_USE, otherwise ERR_OK is returned.
Bethory 0:6ad07c9019fd 149
Bethory 0:6ad07c9019fd 150 - struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
Bethory 0:6ad07c9019fd 151
Bethory 0:6ad07c9019fd 152 Commands a pcb to start listening for incoming connections. When an
Bethory 0:6ad07c9019fd 153 incoming connection is accepted, the function specified with the
Bethory 0:6ad07c9019fd 154 tcp_accept() function will be called. The pcb will have to be bound
Bethory 0:6ad07c9019fd 155 to a local port with the tcp_bind() function.
Bethory 0:6ad07c9019fd 156
Bethory 0:6ad07c9019fd 157 The tcp_listen() function returns a new connection identifier, and
Bethory 0:6ad07c9019fd 158 the one passed as an argument to the function will be
Bethory 0:6ad07c9019fd 159 deallocated. The reason for this behavior is that less memory is
Bethory 0:6ad07c9019fd 160 needed for a connection that is listening, so tcp_listen() will
Bethory 0:6ad07c9019fd 161 reclaim the memory needed for the original connection and allocate a
Bethory 0:6ad07c9019fd 162 new smaller memory block for the listening connection.
Bethory 0:6ad07c9019fd 163
Bethory 0:6ad07c9019fd 164 tcp_listen() may return NULL if no memory was available for the
Bethory 0:6ad07c9019fd 165 listening connection. If so, the memory associated with the pcb
Bethory 0:6ad07c9019fd 166 passed as an argument to tcp_listen() will not be deallocated.
Bethory 0:6ad07c9019fd 167
Bethory 0:6ad07c9019fd 168 - struct tcp_pcb *tcp_listen_with_backlog(struct tcp_pcb *pcb, u8_t backlog)
Bethory 0:6ad07c9019fd 169
Bethory 0:6ad07c9019fd 170 Same as tcp_listen, but limits the number of outstanding connections
Bethory 0:6ad07c9019fd 171 in the listen queue to the value specified by the backlog argument.
Bethory 0:6ad07c9019fd 172 To use it, your need to set TCP_LISTEN_BACKLOG=1 in your lwipopts.h.
Bethory 0:6ad07c9019fd 173
Bethory 0:6ad07c9019fd 174 - void tcp_accept(struct tcp_pcb *pcb,
Bethory 0:6ad07c9019fd 175 err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
Bethory 0:6ad07c9019fd 176 err_t err))
Bethory 0:6ad07c9019fd 177
Bethory 0:6ad07c9019fd 178 Specified the callback function that should be called when a new
Bethory 0:6ad07c9019fd 179 connection arrives on a listening connection.
Bethory 0:6ad07c9019fd 180
Bethory 0:6ad07c9019fd 181 - err_t tcp_connect(struct tcp_pcb *pcb, ip_addr_t *ipaddr,
Bethory 0:6ad07c9019fd 182 u16_t port, err_t (* connected)(void *arg,
Bethory 0:6ad07c9019fd 183 struct tcp_pcb *tpcb,
Bethory 0:6ad07c9019fd 184 err_t err));
Bethory 0:6ad07c9019fd 185
Bethory 0:6ad07c9019fd 186 Sets up the pcb to connect to the remote host and sends the
Bethory 0:6ad07c9019fd 187 initial SYN segment which opens the connection.
Bethory 0:6ad07c9019fd 188
Bethory 0:6ad07c9019fd 189 The tcp_connect() function returns immediately; it does not wait for
Bethory 0:6ad07c9019fd 190 the connection to be properly setup. Instead, it will call the
Bethory 0:6ad07c9019fd 191 function specified as the fourth argument (the "connected" argument)
Bethory 0:6ad07c9019fd 192 when the connection is established. If the connection could not be
Bethory 0:6ad07c9019fd 193 properly established, either because the other host refused the
Bethory 0:6ad07c9019fd 194 connection or because the other host didn't answer, the "err"
Bethory 0:6ad07c9019fd 195 callback function of this pcb (registered with tcp_err, see below)
Bethory 0:6ad07c9019fd 196 will be called.
Bethory 0:6ad07c9019fd 197
Bethory 0:6ad07c9019fd 198 The tcp_connect() function can return ERR_MEM if no memory is
Bethory 0:6ad07c9019fd 199 available for enqueueing the SYN segment. If the SYN indeed was
Bethory 0:6ad07c9019fd 200 enqueued successfully, the tcp_connect() function returns ERR_OK.
Bethory 0:6ad07c9019fd 201
Bethory 0:6ad07c9019fd 202
Bethory 0:6ad07c9019fd 203 --- Sending TCP data
Bethory 0:6ad07c9019fd 204
Bethory 0:6ad07c9019fd 205 TCP data is sent by enqueueing the data with a call to
Bethory 0:6ad07c9019fd 206 tcp_write(). When the data is successfully transmitted to the remote
Bethory 0:6ad07c9019fd 207 host, the application will be notified with a call to a specified
Bethory 0:6ad07c9019fd 208 callback function.
Bethory 0:6ad07c9019fd 209
Bethory 0:6ad07c9019fd 210 - err_t tcp_write(struct tcp_pcb *pcb, const void *dataptr, u16_t len,
Bethory 0:6ad07c9019fd 211 u8_t apiflags)
Bethory 0:6ad07c9019fd 212
Bethory 0:6ad07c9019fd 213 Enqueues the data pointed to by the argument dataptr. The length of
Bethory 0:6ad07c9019fd 214 the data is passed as the len parameter. The apiflags can be one or more of:
Bethory 0:6ad07c9019fd 215 - TCP_WRITE_FLAG_COPY: indicates whether the new memory should be allocated
Bethory 0:6ad07c9019fd 216 for the data to be copied into. If this flag is not given, no new memory
Bethory 0:6ad07c9019fd 217 should be allocated and the data should only be referenced by pointer. This
Bethory 0:6ad07c9019fd 218 also means that the memory behind dataptr must not change until the data is
Bethory 0:6ad07c9019fd 219 ACKed by the remote host
Bethory 0:6ad07c9019fd 220 - TCP_WRITE_FLAG_MORE: indicates that more data follows. If this is omitted,
Bethory 0:6ad07c9019fd 221 the PSH flag is set in the last segment created by this call to tcp_write.
Bethory 0:6ad07c9019fd 222 If this flag is given, the PSH flag is not set.
Bethory 0:6ad07c9019fd 223
Bethory 0:6ad07c9019fd 224 The tcp_write() function will fail and return ERR_MEM if the length
Bethory 0:6ad07c9019fd 225 of the data exceeds the current send buffer size or if the length of
Bethory 0:6ad07c9019fd 226 the queue of outgoing segment is larger than the upper limit defined
Bethory 0:6ad07c9019fd 227 in lwipopts.h. The number of bytes available in the output queue can
Bethory 0:6ad07c9019fd 228 be retrieved with the tcp_sndbuf() function.
Bethory 0:6ad07c9019fd 229
Bethory 0:6ad07c9019fd 230 The proper way to use this function is to call the function with at
Bethory 0:6ad07c9019fd 231 most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
Bethory 0:6ad07c9019fd 232 the application should wait until some of the currently enqueued
Bethory 0:6ad07c9019fd 233 data has been successfully received by the other host and try again.
Bethory 0:6ad07c9019fd 234
Bethory 0:6ad07c9019fd 235 - void tcp_sent(struct tcp_pcb *pcb,
Bethory 0:6ad07c9019fd 236 err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
Bethory 0:6ad07c9019fd 237 u16_t len))
Bethory 0:6ad07c9019fd 238
Bethory 0:6ad07c9019fd 239 Specifies the callback function that should be called when data has
Bethory 0:6ad07c9019fd 240 successfully been received (i.e., acknowledged) by the remote
Bethory 0:6ad07c9019fd 241 host. The len argument passed to the callback function gives the
Bethory 0:6ad07c9019fd 242 amount bytes that was acknowledged by the last acknowledgment.
Bethory 0:6ad07c9019fd 243
Bethory 0:6ad07c9019fd 244
Bethory 0:6ad07c9019fd 245 --- Receiving TCP data
Bethory 0:6ad07c9019fd 246
Bethory 0:6ad07c9019fd 247 TCP data reception is callback based - an application specified
Bethory 0:6ad07c9019fd 248 callback function is called when new data arrives. When the
Bethory 0:6ad07c9019fd 249 application has taken the data, it has to call the tcp_recved()
Bethory 0:6ad07c9019fd 250 function to indicate that TCP can advertise increase the receive
Bethory 0:6ad07c9019fd 251 window.
Bethory 0:6ad07c9019fd 252
Bethory 0:6ad07c9019fd 253 - void tcp_recv(struct tcp_pcb *pcb,
Bethory 0:6ad07c9019fd 254 err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
Bethory 0:6ad07c9019fd 255 struct pbuf *p, err_t err))
Bethory 0:6ad07c9019fd 256
Bethory 0:6ad07c9019fd 257 Sets the callback function that will be called when new data
Bethory 0:6ad07c9019fd 258 arrives. The callback function will be passed a NULL pbuf to
Bethory 0:6ad07c9019fd 259 indicate that the remote host has closed the connection. If
Bethory 0:6ad07c9019fd 260 there are no errors and the callback function is to return
Bethory 0:6ad07c9019fd 261 ERR_OK, then it must free the pbuf. Otherwise, it must not
Bethory 0:6ad07c9019fd 262 free the pbuf so that lwIP core code can store it.
Bethory 0:6ad07c9019fd 263
Bethory 0:6ad07c9019fd 264 - void tcp_recved(struct tcp_pcb *pcb, u16_t len)
Bethory 0:6ad07c9019fd 265
Bethory 0:6ad07c9019fd 266 Must be called when the application has received the data. The len
Bethory 0:6ad07c9019fd 267 argument indicates the length of the received data.
Bethory 0:6ad07c9019fd 268
Bethory 0:6ad07c9019fd 269
Bethory 0:6ad07c9019fd 270 --- Application polling
Bethory 0:6ad07c9019fd 271
Bethory 0:6ad07c9019fd 272 When a connection is idle (i.e., no data is either transmitted or
Bethory 0:6ad07c9019fd 273 received), lwIP will repeatedly poll the application by calling a
Bethory 0:6ad07c9019fd 274 specified callback function. This can be used either as a watchdog
Bethory 0:6ad07c9019fd 275 timer for killing connections that have stayed idle for too long, or
Bethory 0:6ad07c9019fd 276 as a method of waiting for memory to become available. For instance,
Bethory 0:6ad07c9019fd 277 if a call to tcp_write() has failed because memory wasn't available,
Bethory 0:6ad07c9019fd 278 the application may use the polling functionality to call tcp_write()
Bethory 0:6ad07c9019fd 279 again when the connection has been idle for a while.
Bethory 0:6ad07c9019fd 280
Bethory 0:6ad07c9019fd 281 - void tcp_poll(struct tcp_pcb *pcb,
Bethory 0:6ad07c9019fd 282 err_t (* poll)(void *arg, struct tcp_pcb *tpcb),
Bethory 0:6ad07c9019fd 283 u8_t interval)
Bethory 0:6ad07c9019fd 284
Bethory 0:6ad07c9019fd 285 Specifies the polling interval and the callback function that should
Bethory 0:6ad07c9019fd 286 be called to poll the application. The interval is specified in
Bethory 0:6ad07c9019fd 287 number of TCP coarse grained timer shots, which typically occurs
Bethory 0:6ad07c9019fd 288 twice a second. An interval of 10 means that the application would
Bethory 0:6ad07c9019fd 289 be polled every 5 seconds.
Bethory 0:6ad07c9019fd 290
Bethory 0:6ad07c9019fd 291
Bethory 0:6ad07c9019fd 292 --- Closing and aborting connections
Bethory 0:6ad07c9019fd 293
Bethory 0:6ad07c9019fd 294 - err_t tcp_close(struct tcp_pcb *pcb)
Bethory 0:6ad07c9019fd 295
Bethory 0:6ad07c9019fd 296 Closes the connection. The function may return ERR_MEM if no memory
Bethory 0:6ad07c9019fd 297 was available for closing the connection. If so, the application
Bethory 0:6ad07c9019fd 298 should wait and try again either by using the acknowledgment
Bethory 0:6ad07c9019fd 299 callback or the polling functionality. If the close succeeds, the
Bethory 0:6ad07c9019fd 300 function returns ERR_OK.
Bethory 0:6ad07c9019fd 301
Bethory 0:6ad07c9019fd 302 The pcb is deallocated by the TCP code after a call to tcp_close().
Bethory 0:6ad07c9019fd 303
Bethory 0:6ad07c9019fd 304 - void tcp_abort(struct tcp_pcb *pcb)
Bethory 0:6ad07c9019fd 305
Bethory 0:6ad07c9019fd 306 Aborts the connection by sending a RST (reset) segment to the remote
Bethory 0:6ad07c9019fd 307 host. The pcb is deallocated. This function never fails.
Bethory 0:6ad07c9019fd 308
Bethory 0:6ad07c9019fd 309 ATTENTION: When calling this from one of the TCP callbacks, make
Bethory 0:6ad07c9019fd 310 sure you always return ERR_ABRT (and never return ERR_ABRT otherwise
Bethory 0:6ad07c9019fd 311 or you will risk accessing deallocated memory or memory leaks!
Bethory 0:6ad07c9019fd 312
Bethory 0:6ad07c9019fd 313
Bethory 0:6ad07c9019fd 314 If a connection is aborted because of an error, the application is
Bethory 0:6ad07c9019fd 315 alerted of this event by the err callback. Errors that might abort a
Bethory 0:6ad07c9019fd 316 connection are when there is a shortage of memory. The callback
Bethory 0:6ad07c9019fd 317 function to be called is set using the tcp_err() function.
Bethory 0:6ad07c9019fd 318
Bethory 0:6ad07c9019fd 319 - void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,
Bethory 0:6ad07c9019fd 320 err_t err))
Bethory 0:6ad07c9019fd 321
Bethory 0:6ad07c9019fd 322 The error callback function does not get the pcb passed to it as a
Bethory 0:6ad07c9019fd 323 parameter since the pcb may already have been deallocated.
Bethory 0:6ad07c9019fd 324
Bethory 0:6ad07c9019fd 325
Bethory 0:6ad07c9019fd 326 --- UDP interface
Bethory 0:6ad07c9019fd 327
Bethory 0:6ad07c9019fd 328 The UDP interface is similar to that of TCP, but due to the lower
Bethory 0:6ad07c9019fd 329 level of complexity of UDP, the interface is significantly simpler.
Bethory 0:6ad07c9019fd 330
Bethory 0:6ad07c9019fd 331 - struct udp_pcb *udp_new(void)
Bethory 0:6ad07c9019fd 332
Bethory 0:6ad07c9019fd 333 Creates a new UDP pcb which can be used for UDP communication. The
Bethory 0:6ad07c9019fd 334 pcb is not active until it has either been bound to a local address
Bethory 0:6ad07c9019fd 335 or connected to a remote address.
Bethory 0:6ad07c9019fd 336
Bethory 0:6ad07c9019fd 337 - void udp_remove(struct udp_pcb *pcb)
Bethory 0:6ad07c9019fd 338
Bethory 0:6ad07c9019fd 339 Removes and deallocates the pcb.
Bethory 0:6ad07c9019fd 340
Bethory 0:6ad07c9019fd 341 - err_t udp_bind(struct udp_pcb *pcb, ip_addr_t *ipaddr,
Bethory 0:6ad07c9019fd 342 u16_t port)
Bethory 0:6ad07c9019fd 343
Bethory 0:6ad07c9019fd 344 Binds the pcb to a local address. The IP-address argument "ipaddr"
Bethory 0:6ad07c9019fd 345 can be IP_ADDR_ANY to indicate that it should listen to any local IP
Bethory 0:6ad07c9019fd 346 address. The function currently always return ERR_OK.
Bethory 0:6ad07c9019fd 347
Bethory 0:6ad07c9019fd 348 - err_t udp_connect(struct udp_pcb *pcb, ip_addr_t *ipaddr,
Bethory 0:6ad07c9019fd 349 u16_t port)
Bethory 0:6ad07c9019fd 350
Bethory 0:6ad07c9019fd 351 Sets the remote end of the pcb. This function does not generate any
Bethory 0:6ad07c9019fd 352 network traffic, but only set the remote address of the pcb.
Bethory 0:6ad07c9019fd 353
Bethory 0:6ad07c9019fd 354 - err_t udp_disconnect(struct udp_pcb *pcb)
Bethory 0:6ad07c9019fd 355
Bethory 0:6ad07c9019fd 356 Remove the remote end of the pcb. This function does not generate
Bethory 0:6ad07c9019fd 357 any network traffic, but only removes the remote address of the pcb.
Bethory 0:6ad07c9019fd 358
Bethory 0:6ad07c9019fd 359 - err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
Bethory 0:6ad07c9019fd 360
Bethory 0:6ad07c9019fd 361 Sends the pbuf p. The pbuf is not deallocated.
Bethory 0:6ad07c9019fd 362
Bethory 0:6ad07c9019fd 363 - void udp_recv(struct udp_pcb *pcb,
Bethory 0:6ad07c9019fd 364 void (* recv)(void *arg, struct udp_pcb *upcb,
Bethory 0:6ad07c9019fd 365 struct pbuf *p,
Bethory 0:6ad07c9019fd 366 ip_addr_t *addr,
Bethory 0:6ad07c9019fd 367 u16_t port),
Bethory 0:6ad07c9019fd 368 void *recv_arg)
Bethory 0:6ad07c9019fd 369
Bethory 0:6ad07c9019fd 370 Specifies a callback function that should be called when a UDP
Bethory 0:6ad07c9019fd 371 datagram is received.
Bethory 0:6ad07c9019fd 372
Bethory 0:6ad07c9019fd 373
Bethory 0:6ad07c9019fd 374 --- System initalization
Bethory 0:6ad07c9019fd 375
Bethory 0:6ad07c9019fd 376 A truly complete and generic sequence for initializing the lwIP stack
Bethory 0:6ad07c9019fd 377 cannot be given because it depends on additional initializations for
Bethory 0:6ad07c9019fd 378 your runtime environment (e.g. timers).
Bethory 0:6ad07c9019fd 379
Bethory 0:6ad07c9019fd 380 We can give you some idea on how to proceed when using the raw API.
Bethory 0:6ad07c9019fd 381 We assume a configuration using a single Ethernet netif and the
Bethory 0:6ad07c9019fd 382 UDP and TCP transport layers, IPv4 and the DHCP client.
Bethory 0:6ad07c9019fd 383
Bethory 0:6ad07c9019fd 384 Call these functions in the order of appearance:
Bethory 0:6ad07c9019fd 385
Bethory 0:6ad07c9019fd 386 - lwip_init()
Bethory 0:6ad07c9019fd 387
Bethory 0:6ad07c9019fd 388 Initialize the lwIP stack and all of its subsystems.
Bethory 0:6ad07c9019fd 389
Bethory 0:6ad07c9019fd 390 - netif_add(struct netif *netif, const ip4_addr_t *ipaddr,
Bethory 0:6ad07c9019fd 391 const ip4_addr_t *netmask, const ip4_addr_t *gw,
Bethory 0:6ad07c9019fd 392 void *state, netif_init_fn init, netif_input_fn input)
Bethory 0:6ad07c9019fd 393
Bethory 0:6ad07c9019fd 394 Adds your network interface to the netif_list. Allocate a struct
Bethory 0:6ad07c9019fd 395 netif and pass a pointer to this structure as the first argument.
Bethory 0:6ad07c9019fd 396 Give pointers to cleared ip_addr structures when using DHCP,
Bethory 0:6ad07c9019fd 397 or fill them with sane numbers otherwise. The state pointer may be NULL.
Bethory 0:6ad07c9019fd 398
Bethory 0:6ad07c9019fd 399 The init function pointer must point to a initialization function for
Bethory 0:6ad07c9019fd 400 your Ethernet netif interface. The following code illustrates its use.
Bethory 0:6ad07c9019fd 401
Bethory 0:6ad07c9019fd 402 err_t netif_if_init(struct netif *netif)
Bethory 0:6ad07c9019fd 403 {
Bethory 0:6ad07c9019fd 404 u8_t i;
Bethory 0:6ad07c9019fd 405
Bethory 0:6ad07c9019fd 406 for (i = 0; i < ETHARP_HWADDR_LEN; i++) {
Bethory 0:6ad07c9019fd 407 netif->hwaddr[i] = some_eth_addr[i];
Bethory 0:6ad07c9019fd 408 }
Bethory 0:6ad07c9019fd 409 init_my_eth_device();
Bethory 0:6ad07c9019fd 410 return ERR_OK;
Bethory 0:6ad07c9019fd 411 }
Bethory 0:6ad07c9019fd 412
Bethory 0:6ad07c9019fd 413 For Ethernet drivers, the input function pointer must point to the lwIP
Bethory 0:6ad07c9019fd 414 function ethernet_input() declared in "netif/etharp.h". Other drivers
Bethory 0:6ad07c9019fd 415 must use ip_input() declared in "lwip/ip.h".
Bethory 0:6ad07c9019fd 416
Bethory 0:6ad07c9019fd 417 - netif_set_default(struct netif *netif)
Bethory 0:6ad07c9019fd 418
Bethory 0:6ad07c9019fd 419 Registers the default network interface.
Bethory 0:6ad07c9019fd 420
Bethory 0:6ad07c9019fd 421 - netif_set_link_up(struct netif *netif)
Bethory 0:6ad07c9019fd 422
Bethory 0:6ad07c9019fd 423 This is the hardware link state; e.g. whether cable is plugged for wired
Bethory 0:6ad07c9019fd 424 Ethernet interface. This function must be called even if you don't know
Bethory 0:6ad07c9019fd 425 the current state. Having link up and link down events is optional but
Bethory 0:6ad07c9019fd 426 DHCP and IPv6 discover benefit well from those events.
Bethory 0:6ad07c9019fd 427
Bethory 0:6ad07c9019fd 428 - netif_set_up(struct netif *netif)
Bethory 0:6ad07c9019fd 429
Bethory 0:6ad07c9019fd 430 This is the administrative (= software) state of the netif, when the
Bethory 0:6ad07c9019fd 431 netif is fully configured this function must be called.
Bethory 0:6ad07c9019fd 432
Bethory 0:6ad07c9019fd 433 - dhcp_start(struct netif *netif)
Bethory 0:6ad07c9019fd 434
Bethory 0:6ad07c9019fd 435 Creates a new DHCP client for this interface on the first call.
Bethory 0:6ad07c9019fd 436
Bethory 0:6ad07c9019fd 437 You can peek in the netif->dhcp struct for the actual DHCP status.
Bethory 0:6ad07c9019fd 438
Bethory 0:6ad07c9019fd 439 - sys_check_timeouts()
Bethory 0:6ad07c9019fd 440
Bethory 0:6ad07c9019fd 441 When the system is running, you have to periodically call
Bethory 0:6ad07c9019fd 442 sys_check_timeouts() which will handle all timers for all protocols in
Bethory 0:6ad07c9019fd 443 the stack; add this to your main loop or equivalent.
Bethory 0:6ad07c9019fd 444
Bethory 0:6ad07c9019fd 445
Bethory 0:6ad07c9019fd 446 --- Optimalization hints
Bethory 0:6ad07c9019fd 447
Bethory 0:6ad07c9019fd 448 The first thing you want to optimize is the lwip_standard_checksum()
Bethory 0:6ad07c9019fd 449 routine from src/core/inet.c. You can override this standard
Bethory 0:6ad07c9019fd 450 function with the #define LWIP_CHKSUM <your_checksum_routine>.
Bethory 0:6ad07c9019fd 451
Bethory 0:6ad07c9019fd 452 There are C examples given in inet.c or you might want to
Bethory 0:6ad07c9019fd 453 craft an assembly function for this. RFC1071 is a good
Bethory 0:6ad07c9019fd 454 introduction to this subject.
Bethory 0:6ad07c9019fd 455
Bethory 0:6ad07c9019fd 456 Other significant improvements can be made by supplying
Bethory 0:6ad07c9019fd 457 assembly or inline replacements for htons() and htonl()
Bethory 0:6ad07c9019fd 458 if you're using a little-endian architecture.
Bethory 0:6ad07c9019fd 459 #define lwip_htons(x) <your_htons>
Bethory 0:6ad07c9019fd 460 #define lwip_htonl(x) <your_htonl>
Bethory 0:6ad07c9019fd 461 If you #define them to htons() and htonl(), you should
Bethory 0:6ad07c9019fd 462 #define LWIP_DONT_PROVIDE_BYTEORDER_FUNCTIONS to prevent lwIP from
Bethory 0:6ad07c9019fd 463 defining hton*/ntoh* compatibility macros.
Bethory 0:6ad07c9019fd 464
Bethory 0:6ad07c9019fd 465 Check your network interface driver if it reads at
Bethory 0:6ad07c9019fd 466 a higher speed than the maximum wire-speed. If the
Bethory 0:6ad07c9019fd 467 hardware isn't serviced frequently and fast enough
Bethory 0:6ad07c9019fd 468 buffer overflows are likely to occur.
Bethory 0:6ad07c9019fd 469
Bethory 0:6ad07c9019fd 470 E.g. when using the cs8900 driver, call cs8900if_service(ethif)
Bethory 0:6ad07c9019fd 471 as frequently as possible. When using an RTOS let the cs8900 interrupt
Bethory 0:6ad07c9019fd 472 wake a high priority task that services your driver using a binary
Bethory 0:6ad07c9019fd 473 semaphore or event flag. Some drivers might allow additional tuning
Bethory 0:6ad07c9019fd 474 to match your application and network.
Bethory 0:6ad07c9019fd 475
Bethory 0:6ad07c9019fd 476 For a production release it is recommended to set LWIP_STATS to 0.
Bethory 0:6ad07c9019fd 477 Note that speed performance isn't influenced much by simply setting
Bethory 0:6ad07c9019fd 478 high values to the memory options.
Bethory 0:6ad07c9019fd 479
Bethory 0:6ad07c9019fd 480 For more optimization hints take a look at the lwIP wiki.
Bethory 0:6ad07c9019fd 481
Bethory 0:6ad07c9019fd 482 --- Zero-copy MACs
Bethory 0:6ad07c9019fd 483
Bethory 0:6ad07c9019fd 484 To achieve zero-copy on transmit, the data passed to the raw API must
Bethory 0:6ad07c9019fd 485 remain unchanged until sent. Because the send- (or write-)functions return
Bethory 0:6ad07c9019fd 486 when the packets have been enqueued for sending, data must be kept stable
Bethory 0:6ad07c9019fd 487 after that, too.
Bethory 0:6ad07c9019fd 488
Bethory 0:6ad07c9019fd 489 This implies that PBUF_RAM/PBUF_POOL pbufs passed to raw-API send functions
Bethory 0:6ad07c9019fd 490 must *not* be reused by the application unless their ref-count is 1.
Bethory 0:6ad07c9019fd 491
Bethory 0:6ad07c9019fd 492 For no-copy pbufs (PBUF_ROM/PBUF_REF), data must be kept unchanged, too,
Bethory 0:6ad07c9019fd 493 but the stack/driver will/must copy PBUF_REF'ed data when enqueueing, while
Bethory 0:6ad07c9019fd 494 PBUF_ROM-pbufs are just enqueued (as ROM-data is expected to never change).
Bethory 0:6ad07c9019fd 495
Bethory 0:6ad07c9019fd 496 Also, data passed to tcp_write without the copy-flag must not be changed!
Bethory 0:6ad07c9019fd 497
Bethory 0:6ad07c9019fd 498 Therefore, be careful which type of PBUF you use and if you copy TCP data
Bethory 0:6ad07c9019fd 499 or not!