Genadi Zawidowski / lwip

lwip-1.4.1 (partial)

Dependents:   IGLOO_board

lwip-1_4_1/doc/rawapi.txt@1:119c4f7144c8, 2018-07-24 (annotated)

Committer:
ua1arn
Date:
Tue Jul 24 17:36:01 2018 +0000
Revision:
1:119c4f7144c8
Parent:
0:c2ca3c5ded62 
lwip 1.4.1 with necessary servers

Who changed what in which revision?

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