Lines Matching full:the
6 to use for communication with the TCP/IP code:
11 The raw API (sometimes called native API) is an event-driven API designed
13 receive. This API is also used by the core stack for interaction between
14 the various protocols. It is the only API available when running lwIP
17 The sequential API provides a way for ordinary, sequential, programs
18 to use the lwIP stack. It is quite similar to the BSD socket API. The
19 model of execution is based on the blocking open-read-write-close
20 paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
21 code and the application program must reside in different execution
24 The socket API is a compatibility API for existing applications,
25 currently it is built on top of the sequential API. It is meant to
28 in the specification of this API, there might be incompatibilities
34 threading support, instead of making the core thread-safe, another
35 approach was chosen: there is one main thread running the lwIP core
36 (also known as the "tcpip_thread"). When running in a multithreaded
37 environment, raw API functions MUST only be called from the core thread
40 the sequential- or socket API communicate with this main thread through
43 As such, the list of functions that may be called from
59 Netconn or Socket API functions are thread safe against the
60 core thread but they are not reentrant at the control block
68 be called from an ISR: otherwise, the HEAP is only
72 ** The remainder of this document discusses the "raw" API. **
74 The raw TCP/IP interface allows the application program to integrate
75 better with the TCP/IP code. Program execution is event based by
76 having callback functions being called from within the TCP/IP
77 code. The TCP/IP code and the application program both run in the same
78 thread. The sequential API has a much higher overhead and is not very
80 on the application.
82 The raw TCP/IP interface is not only faster in terms of code execution
83 time but is also less memory intensive. The drawback is that program
85 the raw TCP/IP interface are more difficult to understand. Still, this
86 is the preferred way of writing applications that should be small in
90 programs. In fact, the sequential API is implemented as an application
91 program using the raw TCP/IP interface.
93 Do not confuse the lwIP raw API with raw Ethernet or IP sockets.
94 The former is a way of interfacing the lwIP network stack (including
95 TCP and UDP), the later refers to processing raw Ethernet or IP data
105 invoked by the lwIP core when activity related to that application
111 C function that is called from within the TCP/IP code. Every callback
112 function is passed the current TCP or UDP connection state as an
114 the callback functions are called with a program specified argument
115 that is independent of the TCP/IP state.
117 The function for setting the application connection state is:
121 Specifies the program specific state that should be passed to all
122 other callback functions. The "pcb" argument is the current TCP
123 connection control block, and the "arg" argument is the argument
124 that will be passed to the callbacks.
129 The functions used for setting up connections is similar to that of
130 the sequential API and of the BSD socket API. A new TCP connection
131 identifier (i.e., a protocol control block - PCB) is created with the
138 available for creating the new pcb, NULL is returned.
143 Binds the pcb to a local IP address and port number. The IP address
144 can be specified as IP_ADDR_ANY in order to bind the connection to
147 If another connection is bound to the same port, the function will
153 incoming connection is accepted, the function specified with the
154 tcp_accept() function will be called. The pcb will have to be bound
155 to a local port with the tcp_bind() function.
157 The tcp_listen() function returns a new connection identifier, and
158 the one passed as an argument to the function will be
159 deallocated. The reason for this behavior is that less memory is
161 reclaim the memory needed for the original connection and allocate a
162 new smaller memory block for the listening connection.
164 tcp_listen() may return NULL if no memory was available for the
165 listening connection. If so, the memory associated with the pcb
170 Same as tcp_listen, but limits the number of outstanding connections
171 in the listen queue to the value specified by the backlog argument.
178 Specified the callback function that should be called when a new
186 Sets up the pcb to connect to the remote host and sends the
187 initial SYN segment which opens the connection.
189 The tcp_connect() function returns immediately; it does not wait for
190 the connection to be properly setup. Instead, it will call the
191 function specified as the fourth argument (the "connected" argument)
192 when the connection is established. If the connection could not be
193 properly established, either because the other host refused the
194 connection or because the other host didn't answer, the "err"
198 The tcp_connect() function can return ERR_MEM if no memory is
199 available for enqueueing the SYN segment. If the SYN indeed was
200 enqueued successfully, the tcp_connect() function returns ERR_OK.
205 TCP data is sent by enqueueing the data with a call to
206 tcp_write(). When the data is successfully transmitted to the remote
207 host, the application will be notified with a call to a specified
213 Enqueues the data pointed to by the argument dataptr. The length of
214 the data is passed as the len parameter. The apiflags can be one or more of:
215 - TCP_WRITE_FLAG_COPY: indicates whether the new memory should be allocated
216 for the data to be copied into. If this flag is not given, no new memory
217 should be allocated and the data should only be referenced by pointer. This
218 also means that the memory behind dataptr must not change until the data is
219 ACKed by the remote host
221 the PSH flag is set in the last segment created by this call to tcp_write.
222 If this flag is given, the PSH flag is not set.
224 The tcp_write() function will fail and return ERR_MEM if the length
225 of the data exceeds the current send buffer size or if the length of
226 the queue of outgoing segment is larger than the upper limit defined
227 in lwipopts.h. The number of bytes available in the output queue can
228 be retrieved with the tcp_sndbuf() function.
230 The proper way to use this function is to call the function with at
231 most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
232 the application should wait until some of the currently enqueued
233 data has been successfully received by the other host and try again.
239 Specifies the callback function that should be called when data has
240 successfully been received (i.e., acknowledged) by the remote
241 host. The len argument passed to the callback function gives the
242 amount bytes that was acknowledged by the last acknowledgment.
248 callback function is called when new data arrives. When the
249 application has taken the data, it has to call the tcp_recved()
250 function to indicate that TCP can advertise increase the receive
257 Sets the callback function that will be called when new data
258 arrives. The callback function will be passed a NULL pbuf to
259 indicate that the remote host has closed the connection. If
260 there are no errors and the callback function is to return
261 ERR_OK, then it must free the pbuf. Otherwise, it must not
262 free the pbuf so that lwIP core code can store it.
266 Must be called when the application has received the data. The len
267 argument indicates the length of the received data.
273 received), lwIP will repeatedly poll the application by calling a
278 the application may use the polling functionality to call tcp_write()
279 again when the connection has been idle for a while.
285 Specifies the polling interval and the callback function that should
286 be called to poll the application. The interval is specified in
288 twice a second. An interval of 10 means that the application would
296 Closes the connection. The function may return ERR_MEM if no memory
297 was available for closing the connection. If so, the application
298 should wait and try again either by using the acknowledgment
299 callback or the polling functionality. If the close succeeds, the
302 The pcb is deallocated by the TCP code after a call to tcp_close().
306 Aborts the connection by sending a RST (reset) segment to the remote
307 host. The pcb is deallocated. This function never fails.
309 ATTENTION: When calling this from one of the TCP callbacks, make
314 If a connection is aborted because of an error, the application is
315 alerted of this event by the err callback. Errors that might abort a
316 connection are when there is a shortage of memory. The callback
317 function to be called is set using the tcp_err() function.
322 The error callback function does not get the pcb passed to it as a
323 parameter since the pcb may already have been deallocated.
328 The UDP interface is similar to that of TCP, but due to the lower
329 level of complexity of UDP, the interface is significantly simpler.
333 Creates a new UDP pcb which can be used for UDP communication. The
339 Removes and deallocates the pcb.
344 Binds the pcb to a local address. The IP-address argument "ipaddr"
346 address. The function currently always return ERR_OK.
351 Sets the remote end of the pcb. This function does not generate any
352 network traffic, but only set the remote address of the pcb.
356 Remove the remote end of the pcb. This function does not generate
357 any network traffic, but only removes the remote address of the pcb.
361 Sends the pbuf p. The pbuf is not deallocated.
376 A truly complete and generic sequence for initializing the lwIP stack
380 We can give you some idea on how to proceed when using the raw API.
381 We assume a configuration using a single Ethernet netif and the
382 UDP and TCP transport layers, IPv4 and the DHCP client.
384 Call these functions in the order of appearance:
388 Initialize the lwIP stack and all of its subsystems.
394 Adds your network interface to the netif_list. Allocate a struct
395 netif and pass a pointer to this structure as the first argument.
397 or fill them with sane numbers otherwise. The state pointer may be NULL.
399 The init function pointer must point to a initialization function for
400 your Ethernet netif interface. The following code illustrates its use.
413 For Ethernet drivers, the input function pointer must point to the lwIP
419 Registers the default network interface.
423 This is the hardware link state; e.g. whether cable is plugged for wired
425 the current state. Having link up and link down events is optional but
430 This is the administrative (= software) state of the netif, when the
435 Creates a new DHCP client for this interface on the first call.
437 You can peek in the netif->dhcp struct for the actual DHCP status.
441 When the system is running, you have to periodically call
443 the stack; add this to your main loop or equivalent.
448 The first thing you want to optimize is the lwip_standard_checksum()
450 function with the #define LWIP_CHKSUM <your_checksum_routine>.
466 a higher speed than the maximum wire-speed. If the
470 E.g. when using the cs8900 driver, call cs8900if_service(ethif)
471 as frequently as possible. When using an RTOS let the cs8900 interrupt
478 high values to the memory options.
480 For more optimization hints take a look at the lwIP wiki.
484 To achieve zero-copy on transmit, the data passed to the raw API must
485 remain unchanged until sent. Because the send- (or write-)functions return
486 when the packets have been enqueued for sending, data must be kept stable
490 must *not* be reused by the application unless their ref-count is 1.
493 but the stack/driver will/must copy PBUF_REF'ed data when enqueueing, while
496 Also, data passed to tcp_write without the copy-flag must not be changed!