LWIP移植说明文档

翻译：Lizhiming Mail：seu.zhiming@gmail.com 1 / 43 LwIP移植 说明 关于失联党员情况说明岗位说明总经理岗位说明书会计岗位说明书行政主管岗位说明书 文档 该译文以 LwIP-1.4.0的移植文档为蓝本 本文档翻译了 LwIP-1.4.0的移植说明文档，包括原始 API及 SYS_ARCH接口的说明文档。由于译者 水平所限，译文存在很多不确切或错误的翻译，还请网友多指正。需要特别提出的是，LwIP的 SYS_ARCH 接口部分参考了焦海波“uC/OS-II 平台下的 LwIP 移植 笔记 哲学笔记pdf明清笔记pdf政法笔记下载课堂笔记下载生物化学笔记PDF ”一文。在此，将译文放在网络上共享， 愿与网友共同学习、共同进步。 翻译：Lizhiming Mail：seu.zhiming@gmail.com 2 / 43 INTRODUCTION lwIP is a small independent implementation of the TCP/IP protocol suite that has been developed by Adam Dunkels at the Computer and Networks Architectures (CNA) lab at the Swedish Institute of Computer Science (SICS). LwIP是一个 TCP/IP 协议 离婚协议模板下载合伙人协议 下载渠道分销协议免费下载敬业协议下载授课协议下载 簇的小型独立实现，该协议簇由瑞士 SICS计算机网络实验室的 Adam开发。 The focus of the lwIP TCP/IP implementation is to reduce the RAM usage while still having a full scale TCP. This making lwIP suitable for use in embedded systems with tens of kilobytes of free RAM and room for around 40 kilobytes of code ROM. LwIP TCP/IP实现关注的是减小 RAM的使用，同时拥有完整尺度的 TCP协议。这使得 LwIP适合于在只拥有数十 k字 节 RAM和 40k左右 ROM的嵌入式系统中使用。 FEATURES 特性 * IP (Internet Protocol) including packet forwarding over multiple network interfaces Internet协议：包括通过多接口发送报文 * ICMP (Internet Control Message Protocol) for network maintenance and debugging Internet控制报文协议：用于网络维护和调试 * IGMP (Internet Group Management Protocol) for multicast traffic management Internet组管理协议：用于多播通信管理 * UDP (User Datagram Protocol) including experimental UDP-lite extensions 用户数据报协议：包括实验性 UDP扩展 * TCP (Transmission Control Protocol) with congestion control, RTT estimation and fast recovery/fast retransmit 传输控制协议：拥有阻塞控制、RTT估计和快速恢复、快速传输等功能。 * Specialized raw/native API for enhanced performance 专门的原始 API用于提高性能。 * Optional Berkeley-like socket API 可选的伯克利形式 SOCKET的 API * DNS (Domain names resolver) 域名解析（域名系统） * SNMP (Simple Network Management Protocol) 简单网络管理协议 * DHCP (Dynamic Host Configuration Protocol) 动态主机配置协议 * AUTOIP (for IPv4, conform with RFC 3927) 自动 IP * PPP (Point-to-Point Protocol) 点对点传输协议 * ARP (Address Resolution Protocol) for Ethernet 英特网地址解析协议 翻译：Lizhiming Mail：seu.zhiming@gmail.com 3 / 43 Raw TCP/IP interface for lwIP LwIP原始 TCP/IP接口 Authors: Adam Dunkels, Leon Woestenberg, Christiaan Simons 作者：Adam Dunkels, Leon Woestenberg, Christiaan Simons 翻译:Lizhiming 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.h - netbuf.h - netdb.h 翻译：Lizhiming Mail：seu.zhiming@gmail.com 4 / 43 - netifapi.h - sockets.h - sys.h 同样地，被其他线程或中断服务程序调用的函数是非常地有限。只有如下 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 翻译：Lizhiming Mail：seu.zhiming@gmail.com 5 / 43 --- 回调函数 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, struct ip_addr *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. 翻译：Lizhiming Mail：seu.zhiming@gmail.com 6 / 43 将 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. 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. 命令一个 PCB 开始监听即将到来的连接。当新到来的连接被接受，指定 tcp_accept()函数将被调用。PCB 必须通过 tcp_bind()绑定到本地的一个端口。 tcp_listen()返回一个新的连接标识。同时，作为参数传递给该函数的 PCB 将被释放。原因是处于监听状态的连接仅 需少量的内存，因此 tcp_listen()将回收初始连接的内存，并为监听连接分配一个新的较小的内存块。 当用于监听连接的内存不足时（不可获得时），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执行内务操作任务，比如允许 后续即将到来的连接进入监听后备队列。 - 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 翻译：Lizhiming Mail：seu.zhiming@gmail.com 7 / 43 listening connection. 指定应调用的回调函数，当在一个监听连接上到来一个新的连接时。 - err_t tcp_connect(struct tcp_pcb *pcb, struct ip_addr *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. 设置 PCB以连接至远程主机，并发送用于打开连接的初始 SYN参数。 tcp_connect()函数立即返回；它并不等待连接的正确建立，而是在连接建立时调用第四个参数指定的回调函数。如果 连接不能正常建立，或因其他主机拒绝建立连接，或其他主机没有应答，该 pcb（以 pcb_err注册，见下文）的“err” 回调函数将被调用。 如果对入队的 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, void *dataptr, u16_t len,u8_t copy) Enqueues the data pointed to by the argument dataptr. The length of the data is passed as the len parameter. The copy argument is either 0 or 1 and indicates whether the new memory should be allocated for the data to be copied into. If the argument is 0, no new memory should be allocated and the data should only be referenced by pointer. 翻译：Lizhiming Mail：seu.zhiming@gmail.com 8 / 43 将数据入队写至由参数 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) 翻译：Lizhiming Mail：seu.zhiming@gmail.com 9 / 43 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, u8_t interval, err_t (* poll)(void *arg, struct tcp_pcb *tpcb)) 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的间隔 表 关于同志近三年现实表现材料材料类招标技术评分表图表与交易pdf视力表打印pdf用图表说话 pdf 示应用程序每隔 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. The pcb is deallocated by the TCP code after a call to tcp_close(). 关闭连接。如果关闭连接的内存不可获得，该函数将返回 ERR_MEM。在这种情况下，应用程序应通过确认回调函数或轮 询功能来等待并重试。如果关闭成功，该函数返回 ERR_OK。 在 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. 翻译：Lizhiming Mail：seu.zhiming@gmail.com 10 / 43 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. 通过向远程主机发送一个复位语句以中止连接。同时，pcb释放。该函数不会失败。 注意：当从 TCP 的任何一个回调函数中调用该函数时，需确保返回值为 ERR_ABRT（从不返回 ERR_ABRT，否则将冒险 存取已释放的内存，或内存泄露）。 如果由于发生错误连接中止，应用程序应通过 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接口 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接口