Daiki Kato / mbed-os-lychee

mbed-os for GR-LYCHEE

Dependents:   mbed-os-example-blinky-gr-lychee GR-Boads_Camera_sample GR-Boards_Audio_Recoder GR-Boads_Camera_DisplayApp ... more

features/FEATURE_LWIP/lwip-interface/lwip/doc/rawapi.txt@0:f782d9c66c49, 2018-02-02 (annotated)

Committer:
dkato
Date:
Fri Feb 02 05:42:23 2018 +0000
Revision:
0:f782d9c66c49
mbed-os for GR-LYCHEE

Who changed what in which revision?

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