lwip-1.4.1文档rawapi中文翻译
来源：互联网 发布：捍卫者软件 编辑：程序博客网 时间：2024/05/27 03:29
Raw TCP/IP interface for lwIP
LwIP原始 TCP/IP接口
Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
lwIP provides three Application Program's Interfaces (APIs) for programs
to use for communication with the TCP/IP code:
* low-level "core" / "callback" or "raw" API.
* higher-level "sequential" API.
* BSD-style socket API.
LwIP为程序（上层应用程序）提供了三种应用程序接口，用于和 TCP/IP的代码通信，三种接口如下：
底层的“内核”/“回调函数”或“原始”API
较高层次的有序 API
BSD样式的套接 API
The sequential API provides a way for ordinary, sequential, programs
to use the lwIP stack. It is quite similar to the BSD socket API. The
model of execution is based on the blocking open-read-write-close
paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
code and the application program must reside in different execution
contexts (threads).
有序 API提供一种常规、有序的编程方法来使用 LwIP堆栈。其非常相似于 BSD套接 API。
其执行模型是基于阻塞的打开-读-写-关闭的范式。由于 TCP/IP本质上是事件驱动的，
TCP/IP代码和应用程序必须驻留在不同的线程中。
The socket API is a compatibility API for existing applications,
currently it is built on top of the sequential API. It is meant to
provide all functions needed to run socket API applications running
on other platforms (e.g. unix / windows etc.). However, due to limitations
in the specification of this API, there might be incompatibilities
that require small modifications of existing programs.
套接 API是一个与现有应用程序兼容的 API，当前，它是建立在有序 API的基础之上。
它为需要在其他平台（如 Unix和 Windows等）运行的套接 API 的应用程序提供完整的功能。
但由于 API在规格方面的限制，现有程序可能存在与之不兼容的地方，进而需要微小的调整。
** Threading
线程
lwIP started targeting single-threaded environments. When adding multi-
threading support, instead of making the core thread-safe, another
approach was chosen: there is one main thread running the lwIP core
(also known as the "tcpip_thread"). The raw API may only be used from
this thread! Application threads using the sequential- or socket API
communicate with this main thread through message passing.
LwIP最初以单线程环境为目标。当加入多线程支持时，鉴于内核线程安全的考量，
采取了另一种方法：一个主线程运行LwIP内核（也被称作“tcpip_thread”）。
原始 API可能只在该线程中使用。应用程序线程采用有序 API或套接 API通过消息投递与主线程通信。
As such, the list of functions that may be called from
other threads or an ISR is very limited! Only functions
from these API header files are thread-safe:
同样地，被其他线程或中断服务程序调用的函数是非常地有限。
只有如下 API头文件中的函数是线程安全的：
- api.h
- netbuf.h
- netdb.h
- netifapi.h
- sockets.h
- sys.h
Additionaly, memory (de-)allocation functions may be
called from multiple threads (not ISR!) with NO_SYS=0
since they are protected by SYS_LIGHTWEIGHT_PROT and/or
semaphores.
此外，当 NO_SYS=0 时，内存的分配和释放函数可能被多个线程（不是中断服务程序）调用，
因此它们（需）通过SYS_LIGHTWEIGHT_PROT宏定义和（或）信号量来保护。
Only since 1.3.0, if SYS_LIGHTWEIGHT_PROT is set to 1
and LWIP_ALLOW_MEM_FREE_FROM_OTHER_CONTEXT is set to 1,
pbuf_free() may also be called from another thread or
an ISR (since only then, mem_free - for PBUF_RAM - may
be called from an ISR: otherwise, the HEAP is only
protected by semaphores).
仅从 1.3.0版本开始，如果 SYS_LIGHTWEIGHT_PROT置 1，pbuf_free()可由其他线程或中断服务程序调用
（仅从那时开始，对 PBUF_MEM的 mem_free函数可能被其他中断服务程序调用：否则，HEAP仅能通过信号量保护）。
** The remainder of this document discusses the "raw" API. **
该文档的以下内容讨论原始 API
The raw TCP/IP interface allows the application program to integrate
better with the TCP/IP code. Program execution is event based by
having callback functions being called from within the TCP/IP
code. The TCP/IP code and the application program both run in the same
thread. The sequential API has a much higher overhead and is not very
well suited for small systems since it forces a multithreaded paradigm
on the application.
原始 TCP/IP接口允许应用程序与 TCP/IP代码更好的集成。
应用程序的执行是通过调用 TCP/IP 代码中的回调函数来实现事件驱动的。
TCP/IP代码和应用程序运行在同一个进程里。有序 API模式需要较高的开销，其不适合于小型的系统，
因此，迫使应用程序使用多线程范式。
The raw TCP/IP interface is not only faster in terms of code execution
time but is also less memory intensive. The drawback is that program
development is somewhat harder and application programs written for
the raw TCP/IP interface are more difficult to understand. Still, this
is the preferred way of writing applications that should be small in
code size and memory usage.
原始 API不仅在代码执行方面更快，其对存储器密度要求也较低。缺点是程序开发较为困难，
为原始 API写的应用程序较难于理解。然而，对于要求具有较小的代码尺寸和内存使用的场合，
其不失为一种受欢迎的方式。
Both APIs can be used simultaneously by different application
programs. In fact, the sequential API is implemented as an application
program using the raw TCP/IP interface.
各种 API可以同时被不同的应用程序调用（使用）。事实上，有序 API是采用原始 API接口实现的一个应用程序。
--- Callbacks回调函数
Program execution is driven by callbacks. 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.
程序的执行有回调函数驱动。每个回调函数都是一个普通的 C函数，这些 C函数由 TCP/IP代码调用。
每一个回调函数作为参数传递当前的 TCP或 UDP连接状态。同时，为了能够保持程序的特定状态，
回调函数被指定参数的程序调用，回调函数与 TCP/IP状态无关。
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.
指定程序的特定状态，该程序的返回句柄应传递给所有其他的回调函数。
“pcb”参数是当前 TCP连接控制块；“arg”参数是回调函数返回时的状态参数。
（该函数有两个参数，pcb是用户分配的 TCP连接控制块；arg是回调函数返回时，
存放回调函数某些参数或状态的指针；该函数返回的句柄应作为参数传递给其他回调函数）
--- TCP connection setup TCP连接建立
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.
用于建立连接的函数类似于有序 API和 BSD套接 API。
一个新的 TCP连接标识（如，协议控制块 PCB）通过 tcp_new()函数创建。
创建完毕，该 PCB即可用于监听新到来的连接，也可明确地连接到其他主机。
- 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.
创建一个新的连接标识。如果内存不足，返回 NULL.
- 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.
将 pcb绑定到本地 IP地址和端口号。为了绑定连接至所有本地 IP地址，IP地址可指定为 IP_ADDR_ANY。
如果另一个连接已绑定到相同的端口，该函数将返回 ERR_USE，否则返回 ERR_OK。
- 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.
命令一个 PCB 开始监听即将到来的连接。当新到来的连接被接受，指定 tcp_accept()函数将被调用。
PCB 必须通过tcp_bind()绑定到本地的一个端口。
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()返回一个新的连接标识。同时，作为参数传递给该函数的 PCB 将被释放。
原因是处于监听状态的连接仅需少量的内存，因此 tcp_listen()将回收初始连接的内存，并为监听连接分配一个新的较小的内存块。
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.
当用于监听连接的内存不足时（不可获得时），tcp_listen()将返回 NULL。在这种情况下，
作为参数传递给tcp_listen()的内存块将不会被释放。
- 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.
与 tcp_listen相同，但限制了在监听队列中未完成（等待）连接的数量，其值由 backlog参数指定。
使用该函数需在lwipopts.h文件中将 TCP_LISTEN_BACKLOG置 1。
- void tcp_accepted(struct tcp_pcb *pcb)
Inform lwIP that an incoming connection has been accepted. This would
usually be called from the accept callback. This allows lwIP to perform
housekeeping tasks, such as allowing further incoming connections to be
queued in the listen backlog.
通知 LwIP一个新的连接已经被接受。该函数通常被“接受回调函数”调用。
这允许 LwIP执行内务操作任务，比如允许后续即将到来的连接进入监听后备队列。
ATTENTION: the PCB passed in must be the listening pcb, not the pcb passed
into the accept callback!
- 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.
设置 PCB以连接至远程主机，并发送用于打开连接的初始 SYN参数。
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.
tcp_connect()函数立即返回；它并不等待连接的正确建立，而是在连接建立时调用第四个参数指定的回调函数。
如果连接不能正常建立，或因其他主机拒绝建立连接，或其他主机没有应答，
该 pcb（以 pcb_err注册，见下文）的“err” 回调函数将被调用。
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.
如果对入队的 SYN参数没有可获得的内存，tcp_connect()将返回 ERR_MEM。如果 SYN参数成功入队，tcp_connect()将返回 ERR_OK。
--- Sending TCP data发送 TCP数据
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.
TCP数据的发送是通过入队数据并调用 tcp_write()来实现的。
当数据成功传输至远程主机时，远程主机调用指定的回调函数通知应用程序。
- 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 given,
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.
将数据入队写至由参数 dataptr指定的内存区域。数据的长度作为 len参数传递。
拷贝参数为 0或 1，用于指示是否为将要拷贝来的数据分配新的内存。
如果该参数为 0，将不分配新的内存，并且数据仅能通过指针来引用。
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.
如果数据的最大长度超过了当前发送数据缓冲区的大小，或输出片段队列的长度超过了 lwipopts.h文件中定义的上限，
tcp_write()将失败并返回 EER_MEM，在输出队列中可获得的字节数可通过 tcp_sndbuf()函数检索。
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.
使用该函数的正确方式是调用该函数，并将参数指定为 tcp_sndbuf()获得的最大字节数。
如果函数返回 ERR_MEM，应用程序应等待直到当前入队数据正确地被其他主机接受并重试。
- 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.
指定当数据被远程主机成功接收时应调用的回调函数。传递给回调函数的 len 参数给出了在最后一次确认中确认的字节数。
--- Receiving TCP data接收 TCP数据
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.
TCP数据接收是基于回调函数的——当新的数据到达时，应用程序指定的回调函数被调用。
当应用程序接收数据完毕，必须调用 tcp_recved()函数用于指示 TCP通告可以增加新的接收窗口。
- 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
there are no errors and the callback function is to return
ERR_OK, then it must free the pbuf. Otherwise, it must not
free the pbuf so that lwIP core code can store it.
当新的数据到达时，设置被调用的回调函数。如果远程主机已关闭了连接，该函数的 pbuf参数将返回一个 NULL空指针。
如没有错误，并且回调函数的该参数返回值为 ERR_OK，那么该函数必须释放 pbuf。否则，禁止释放 pbuf，以确保 LwIP内核代码可以存储其值。
- 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.
当应用程序已接收数据，必须调用此函数。Len参数指示接收数据的长度。
--- 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.
当连接处于空闲状态（比如没有数据收发），LwIP将通过特定的回调函数重复地询问应用程序。
在这种情况下，可以用看门狗定时器来切断长时间处于空闲状态的连接，也可以用这种方法等待获取内存的分配。
例如，由于内存暂时不可获得，调用 tcp_write()将失败，应用程序可在连接处于空闲状态时用轮询功能来再次调用 tcp_write()。
- 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.
指定轮询间隔，并调用该回调函数轮询应用程序。时间间隔由粗略的定时器中断时间来指定，通常 1秒钟发生 2次。
值为10的间隔表示应用程序每隔 5秒查询一次。
--- 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.
关闭连接。如果关闭连接的内存不可获得，该函数将返回 ERR_MEM。
在这种情况下，应用程序应通过确认回调函数或轮询功能来等待并重试。如果关闭成功，该函数返回 ERR_OK。
The pcb is deallocated by the TCP code after a call to tcp_close().
在 tcp_close()调用后，pcb由 TCP代码释放其内存。
- 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.
通过向远程主机发送一个复位语句以中止连接。同时，pcb释放。该函数不会失败。
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!
注意：当从 TCP 的任何一个回调函数中调用该函数时，需确保返回值为 ERR_ABRT
（从不返回 ERR_ABRT，否则将冒险存取已释放的内存，或内存泄露）。
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.
如果由于发生错误连接中止，应用程序应通过 err 回调函数对该事件保持警觉。
造成中止连接的错误可能是内存不足。可调用的回调函数是使用 tcp_err()。
- 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.
由于 pcb可能已经被释放，该回调函数不能获得作为参数传递给其自身的 pcb。
--- Lower layer TCP interface
TCP provides a simple interface to the lower layers of the
system. During system initialization, the function tcp_init() has
to be called before any other TCP function is called. When the system
is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
must be called with regular intervals. The tcp_fasttmr() should be
called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
TCP为系统的底层提供了一个较为简单的接口。在系统初始化期间，函数 tcp_init()应先于其他 TCP函数被调用。
在系统运行时，两个定时器函数 tcp_fasttmr()和 tcp_slowtmr()必须以特定的时间间隔调用。
tcp_fasttmr()应该每 TCP_FAST_INTERVAL毫秒调用一次（定义在 tcp.h文件中），tcp_slowtmr()应每隔 TCP_SLOW_INTERVAL毫秒调用一次。
--- UDP interface UDP接口
The UDP interface is similar to that of TCP, but due to the lower
level of complexity of UDP, the interface is significantly simpler.
UDP接口与 TCP类似，但由于 UDP底层的复杂性，但其接口却更为简单。
- 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.
创建一个用于 UDP通信的 pcb。除非 pcb被绑定到一个本地地址或连接到远程地址，否则该 pcb处于非活动状态。
- void udp_remove(struct udp_pcb *pcb)
Removes and deallocates the pcb.
删除并释放 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.
将 pcb绑定到一个本地地址。IP 地址参数可以指定为 IP_ADDR_ANY，用以表明其监听本地所有 IP地址。该函数总是返回 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.
设置 pcb的远程端。该函数不产生任何网络流量，仅仅设置 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.
删除 pcb的远程端。该函数不产生任何网络流量，仅仅删除 pcb的远程终端地址。
- err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
Sends the pbuf p. The pbuf is not deallocated.
发送参数 p指向的内容。Pbuf不被释放。
- 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.
指定当接收到 UDP报文时应调用的回调函数。
--- System initalization系统初始化
A truly complete and generic sequence for initializing the lwip stack
cannot be given because it depends on the build configuration (lwipopts.h)
and additional initializations for your runtime environment (e.g. timers).
取决于编译配置（lwipopts.h）及运行环境（如定时器）的附加初始化，我们不能给出一个真实、完整、通用的初始化LwIP堆栈的顺序。
We can give you some idea on how to proceed when using the raw API.
We assume a configuration using a single Ethernet netif and the
UDP and TCP transport layers, IPv4 and the DHCP client.
我们仅能给出一些使用原始 API的处理方法。假定我们使用单网络 netif、UDP和 TCP、IPv4和 DHCP客户端的配置。
Call these functions in the order of appearance:
以出现顺序调用如下函数：
- stats_init()
Clears the structure where runtime statistics are gathered.
清除收集运行统计信息的结构。
- sys_init()
Not of much use since we set the NO_SYS 1 option in lwipopts.h,
to be called for easy configuration changes.
由于我们在 lwipopts.h文件中将 NO_SYS置 1，所以该函数没太大的用处。对于简单配置的改变应调用此函数。
- mem_init()
Initializes the dynamic memory heap defined by MEM_SIZE.
初始化由 MEM_SIZE定义的内存堆。
- memp_init()
Initializes the memory pools defined by MEMP_NUM_x.
初始化由 MEMP_NUM_x定义的内存池。
- pbuf_init()
Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
初始化由 PBUF_POOL_SIZE定义的 pbuf内存池。
- etharp_init()
Initializes the ARP table and queue.
Note: you must call etharp_tmr at a ARP_TMR_INTERVAL (5 seconds) regular interval
after this initialization.
初始化 ARP表和队列。注释：此初始化完毕，必须以 ARP_TMR_INTERVAL(5秒)间隔调用 etharp_tmr函数。
- ip_init()
Doesn't do much, it should be called to handle future changes.
应调用处理后续的改变，此处没处理特别的事务。
- udp_init()
Clears the UDP PCB list.
清除 UDP的 PCB列表。
- tcp_init()
Clears the TCP PCB list and clears some internal TCP timers.
清除 TCP 的 PCB 列表，并且清除某些内部的 TCP 定时器。
Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
predefined regular intervals after this initialization.
注释：此初始化完毕，必须以实现定义的时间间隔调用tcp_fasttmr()和 tcp_slowtmr()。
- netif_add(struct netif *netif, ip_addr_t *ipaddr,
ip_addr_t *netmask, ip_addr_t *gw,
void *state, err_t (* init)(struct netif *netif),
err_t (* input)(struct pbuf *p, struct netif *netif))
Adds your network interface to the netif_list. Allocate a struct
netif and pass a pointer to this structure as the first argument.
Give pointers to cleared ip_addr structures when using DHCP,
or fill them with sane numbers otherwise. The state pointer may be NULL.
在 netif_list中添加网络接口，分配 netif结构并向这个结构的第一个参数传递一个指针。
当使用 DHCP时，给出指向已清空的 ip_addr结构的指针，否则，应正确地赋值。State参数可能是空指针 NULL。
The init function pointer must point to a initialization function for
your ethernet netif interface. The following code illustrates it's use.
初始化函数指针必须指向用户的网络 netif接口初始化函数。以下代码阐述了它的用法。
err_t netif_if_init(struct netif *netif)
{
u8_t i;
for(i = 0; i < ETHARP_HWADDR_LEN; i++) netif->hwaddr[i] = some_eth_addr[i];
init_my_eth_device();
return ERR_OK;
}
For ethernet drivers, the input function pointer must point to the lwip
function ethernet_input() declared in "netif/etharp.h". Other drivers
must use ip_input() declared in "lwip/ip.h".
对于网络驱动，输入函数指针必须指向在"netif/etharp.h"声明的 LwIP 函数 ethernet_input()。
其他驱动必须使用在"lwip/ip.h"声明的 ip_input()函数。
- netif_set_default(struct netif *netif)
Registers the default network interface.
注册默认的网络接口。
- netif_set_up(struct netif *netif)
When the netif is fully configured this function must be called.
当 netif配置完整，必须调用该函数。
- dhcp_start(struct netif *netif)
Creates a new DHCP client for this interface on the first call.
Note: you must call dhcp_fine_tmr() and dhcp_coarse_tmr() at
the predefined regular intervals after starting the client.
为该接口的第一次调用创建一个新的 DHCP 客户端。
注释：在启动这个客户端后，必须以实现定义的时间间隔调用dhcp_fine_tmr()和 dhcp_coarse_tmr()函数。
You can peek in the netif->dhcp struct for the actual DHCP status.
用户可以通过 netif结构中的 netif->dhcp成员来查看实际的 DHCP状态。
--- Optimalization hints 优化提示
The first thing you want to optimize is the lwip_standard_checksum()
routine from src/core/inet.c. You can override this standard
function with the #define LWIP_CHKSUM <your_checksum_routine>.
优化工作的第一件事情就是 src/core/inet.c 中的 lwip_standard_checksum()程序。
用户可以通过#define LWIP_CHKSUM <your_checksum_routine>宏定义，使用用户的函数来取代标准函数。
There are C examples given in inet.c or you might want to
craft an assembly function for this. RFC1071 is a good
introduction to this subject.
在 inet.c文件中有 C程序的例子。你可能想要为之编制一个汇编程序。RFC1071对该主题做了详细的介绍。
Other significant improvements can be made by supplying
assembly or inline replacements for htons() and htonl()
if you're using a little-endian architecture.
如果你采用小端结构，可通过采用汇编或内联汇编嵌入来实现 htons()和 htonl()以获得重要的性能提升。
#define LWIP_PLATFORM_BYTESWAP 1
#define LWIP_PLATFORM_HTONS(x) <your_htons>
#define LWIP_PLATFORM_HTONL(x) <your_htonl>
Check your network interface driver if it reads at
a higher speed than the maximum wire-speed. If the
hardware isn't serviced frequently and fast enough
buffer overflows are likely to occur.
检测你的网络接口驱动是否读取的速度高于最大的线速。如果硬件不能足够快速、频繁地服务，那么缓存溢出就可能会发生
E.g. when using the cs8900 driver, call cs8900if_service(ethif)
as frequently as possible. When using an RTOS let the cs8900 interrupt
wake a high priority task that services your driver using a binary
semaphore or event flag. Some drivers might allow additional tuning
to match your application and network.
例如，在使用 CS8900驱动时，尽可能频繁地调用 cs8900if_service(ethif)。
当运行实时操作系统时，让 CS8900中断唤醒较高优先级的任务，而该任务采用信号量或事件标志来为你的驱动提供服务。
一些驱动可能允许采取其他的调整来匹配你的应用程序和网络。
For a production release it is recommended to set LWIP_STATS to 0.
Note that speed performance isn't influenced much by simply setting
high values to the memory options.
对于正式发行的产品，推荐将 LWIP_STATS置 0。注释：简单地将内存选项置高对速度性能并没有太大影响。
For more optimization hints take a look at the lwIP wiki.
想要获得更多的优化提示，请查看 LwIP维基。
--- Zero-copy MACs 零拷贝 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.
为了实现传输的 0拷贝，传递到原始 API 的数据必须保持不被更改直到被发送。
因为当入队待发的数据包在入队后发送（或写）函数将返回，入队后的数据也必须保持不变。
This implies that PBUF_RAM/PBUF_POOL pbufs passed to raw-API send functions
must *not* be reused by the application unless their ref-count is 1.
这意味着传递给原始 API发送函数的 pbufs不能被应用程序重复使用，除非他们的 ref-count为 1。
For no-copy pbufs (PBUF_ROM/PBUF_REF), data must be kept unchanged, too,
but the stack/driver will/must copy PBUF_REF'ed data when enqueueing, while
PBUF_ROM-pbufs are just enqueued (as ROM-data is expected to never change).
对于非拷贝型 pbufs，数据也必须保持不变，但当入队时，堆栈/驱动将/必须拷贝 PBUF_REF'ed数据，PBUF_ROM-pbufs仅是被入队（因为 ROM-data不会被改变）。
Also, data passed to tcp_write without the copy-flag must not be changed!
此外，没有拷贝标志 copy-flag传递到 tcp_write函数的数据禁止改变。
Therefore, be careful which type of PBUF you use and if you copy TCP data
or not!
因此，要留意你所使用的 PBUF的类型，以及是否拷贝 TCP数据。
LwIP原始 TCP/IP接口
Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons
lwIP provides three Application Program's Interfaces (APIs) for programs
to use for communication with the TCP/IP code:
* low-level "core" / "callback" or "raw" API.
* higher-level "sequential" API.
* BSD-style socket API.
LwIP为程序（上层应用程序）提供了三种应用程序接口，用于和 TCP/IP的代码通信，三种接口如下：
底层的“内核”/“回调函数”或“原始”API
较高层次的有序 API
BSD样式的套接 API
The sequential API provides a way for ordinary, sequential, programs
to use the lwIP stack. It is quite similar to the BSD socket API. The
model of execution is based on the blocking open-read-write-close
paradigm. Since the TCP/IP stack is event based by nature, the TCP/IP
code and the application program must reside in different execution
contexts (threads).
有序 API提供一种常规、有序的编程方法来使用 LwIP堆栈。其非常相似于 BSD套接 API。
其执行模型是基于阻塞的打开-读-写-关闭的范式。由于 TCP/IP本质上是事件驱动的，
TCP/IP代码和应用程序必须驻留在不同的线程中。
The socket API is a compatibility API for existing applications,
currently it is built on top of the sequential API. It is meant to
provide all functions needed to run socket API applications running
on other platforms (e.g. unix / windows etc.). However, due to limitations
in the specification of this API, there might be incompatibilities
that require small modifications of existing programs.
套接 API是一个与现有应用程序兼容的 API，当前，它是建立在有序 API的基础之上。
它为需要在其他平台（如 Unix和 Windows等）运行的套接 API 的应用程序提供完整的功能。
但由于 API在规格方面的限制，现有程序可能存在与之不兼容的地方，进而需要微小的调整。
** Threading
线程
lwIP started targeting single-threaded environments. When adding multi-
threading support, instead of making the core thread-safe, another
approach was chosen: there is one main thread running the lwIP core
(also known as the "tcpip_thread"). The raw API may only be used from
this thread! Application threads using the sequential- or socket API
communicate with this main thread through message passing.
LwIP最初以单线程环境为目标。当加入多线程支持时，鉴于内核线程安全的考量，
采取了另一种方法：一个主线程运行LwIP内核（也被称作“tcpip_thread”）。
原始 API可能只在该线程中使用。应用程序线程采用有序 API或套接 API通过消息投递与主线程通信。
As such, the list of functions that may be called from
other threads or an ISR is very limited! Only functions
from these API header files are thread-safe:
同样地，被其他线程或中断服务程序调用的函数是非常地有限。
只有如下 API头文件中的函数是线程安全的：
- api.h
- netbuf.h
- netdb.h
- netifapi.h
- sockets.h
- sys.h
Additionaly, memory (de-)allocation functions may be
called from multiple threads (not ISR!) with NO_SYS=0
since they are protected by SYS_LIGHTWEIGHT_PROT and/or
semaphores.
此外，当 NO_SYS=0 时，内存的分配和释放函数可能被多个线程（不是中断服务程序）调用，
因此它们（需）通过SYS_LIGHTWEIGHT_PROT宏定义和（或）信号量来保护。
Only since 1.3.0, if SYS_LIGHTWEIGHT_PROT is set to 1
and LWIP_ALLOW_MEM_FREE_FROM_OTHER_CONTEXT is set to 1,
pbuf_free() may also be called from another thread or
an ISR (since only then, mem_free - for PBUF_RAM - may
be called from an ISR: otherwise, the HEAP is only
protected by semaphores).
仅从 1.3.0版本开始，如果 SYS_LIGHTWEIGHT_PROT置 1，pbuf_free()可由其他线程或中断服务程序调用
（仅从那时开始，对 PBUF_MEM的 mem_free函数可能被其他中断服务程序调用：否则，HEAP仅能通过信号量保护）。
** The remainder of this document discusses the "raw" API. **
该文档的以下内容讨论原始 API
The raw TCP/IP interface allows the application program to integrate
better with the TCP/IP code. Program execution is event based by
having callback functions being called from within the TCP/IP
code. The TCP/IP code and the application program both run in the same
thread. The sequential API has a much higher overhead and is not very
well suited for small systems since it forces a multithreaded paradigm
on the application.
原始 TCP/IP接口允许应用程序与 TCP/IP代码更好的集成。
应用程序的执行是通过调用 TCP/IP 代码中的回调函数来实现事件驱动的。
TCP/IP代码和应用程序运行在同一个进程里。有序 API模式需要较高的开销，其不适合于小型的系统，
因此，迫使应用程序使用多线程范式。
The raw TCP/IP interface is not only faster in terms of code execution
time but is also less memory intensive. The drawback is that program
development is somewhat harder and application programs written for
the raw TCP/IP interface are more difficult to understand. Still, this
is the preferred way of writing applications that should be small in
code size and memory usage.
原始 API不仅在代码执行方面更快，其对存储器密度要求也较低。缺点是程序开发较为困难，
为原始 API写的应用程序较难于理解。然而，对于要求具有较小的代码尺寸和内存使用的场合，
其不失为一种受欢迎的方式。
Both APIs can be used simultaneously by different application
programs. In fact, the sequential API is implemented as an application
program using the raw TCP/IP interface.
各种 API可以同时被不同的应用程序调用（使用）。事实上，有序 API是采用原始 API接口实现的一个应用程序。
--- Callbacks回调函数
Program execution is driven by callbacks. 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.
程序的执行有回调函数驱动。每个回调函数都是一个普通的 C函数，这些 C函数由 TCP/IP代码调用。
每一个回调函数作为参数传递当前的 TCP或 UDP连接状态。同时，为了能够保持程序的特定状态，
回调函数被指定参数的程序调用，回调函数与 TCP/IP状态无关。
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.
指定程序的特定状态，该程序的返回句柄应传递给所有其他的回调函数。
“pcb”参数是当前 TCP连接控制块；“arg”参数是回调函数返回时的状态参数。
（该函数有两个参数，pcb是用户分配的 TCP连接控制块；arg是回调函数返回时，
存放回调函数某些参数或状态的指针；该函数返回的句柄应作为参数传递给其他回调函数）
--- TCP connection setup TCP连接建立
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.
用于建立连接的函数类似于有序 API和 BSD套接 API。
一个新的 TCP连接标识（如，协议控制块 PCB）通过 tcp_new()函数创建。
创建完毕，该 PCB即可用于监听新到来的连接，也可明确地连接到其他主机。
- 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.
创建一个新的连接标识。如果内存不足，返回 NULL.
- 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.
将 pcb绑定到本地 IP地址和端口号。为了绑定连接至所有本地 IP地址，IP地址可指定为 IP_ADDR_ANY。
如果另一个连接已绑定到相同的端口，该函数将返回 ERR_USE，否则返回 ERR_OK。
- 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.
命令一个 PCB 开始监听即将到来的连接。当新到来的连接被接受，指定 tcp_accept()函数将被调用。
PCB 必须通过tcp_bind()绑定到本地的一个端口。
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()返回一个新的连接标识。同时，作为参数传递给该函数的 PCB 将被释放。
原因是处于监听状态的连接仅需少量的内存，因此 tcp_listen()将回收初始连接的内存，并为监听连接分配一个新的较小的内存块。
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.
当用于监听连接的内存不足时（不可获得时），tcp_listen()将返回 NULL。在这种情况下，
作为参数传递给tcp_listen()的内存块将不会被释放。
- 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.
与 tcp_listen相同，但限制了在监听队列中未完成（等待）连接的数量，其值由 backlog参数指定。
使用该函数需在lwipopts.h文件中将 TCP_LISTEN_BACKLOG置 1。
- void tcp_accepted(struct tcp_pcb *pcb)
Inform lwIP that an incoming connection has been accepted. This would
usually be called from the accept callback. This allows lwIP to perform
housekeeping tasks, such as allowing further incoming connections to be
queued in the listen backlog.
通知 LwIP一个新的连接已经被接受。该函数通常被“接受回调函数”调用。
这允许 LwIP执行内务操作任务，比如允许后续即将到来的连接进入监听后备队列。
ATTENTION: the PCB passed in must be the listening pcb, not the pcb passed
into the accept callback!
- 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.
设置 PCB以连接至远程主机，并发送用于打开连接的初始 SYN参数。
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.
tcp_connect()函数立即返回；它并不等待连接的正确建立，而是在连接建立时调用第四个参数指定的回调函数。
如果连接不能正常建立，或因其他主机拒绝建立连接，或其他主机没有应答，
该 pcb（以 pcb_err注册，见下文）的“err” 回调函数将被调用。
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.
如果对入队的 SYN参数没有可获得的内存，tcp_connect()将返回 ERR_MEM。如果 SYN参数成功入队，tcp_connect()将返回 ERR_OK。
--- Sending TCP data发送 TCP数据
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.
TCP数据的发送是通过入队数据并调用 tcp_write()来实现的。
当数据成功传输至远程主机时，远程主机调用指定的回调函数通知应用程序。
- 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 given,
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.
将数据入队写至由参数 dataptr指定的内存区域。数据的长度作为 len参数传递。
拷贝参数为 0或 1，用于指示是否为将要拷贝来的数据分配新的内存。
如果该参数为 0，将不分配新的内存，并且数据仅能通过指针来引用。
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.
如果数据的最大长度超过了当前发送数据缓冲区的大小，或输出片段队列的长度超过了 lwipopts.h文件中定义的上限，
tcp_write()将失败并返回 EER_MEM，在输出队列中可获得的字节数可通过 tcp_sndbuf()函数检索。
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.
使用该函数的正确方式是调用该函数，并将参数指定为 tcp_sndbuf()获得的最大字节数。
如果函数返回 ERR_MEM，应用程序应等待直到当前入队数据正确地被其他主机接受并重试。
- 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.
指定当数据被远程主机成功接收时应调用的回调函数。传递给回调函数的 len 参数给出了在最后一次确认中确认的字节数。
--- Receiving TCP data接收 TCP数据
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.
TCP数据接收是基于回调函数的——当新的数据到达时，应用程序指定的回调函数被调用。
当应用程序接收数据完毕，必须调用 tcp_recved()函数用于指示 TCP通告可以增加新的接收窗口。
- 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
there are no errors and the callback function is to return
ERR_OK, then it must free the pbuf. Otherwise, it must not
free the pbuf so that lwIP core code can store it.
当新的数据到达时，设置被调用的回调函数。如果远程主机已关闭了连接，该函数的 pbuf参数将返回一个 NULL空指针。
如没有错误，并且回调函数的该参数返回值为 ERR_OK，那么该函数必须释放 pbuf。否则，禁止释放 pbuf，以确保 LwIP内核代码可以存储其值。
- 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.
当应用程序已接收数据，必须调用此函数。Len参数指示接收数据的长度。
--- 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.
当连接处于空闲状态（比如没有数据收发），LwIP将通过特定的回调函数重复地询问应用程序。
在这种情况下，可以用看门狗定时器来切断长时间处于空闲状态的连接，也可以用这种方法等待获取内存的分配。
例如，由于内存暂时不可获得，调用 tcp_write()将失败，应用程序可在连接处于空闲状态时用轮询功能来再次调用 tcp_write()。
- 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.
指定轮询间隔，并调用该回调函数轮询应用程序。时间间隔由粗略的定时器中断时间来指定，通常 1秒钟发生 2次。
值为10的间隔表示应用程序每隔 5秒查询一次。
--- 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.
关闭连接。如果关闭连接的内存不可获得，该函数将返回 ERR_MEM。
在这种情况下，应用程序应通过确认回调函数或轮询功能来等待并重试。如果关闭成功，该函数返回 ERR_OK。
The pcb is deallocated by the TCP code after a call to tcp_close().
在 tcp_close()调用后，pcb由 TCP代码释放其内存。
- 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.
通过向远程主机发送一个复位语句以中止连接。同时，pcb释放。该函数不会失败。
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!
注意：当从 TCP 的任何一个回调函数中调用该函数时，需确保返回值为 ERR_ABRT
（从不返回 ERR_ABRT，否则将冒险存取已释放的内存，或内存泄露）。
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.
如果由于发生错误连接中止，应用程序应通过 err 回调函数对该事件保持警觉。
造成中止连接的错误可能是内存不足。可调用的回调函数是使用 tcp_err()。
- 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.
由于 pcb可能已经被释放，该回调函数不能获得作为参数传递给其自身的 pcb。
--- Lower layer TCP interface
TCP provides a simple interface to the lower layers of the
system. During system initialization, the function tcp_init() has
to be called before any other TCP function is called. When the system
is running, the two timer functions tcp_fasttmr() and tcp_slowtmr()
must be called with regular intervals. The tcp_fasttmr() should be
called every TCP_FAST_INTERVAL milliseconds (defined in tcp.h) and
tcp_slowtmr() should be called every TCP_SLOW_INTERVAL milliseconds.
TCP为系统的底层提供了一个较为简单的接口。在系统初始化期间，函数 tcp_init()应先于其他 TCP函数被调用。
在系统运行时，两个定时器函数 tcp_fasttmr()和 tcp_slowtmr()必须以特定的时间间隔调用。
tcp_fasttmr()应该每 TCP_FAST_INTERVAL毫秒调用一次（定义在 tcp.h文件中），tcp_slowtmr()应每隔 TCP_SLOW_INTERVAL毫秒调用一次。
--- UDP interface UDP接口
The UDP interface is similar to that of TCP, but due to the lower
level of complexity of UDP, the interface is significantly simpler.
UDP接口与 TCP类似，但由于 UDP底层的复杂性，但其接口却更为简单。
- 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.
创建一个用于 UDP通信的 pcb。除非 pcb被绑定到一个本地地址或连接到远程地址，否则该 pcb处于非活动状态。
- void udp_remove(struct udp_pcb *pcb)
Removes and deallocates the pcb.
删除并释放 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.
将 pcb绑定到一个本地地址。IP 地址参数可以指定为 IP_ADDR_ANY，用以表明其监听本地所有 IP地址。该函数总是返回 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.
设置 pcb的远程端。该函数不产生任何网络流量，仅仅设置 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.
删除 pcb的远程端。该函数不产生任何网络流量，仅仅删除 pcb的远程终端地址。
- err_t udp_send(struct udp_pcb *pcb, struct pbuf *p)
Sends the pbuf p. The pbuf is not deallocated.
发送参数 p指向的内容。Pbuf不被释放。
- 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.
指定当接收到 UDP报文时应调用的回调函数。
--- System initalization系统初始化
A truly complete and generic sequence for initializing the lwip stack
cannot be given because it depends on the build configuration (lwipopts.h)
and additional initializations for your runtime environment (e.g. timers).
取决于编译配置（lwipopts.h）及运行环境（如定时器）的附加初始化，我们不能给出一个真实、完整、通用的初始化LwIP堆栈的顺序。
We can give you some idea on how to proceed when using the raw API.
We assume a configuration using a single Ethernet netif and the
UDP and TCP transport layers, IPv4 and the DHCP client.
我们仅能给出一些使用原始 API的处理方法。假定我们使用单网络 netif、UDP和 TCP、IPv4和 DHCP客户端的配置。
Call these functions in the order of appearance:
以出现顺序调用如下函数：
- stats_init()
Clears the structure where runtime statistics are gathered.
清除收集运行统计信息的结构。
- sys_init()
Not of much use since we set the NO_SYS 1 option in lwipopts.h,
to be called for easy configuration changes.
由于我们在 lwipopts.h文件中将 NO_SYS置 1，所以该函数没太大的用处。对于简单配置的改变应调用此函数。
- mem_init()
Initializes the dynamic memory heap defined by MEM_SIZE.
初始化由 MEM_SIZE定义的内存堆。
- memp_init()
Initializes the memory pools defined by MEMP_NUM_x.
初始化由 MEMP_NUM_x定义的内存池。
- pbuf_init()
Initializes the pbuf memory pool defined by PBUF_POOL_SIZE.
初始化由 PBUF_POOL_SIZE定义的 pbuf内存池。
- etharp_init()
Initializes the ARP table and queue.
Note: you must call etharp_tmr at a ARP_TMR_INTERVAL (5 seconds) regular interval
after this initialization.
初始化 ARP表和队列。注释：此初始化完毕，必须以 ARP_TMR_INTERVAL(5秒)间隔调用 etharp_tmr函数。
- ip_init()
Doesn't do much, it should be called to handle future changes.
应调用处理后续的改变，此处没处理特别的事务。
- udp_init()
Clears the UDP PCB list.
清除 UDP的 PCB列表。
- tcp_init()
Clears the TCP PCB list and clears some internal TCP timers.
清除 TCP 的 PCB 列表，并且清除某些内部的 TCP 定时器。
Note: you must call tcp_fasttmr() and tcp_slowtmr() at the
predefined regular intervals after this initialization.
注释：此初始化完毕，必须以实现定义的时间间隔调用tcp_fasttmr()和 tcp_slowtmr()。
- netif_add(struct netif *netif, ip_addr_t *ipaddr,
ip_addr_t *netmask, ip_addr_t *gw,
void *state, err_t (* init)(struct netif *netif),
err_t (* input)(struct pbuf *p, struct netif *netif))
Adds your network interface to the netif_list. Allocate a struct
netif and pass a pointer to this structure as the first argument.
Give pointers to cleared ip_addr structures when using DHCP,
or fill them with sane numbers otherwise. The state pointer may be NULL.
在 netif_list中添加网络接口，分配 netif结构并向这个结构的第一个参数传递一个指针。
当使用 DHCP时，给出指向已清空的 ip_addr结构的指针，否则，应正确地赋值。State参数可能是空指针 NULL。
The init function pointer must point to a initialization function for
your ethernet netif interface. The following code illustrates it's use.
初始化函数指针必须指向用户的网络 netif接口初始化函数。以下代码阐述了它的用法。
err_t netif_if_init(struct netif *netif)
{
u8_t i;
for(i = 0; i < ETHARP_HWADDR_LEN; i++) netif->hwaddr[i] = some_eth_addr[i];
init_my_eth_device();
return ERR_OK;
}
For ethernet drivers, the input function pointer must point to the lwip
function ethernet_input() declared in "netif/etharp.h". Other drivers
must use ip_input() declared in "lwip/ip.h".
对于网络驱动，输入函数指针必须指向在"netif/etharp.h"声明的 LwIP 函数 ethernet_input()。
其他驱动必须使用在"lwip/ip.h"声明的 ip_input()函数。
- netif_set_default(struct netif *netif)
Registers the default network interface.
注册默认的网络接口。
- netif_set_up(struct netif *netif)
When the netif is fully configured this function must be called.
当 netif配置完整，必须调用该函数。
- dhcp_start(struct netif *netif)
Creates a new DHCP client for this interface on the first call.
Note: you must call dhcp_fine_tmr() and dhcp_coarse_tmr() at
the predefined regular intervals after starting the client.
为该接口的第一次调用创建一个新的 DHCP 客户端。
注释：在启动这个客户端后，必须以实现定义的时间间隔调用dhcp_fine_tmr()和 dhcp_coarse_tmr()函数。
You can peek in the netif->dhcp struct for the actual DHCP status.
用户可以通过 netif结构中的 netif->dhcp成员来查看实际的 DHCP状态。
--- Optimalization hints 优化提示
The first thing you want to optimize is the lwip_standard_checksum()
routine from src/core/inet.c. You can override this standard
function with the #define LWIP_CHKSUM <your_checksum_routine>.
优化工作的第一件事情就是 src/core/inet.c 中的 lwip_standard_checksum()程序。
用户可以通过#define LWIP_CHKSUM <your_checksum_routine>宏定义，使用用户的函数来取代标准函数。
There are C examples given in inet.c or you might want to
craft an assembly function for this. RFC1071 is a good
introduction to this subject.
在 inet.c文件中有 C程序的例子。你可能想要为之编制一个汇编程序。RFC1071对该主题做了详细的介绍。
Other significant improvements can be made by supplying
assembly or inline replacements for htons() and htonl()
if you're using a little-endian architecture.
如果你采用小端结构，可通过采用汇编或内联汇编嵌入来实现 htons()和 htonl()以获得重要的性能提升。
#define LWIP_PLATFORM_BYTESWAP 1
#define LWIP_PLATFORM_HTONS(x) <your_htons>
#define LWIP_PLATFORM_HTONL(x) <your_htonl>
Check your network interface driver if it reads at
a higher speed than the maximum wire-speed. If the
hardware isn't serviced frequently and fast enough
buffer overflows are likely to occur.
检测你的网络接口驱动是否读取的速度高于最大的线速。如果硬件不能足够快速、频繁地服务，那么缓存溢出就可能会发生
E.g. when using the cs8900 driver, call cs8900if_service(ethif)
as frequently as possible. When using an RTOS let the cs8900 interrupt
wake a high priority task that services your driver using a binary
semaphore or event flag. Some drivers might allow additional tuning
to match your application and network.
例如，在使用 CS8900驱动时，尽可能频繁地调用 cs8900if_service(ethif)。
当运行实时操作系统时，让 CS8900中断唤醒较高优先级的任务，而该任务采用信号量或事件标志来为你的驱动提供服务。
一些驱动可能允许采取其他的调整来匹配你的应用程序和网络。
For a production release it is recommended to set LWIP_STATS to 0.
Note that speed performance isn't influenced much by simply setting
high values to the memory options.
对于正式发行的产品，推荐将 LWIP_STATS置 0。注释：简单地将内存选项置高对速度性能并没有太大影响。
For more optimization hints take a look at the lwIP wiki.
想要获得更多的优化提示，请查看 LwIP维基。
--- Zero-copy MACs 零拷贝 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.
为了实现传输的 0拷贝，传递到原始 API 的数据必须保持不被更改直到被发送。
因为当入队待发的数据包在入队后发送（或写）函数将返回，入队后的数据也必须保持不变。
This implies that PBUF_RAM/PBUF_POOL pbufs passed to raw-API send functions
must *not* be reused by the application unless their ref-count is 1.
这意味着传递给原始 API发送函数的 pbufs不能被应用程序重复使用，除非他们的 ref-count为 1。
For no-copy pbufs (PBUF_ROM/PBUF_REF), data must be kept unchanged, too,
but the stack/driver will/must copy PBUF_REF'ed data when enqueueing, while
PBUF_ROM-pbufs are just enqueued (as ROM-data is expected to never change).
对于非拷贝型 pbufs，数据也必须保持不变，但当入队时，堆栈/驱动将/必须拷贝 PBUF_REF'ed数据，PBUF_ROM-pbufs仅是被入队（因为 ROM-data不会被改变）。
Also, data passed to tcp_write without the copy-flag must not be changed!
此外，没有拷贝标志 copy-flag传递到 tcp_write函数的数据禁止改变。
Therefore, be careful which type of PBUF you use and if you copy TCP data
or not!
因此，要留意你所使用的 PBUF的类型，以及是否拷贝 TCP数据。
阅读全文
