mirror of
https://github.com/lwip-tcpip/lwip.git
synced 2024-08-23 06:35:57 +00:00
Remove raw API TCP/UDP function documentation from rawapi.txt - it is now integrated in doxygen docs.
This avoid having a second description for the same stuff that is "bit-rotting" because noone remembers to update this file. Also remove outdated and misleading zero-copy TX information.
This commit is contained in:
parent
d020bfc0df
commit
84b2a0f55b
289
doc/rawapi.txt
289
doc/rawapi.txt
|
@ -99,277 +99,6 @@ Raw API applications may never block since all packet processing
|
||||||
(input and output) as well as timer processing (TCP mainly) is done
|
(input and output) as well as timer processing (TCP mainly) is done
|
||||||
in a single execution context.
|
in a single execution context.
|
||||||
|
|
||||||
--- Callbacks
|
|
||||||
|
|
||||||
Program execution is driven by callbacks functions, which are then
|
|
||||||
invoked by the lwIP core when activity related to that application
|
|
||||||
occurs. A particular application may register to be notified via a
|
|
||||||
callback function for events such as incoming data available, outgoing
|
|
||||||
data sent, error notifications, poll timer expiration, connection
|
|
||||||
closed, etc. An application can provide a callback function to perform
|
|
||||||
processing for any or all of these events. Each callback is an ordinary
|
|
||||||
C function that is called from within the TCP/IP code. Every callback
|
|
||||||
function is passed the current TCP or UDP connection state as an
|
|
||||||
argument. Also, in order to be able to keep program specific state,
|
|
||||||
the callback functions are called with a program specified argument
|
|
||||||
that is independent of the TCP/IP state.
|
|
||||||
|
|
||||||
The function for setting the application connection state is:
|
|
||||||
|
|
||||||
- void tcp_arg(struct tcp_pcb *pcb, void *arg)
|
|
||||||
|
|
||||||
Specifies the program specific state that should be passed to all
|
|
||||||
other callback functions. The "pcb" argument is the current TCP
|
|
||||||
connection control block, and the "arg" argument is the argument
|
|
||||||
that will be passed to the callbacks.
|
|
||||||
|
|
||||||
|
|
||||||
--- TCP connection setup
|
|
||||||
|
|
||||||
The functions used for setting up connections is similar to that of
|
|
||||||
the sequential API and of the BSD socket API. A new TCP connection
|
|
||||||
identifier (i.e., a protocol control block - PCB) is created with the
|
|
||||||
tcp_new() function. This PCB can then be either set to listen for new
|
|
||||||
incoming connections or be explicitly connected to another host.
|
|
||||||
|
|
||||||
- struct tcp_pcb *tcp_new(void)
|
|
||||||
|
|
||||||
Creates a new connection identifier (PCB). If memory is not
|
|
||||||
available for creating the new pcb, NULL is returned.
|
|
||||||
|
|
||||||
- err_t tcp_bind(struct tcp_pcb *pcb, ip_addr_t *ipaddr,
|
|
||||||
u16_t port)
|
|
||||||
|
|
||||||
Binds the pcb to a local IP address and port number. The IP address
|
|
||||||
can be specified as IP_ADDR_ANY in order to bind the connection to
|
|
||||||
all local IP addresses.
|
|
||||||
|
|
||||||
If another connection is bound to the same port, the function will
|
|
||||||
return ERR_USE, otherwise ERR_OK is returned.
|
|
||||||
|
|
||||||
- struct tcp_pcb *tcp_listen(struct tcp_pcb *pcb)
|
|
||||||
|
|
||||||
Commands a pcb to start listening for incoming connections. When an
|
|
||||||
incoming connection is accepted, the function specified with the
|
|
||||||
tcp_accept() function will be called. The pcb will have to be bound
|
|
||||||
to a local port with the tcp_bind() function.
|
|
||||||
|
|
||||||
The tcp_listen() function returns a new connection identifier, and
|
|
||||||
the one passed as an argument to the function will be
|
|
||||||
deallocated. The reason for this behavior is that less memory is
|
|
||||||
needed for a connection that is listening, so tcp_listen() will
|
|
||||||
reclaim the memory needed for the original connection and allocate a
|
|
||||||
new smaller memory block for the listening connection.
|
|
||||||
|
|
||||||
tcp_listen() may return NULL if no memory was available for the
|
|
||||||
listening connection. If so, the memory associated with the pcb
|
|
||||||
passed as an argument to tcp_listen() will not be deallocated.
|
|
||||||
|
|
||||||
- struct tcp_pcb *tcp_listen_with_backlog(struct tcp_pcb *pcb, u8_t backlog)
|
|
||||||
|
|
||||||
Same as tcp_listen, but limits the number of outstanding connections
|
|
||||||
in the listen queue to the value specified by the backlog argument.
|
|
||||||
To use it, your need to set TCP_LISTEN_BACKLOG=1 in your lwipopts.h.
|
|
||||||
|
|
||||||
- void tcp_accept(struct tcp_pcb *pcb,
|
|
||||||
err_t (* accept)(void *arg, struct tcp_pcb *newpcb,
|
|
||||||
err_t err))
|
|
||||||
|
|
||||||
Specified the callback function that should be called when a new
|
|
||||||
connection arrives on a listening connection.
|
|
||||||
|
|
||||||
- err_t tcp_connect(struct tcp_pcb *pcb, ip_addr_t *ipaddr,
|
|
||||||
u16_t port, err_t (* connected)(void *arg,
|
|
||||||
struct tcp_pcb *tpcb,
|
|
||||||
err_t err));
|
|
||||||
|
|
||||||
Sets up the pcb to connect to the remote host and sends the
|
|
||||||
initial SYN segment which opens the connection.
|
|
||||||
|
|
||||||
The tcp_connect() function returns immediately; it does not wait for
|
|
||||||
the connection to be properly setup. Instead, it will call the
|
|
||||||
function specified as the fourth argument (the "connected" argument)
|
|
||||||
when the connection is established. If the connection could not be
|
|
||||||
properly established, either because the other host refused the
|
|
||||||
connection or because the other host didn't answer, the "err"
|
|
||||||
callback function of this pcb (registered with tcp_err, see below)
|
|
||||||
will be called.
|
|
||||||
|
|
||||||
The tcp_connect() function can return ERR_MEM if no memory is
|
|
||||||
available for enqueueing the SYN segment. If the SYN indeed was
|
|
||||||
enqueued successfully, the tcp_connect() function returns ERR_OK.
|
|
||||||
|
|
||||||
|
|
||||||
--- Sending TCP data
|
|
||||||
|
|
||||||
TCP data is sent by enqueueing the data with a call to
|
|
||||||
tcp_write(). When the data is successfully transmitted to the remote
|
|
||||||
host, the application will be notified with a call to a specified
|
|
||||||
callback function.
|
|
||||||
|
|
||||||
- err_t tcp_write(struct tcp_pcb *pcb, const void *dataptr, u16_t len,
|
|
||||||
u8_t apiflags)
|
|
||||||
|
|
||||||
Enqueues the data pointed to by the argument dataptr. The length of
|
|
||||||
the data is passed as the len parameter. The apiflags can be one or more of:
|
|
||||||
- TCP_WRITE_FLAG_COPY: indicates whether the new memory should be allocated
|
|
||||||
for the data to be copied into. If this flag is not given, no new memory
|
|
||||||
should be allocated and the data should only be referenced by pointer. This
|
|
||||||
also means that the memory behind dataptr must not change until the data is
|
|
||||||
ACKed by the remote host
|
|
||||||
- TCP_WRITE_FLAG_MORE: indicates that more data follows. If this is omitted,
|
|
||||||
the PSH flag is set in the last segment created by this call to tcp_write.
|
|
||||||
If this flag is given, the PSH flag is not set.
|
|
||||||
|
|
||||||
The tcp_write() function will fail and return ERR_MEM if the length
|
|
||||||
of the data exceeds the current send buffer size or if the length of
|
|
||||||
the queue of outgoing segment is larger than the upper limit defined
|
|
||||||
in lwipopts.h. The number of bytes available in the output queue can
|
|
||||||
be retrieved with the tcp_sndbuf() function.
|
|
||||||
|
|
||||||
The proper way to use this function is to call the function with at
|
|
||||||
most tcp_sndbuf() bytes of data. If the function returns ERR_MEM,
|
|
||||||
the application should wait until some of the currently enqueued
|
|
||||||
data has been successfully received by the other host and try again.
|
|
||||||
|
|
||||||
- void tcp_sent(struct tcp_pcb *pcb,
|
|
||||||
err_t (* sent)(void *arg, struct tcp_pcb *tpcb,
|
|
||||||
u16_t len))
|
|
||||||
|
|
||||||
Specifies the callback function that should be called when data has
|
|
||||||
successfully been received (i.e., acknowledged) by the remote
|
|
||||||
host. The len argument passed to the callback function gives the
|
|
||||||
amount bytes that was acknowledged by the last acknowledgment.
|
|
||||||
|
|
||||||
|
|
||||||
--- Receiving TCP data
|
|
||||||
|
|
||||||
TCP data reception is callback based - an application specified
|
|
||||||
callback function is called when new data arrives. When the
|
|
||||||
application has taken the data, it has to call the tcp_recved()
|
|
||||||
function to indicate that TCP can advertise increase the receive
|
|
||||||
window.
|
|
||||||
|
|
||||||
- void tcp_recv(struct tcp_pcb *pcb,
|
|
||||||
err_t (* recv)(void *arg, struct tcp_pcb *tpcb,
|
|
||||||
struct pbuf *p, err_t err))
|
|
||||||
|
|
||||||
Sets the callback function that will be called when new data
|
|
||||||
arrives. The callback function will be passed a NULL pbuf to
|
|
||||||
indicate that the remote host has closed the connection. If the
|
|
||||||
callback function returns ERR_OK or ERR_ABRT it must have
|
|
||||||
freed the pbuf, otherwise it must not have freed it.
|
|
||||||
|
|
||||||
- void tcp_recved(struct tcp_pcb *pcb, u16_t len)
|
|
||||||
|
|
||||||
Must be called when the application has received the data. The len
|
|
||||||
argument indicates the length of the received data.
|
|
||||||
|
|
||||||
|
|
||||||
--- Application polling
|
|
||||||
|
|
||||||
When a connection is idle (i.e., no data is either transmitted or
|
|
||||||
received), lwIP will repeatedly poll the application by calling a
|
|
||||||
specified callback function. This can be used either as a watchdog
|
|
||||||
timer for killing connections that have stayed idle for too long, or
|
|
||||||
as a method of waiting for memory to become available. For instance,
|
|
||||||
if a call to tcp_write() has failed because memory wasn't available,
|
|
||||||
the application may use the polling functionality to call tcp_write()
|
|
||||||
again when the connection has been idle for a while.
|
|
||||||
|
|
||||||
- void tcp_poll(struct tcp_pcb *pcb,
|
|
||||||
err_t (* poll)(void *arg, struct tcp_pcb *tpcb),
|
|
||||||
u8_t interval)
|
|
||||||
|
|
||||||
Specifies the polling interval and the callback function that should
|
|
||||||
be called to poll the application. The interval is specified in
|
|
||||||
number of TCP coarse grained timer shots, which typically occurs
|
|
||||||
twice a second. An interval of 10 means that the application would
|
|
||||||
be polled every 5 seconds.
|
|
||||||
|
|
||||||
|
|
||||||
--- Closing and aborting connections
|
|
||||||
|
|
||||||
- err_t tcp_close(struct tcp_pcb *pcb)
|
|
||||||
|
|
||||||
Closes the connection. The function may return ERR_MEM if no memory
|
|
||||||
was available for closing the connection. If so, the application
|
|
||||||
should wait and try again either by using the acknowledgment
|
|
||||||
callback or the polling functionality. If the close succeeds, the
|
|
||||||
function returns ERR_OK.
|
|
||||||
|
|
||||||
The pcb is deallocated by the TCP code after a call to tcp_close().
|
|
||||||
|
|
||||||
- void tcp_abort(struct tcp_pcb *pcb)
|
|
||||||
|
|
||||||
Aborts the connection by sending a RST (reset) segment to the remote
|
|
||||||
host. The pcb is deallocated. This function never fails.
|
|
||||||
|
|
||||||
ATTENTION: When calling this from one of the TCP callbacks, make
|
|
||||||
sure you always return ERR_ABRT (and never return ERR_ABRT otherwise
|
|
||||||
or you will risk accessing deallocated memory or memory leaks!
|
|
||||||
|
|
||||||
|
|
||||||
If a connection is aborted because of an error, the application is
|
|
||||||
alerted of this event by the err callback. Errors that might abort a
|
|
||||||
connection are when there is a shortage of memory. The callback
|
|
||||||
function to be called is set using the tcp_err() function.
|
|
||||||
|
|
||||||
- void tcp_err(struct tcp_pcb *pcb, void (* err)(void *arg,
|
|
||||||
err_t err))
|
|
||||||
|
|
||||||
The error callback function does not get the pcb passed to it as a
|
|
||||||
parameter since the pcb may already have been deallocated.
|
|
||||||
|
|
||||||
|
|
||||||
--- UDP interface
|
|
||||||
|
|
||||||
The UDP interface is similar to that of TCP, but due to the lower
|
|
||||||
level of complexity of UDP, the interface is significantly simpler.
|
|
||||||
|
|
||||||
- struct udp_pcb *udp_new(void)
|
|
||||||
|
|
||||||
Creates a new UDP pcb which can be used for UDP communication. The
|
|
||||||
pcb is not active until it has either been bound to a local address
|
|
||||||
or connected to a remote address.
|
|
||||||
|
|
||||||
- void udp_remove(struct udp_pcb *pcb)
|
|
||||||
|
|
||||||
Removes and deallocates the pcb.
|
|
||||||
|
|
||||||
- err_t udp_bind(struct udp_pcb *pcb, ip_addr_t *ipaddr,
|
|
||||||
u16_t port)
|
|
||||||
|
|
||||||
Binds the pcb to a local address. The IP-address argument "ipaddr"
|
|
||||||
can be IP_ADDR_ANY to indicate that it should listen to any local IP
|
|
||||||
address. The function currently always return ERR_OK.
|
|
||||||
|
|
||||||
- err_t udp_connect(struct udp_pcb *pcb, ip_addr_t *ipaddr,
|
|
||||||
u16_t port)
|
|
||||||
|
|
||||||
Sets the remote end of the pcb. This function does not generate any
|
|
||||||
network traffic, but only set the remote address of the pcb.
|
|
||||||
|
|
||||||
- err_t udp_disconnect(struct udp_pcb *pcb)
|
|
||||||
|
|
||||||
Remove the remote end of the pcb. This function does not generate
|
|
||||||
any network traffic, but only removes the remote address of the pcb.
|
|
||||||
|
|
||||||
- err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
|
|
||||||
|
|
||||||
Sends the pbuf p. The pbuf is not deallocated.
|
|
||||||
|
|
||||||
- void udp_recv(struct udp_pcb *pcb,
|
|
||||||
void (* recv)(void *arg, struct udp_pcb *upcb,
|
|
||||||
struct pbuf *p,
|
|
||||||
ip_addr_t *addr,
|
|
||||||
u16_t port),
|
|
||||||
void *recv_arg)
|
|
||||||
|
|
||||||
Specifies a callback function that should be called when a UDP
|
|
||||||
datagram is received.
|
|
||||||
|
|
||||||
|
|
||||||
--- System initalization
|
--- System initalization
|
||||||
|
|
||||||
A truly complete and generic sequence for initializing the lwIP stack
|
A truly complete and generic sequence for initializing the lwIP stack
|
||||||
|
@ -477,21 +206,3 @@ Note that speed performance isn't influenced much by simply setting
|
||||||
high values to the memory options.
|
high values to the memory options.
|
||||||
|
|
||||||
For more optimization hints take a look at the lwIP wiki.
|
For more optimization hints take a look at the lwIP wiki.
|
||||||
|
|
||||||
--- Zero-copy MACs
|
|
||||||
|
|
||||||
To achieve zero-copy on transmit, the data passed to the raw API must
|
|
||||||
remain unchanged until sent. Because the send- (or write-)functions return
|
|
||||||
when the packets have been enqueued for sending, data must be kept stable
|
|
||||||
after that, too.
|
|
||||||
|
|
||||||
This implies that *ALL* pbufs passed to send functions must *not* be reused by
|
|
||||||
the application unless the send function returns an error indicating the pbuf
|
|
||||||
is not sent/queued for sending.
|
|
||||||
|
|
||||||
|
|
||||||
Also, data passed to tcp_write without the copy-flag must not be changed until
|
|
||||||
sent and ACKed (check the amount of bytes marked as 'sent')!
|
|
||||||
|
|
||||||
Therefore, be careful which type of PBUF you use and if you copy TCP data
|
|
||||||
or not!
|
|
||||||
|
|
|
@ -14,7 +14,6 @@
|
||||||
*
|
*
|
||||||
* TCP connection setup
|
* TCP connection setup
|
||||||
* --------------------
|
* --------------------
|
||||||
*
|
|
||||||
* The functions used for setting up connections is similar to that of
|
* The functions used for setting up connections is similar to that of
|
||||||
* the sequential API and of the BSD socket API. A new TCP connection
|
* the sequential API and of the BSD socket API. A new TCP connection
|
||||||
* identifier (i.e., a protocol control block - PCB) is created with the
|
* identifier (i.e., a protocol control block - PCB) is created with the
|
||||||
|
@ -37,7 +36,6 @@
|
||||||
*
|
*
|
||||||
* Receiving TCP data
|
* Receiving TCP data
|
||||||
* ------------------
|
* ------------------
|
||||||
*
|
|
||||||
* TCP data reception is callback based - an application specified
|
* TCP data reception is callback based - an application specified
|
||||||
* callback function is called when new data arrives. When the
|
* callback function is called when new data arrives. When the
|
||||||
* application has taken the data, it has to call the tcp_recved()
|
* application has taken the data, it has to call the tcp_recved()
|
||||||
|
|
Loading…
Reference in New Issue
Block a user