第 2 章 - 安装和使用 Azure RTOS NetX
本章旨在介绍与安装、设置和使用高性能网络堆栈 Azure RTOS NetX 相关的各种问题。
主机注意事项
嵌入式开发通常在 Windows 或 Linux (Unix) 主机上进行。 在主机上编译、链接应用程序并生成可执行文件之后，应用程序将下载到目标硬件，以便执行。
通常，目标下载是在开发工具的调试器内完成的。 在下载后，调试器负责提供目标执行控件（“执行”、“暂停”、“断点”等）以及对内存和处理器寄存器的访问。
大多数开发工具调试器通过 JTAG (IEEE 1149.1) 和后台调试模式 (BDM) 等芯片调试 (OCD) 连接与目标硬件进行通信。 调试器还通过线路内仿真 (ICE) 连接与目标硬件进行通信。 OCD 和 ICE 连接提供可靠的解决方案，使对目标常驻软件的入侵最少。
对于主机上使用的资源，NetX 的源代码以 ASCII 格式提供，并需要大约 1 MB 的主机计算机硬盘空间。
目标注意事项
NetX 要求目标有 5 到 45 KB 只读内存 (ROM)。 NetX 线程堆栈和其他全局数据结构要求目标另外有 1 到 5 KB 的随机存取内存 (RAM)。
此外，NetX 要求使用两个 ThreadX 计时器对象和一个 ThreadX mutex 对象。 这些设施用于处理 NetX 协议堆栈中的定期处理需求和线程保护。
产品分发
NetX 正在由 NetX Duo 取代。 有关详细信息，请参阅 NetX Duo 存储库。
下面是原始 NetX 包中的几个重要文件的列表：
- nx_api.h：C 头文件，包含所有系统等式、数据结构和服务原型。
- nx_port.h：C 头文件，包含所有开发工具及目标特定的数据定义和结构。
- demo_netx.c：C 文件，包含小型演示应用程序。
- nx.a（或 nx.lib）：随标准包一起分发的 NetX C 库的二进制版本。 |
安装 NetX
NetX 正在由 NetX Duo 取代。 有关使用和安装此功能作为 NetX Duo 的一部分的详细信息，请参阅 NetX Duo 存储库。 有关文档，请参阅 NetX Duo 文档。
重要
应用程序软件需要访问 NetX 库文件（通常为 nx.a 或 nx.lib）和 C 包含文件 nx_api.h 和 nx_port.h。 为实现此目的，可以设置开发工具的相应路径，或者将这些文件复制到应用程序开发区域。
使用 NetX
若要使用 NetX，应用程序代码必须在编译期间包括 nx_api.h，并且必须与 NetX 库 nx.a（或 nx.lib）链接。
下面是生成 NetX 应用程序所需的四个步骤：
- 在所有使用 NetX 服务或数据结构的应用程序文件中包括 nx_api.h 文件。
- 通过从 tx_application_define 函数或应用程序线程调用 来初始化 NetX 系统。
- 创建 IP 实例，在调用 nx_system_initialize 后启用地址解析协议 (ARP)（如有必要）以及任何套接字。
- 编译应用程序源并与 NetX 运行时库 nx.a（或 nx.lib）链接。 生成的图像可下载到目标并执行！
疑难解答
每个 NetX 端口都提供一个或多个在实际网络上或通过模拟网络驱动程序执行的示例。 先运行示例系统始终是一个不错的主意。
如果示例系统无法正常运行，请执行以下操作来缩小问题范围：
- 确定示例的运行量。
- 增大任何新应用程序线程中的堆栈大小。
- 使用配置选项部分中列出的合适调试选项重新编译 NetX 库。
- 检查 NX_IP 结构以查看正在发送还是接收数据包。
- 检查默认数据包池，查看是否存在可用的数据包。
- 请确保网络驱动程序正在提供 ARP 和 IP 数据包并且其标头在 4 字节边界上（适用于需要 IP 连接的应用程序）。
- 暂时跳过最近所做的任何更改，以查看问题是否消失或发生更改。 此类信息对我们的支持工程师非常有用。
按照客户支持中心主题中概述的步骤，发送从故障排除步骤中收集的信息。
配置选项
使用 NetX 构建 NetX 库和应用程序时，有几个配置选项。 除非另有说明，否则可在应用程序源、命令行或 nx_user.h include 文件中配置选项。
重要
只有当应用程序和 NetX 库在构建时定义了 NX_INCLUDE_USER_DEFINE_FILE，才会应用在 nx_user.h 中定义的选项。
以下部分列出了 NetX 中可用的配置选项。
系统配置选项
| 选项 | 说明 |
|---|---|
| X_DEBUG | 定义后，此选项用于启用 RAM 以太网网络驱动程序提供的可选打印调试信息。 |
| NX_DISABLE_ERROR_CHECKING | 定义后，此选项用于删除基本 NetX 错误检查 API 并提高性能。 不受禁用错误检查影响的 API 返回代码将在 API 定义中以粗体字样列出。 此定义通常在应用程序调试之后使用，使用它可提高性能并减少代码大小。 |
| NX_DRIVER_DEFERRED_PROCESSING | 定义后，此选项用于启用延迟网络驱动程序数据包处理。 它允许网络驱动程序将数据包放置在 IP 实例上，并从 NetX 内部 IP 帮助程序线程中调用真实处理例程。 |
| NX_ENABLE_EXTENDED_NOTIFY_SUPPORT | 允许堆栈中有更多回调挂钩。 BSD 包装层使用这些回调函数。 默认情况下，未定义此选项。 |
| NX_ENABLE_SOURCE_ADDRESS_CHECK | 定义后，此选项允许检查传入数据包的源地址。 默认已禁用此选项。 |
| NX_LITTLE_ENDIAN | 定义后，此选项用于对 little endian 环境执行必要的字节交换，以确保协议标头使用正确的 big endian 格式。 请注意，默认值通常在 nx_port.h 中设置。 |
| NX_MAX_PHYSICAL_INTERFACES | 指定设备上物理网络接口的总数。 默认值为 1，在 nx_api.h 中定义。 设备必须至少有一个物理接口。 请注意，此数量不包括环回接口。 |
| NX_PHYSICAL_HEADER | 指定帧的物理标头的大小（以字节为单位）。 默认值为 16（基于与 32 位边界对齐的典型 14 字节以太网帧），在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h（例如 nx_user.h）之前定义该值，以替代默认值。 |
ARP 配置选项
| 选项 | 说明 |
|---|---|
| NX_ARP_DEFEND_BY_REPLY | 定义后，允许 NetX 通过发送 ARP 响应保护其 IP 地址。 |
| NX_ARP_DEFEND_INTERVAL | 定义 ARP 模块发出下一个防御数据包以响应指示地址冲突的传入 ARP 消息的时间间隔（以秒为单位）。 |
| NX_ARP_DISABLE_AUTO_ARP_ENTRY | 已重命名为 NX_DISABLE_ARP_AUTO_ENTRY。 尽管此设计仍受支持，但建议使用新设计以使用 NX_DISABLE_ARP_AUTO_ENTRY。 |
| NX_ARP_EXPIRATION_RATE | 指定 ARP 条目保持有效的秒数。 默认值为 0 时，将禁用 ARP 条目的过期或老化，在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_ARP_MAC_CHANGE_NOTIFICATION_ENABLE | 已重命名为 NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION。 尽管此设计仍受支持，但建议使用新设计以使用 NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION。 |
| NX_ARP_MAX_QUEUE_DEPTH | 指定在等待 ARP 响应时可以排队的数据包的最大数量。 默认值为 4，在 nx_api.h 中定义。 |
| NX_ARP_MAXIMUM_RETRIES | 指定在没有 ARP 响应的情况下进行 ARP 重试的最大次数。 默认值为 18，在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_ARP_UPDATE_RATE | 指定 ARP 重试之间的秒数。 默认值为 10（表示 10 秒），在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_DISABLE_ARP_AUTO_ENTRY | 定义后，此选项用于禁止在 ARP 缓存中输入 ARP 请求信息。 |
| NX_DISABLE_ARP_INFO | 定义后，此选项用于禁用 ARP 信息收集。 |
| NX_ENABLE_ARP_MAC_CHANGE_NOTIFICATION | 定义后，允许 ARP 调用回调通知函数来检测 MAC 地址是否已更新。 |
ICMP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_ICMP_INFO | 定义后，此选项用于禁用 ICMP 信息收集。 |
| NX_DISABLE_ICMP_RX_CHECKSUM | 禁用接收到的 ICMP 数据包上的 ICMP 校验和计算。 当网络接口驱动程序能够验证 ICMP 校验和，且应用程序不使用 IP 拆分功能时，此选项很有用。 默认不定义此选项。 |
| NX_DISABLE_ICMP_TX_CHECKSUM | 禁用传输的 ICMP 数据包上的 ICMP 校验和计算。 当网络接口驱动程序能够计算 ICMP 校验和，且应用程序不使用 IP 拆分功能时，此选项很有用。 默认不定义此选项。 |
IGMP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_IGMP_INFO | 定义后，此选项用于禁用 IGMP 信息收集。 |
| NX_DISABLE_IGMPV2 | 定义后，此选项用于禁用 IGMPv2 支持，NetX 仅支持 IGMPv1。 默认情况下，此选项未设置，且在 nx_api.h 中定义。 |
| NX_MAX_MULTICAST_GROUPS | 指定可以联接的多播组的最大数量。 默认值为 7，在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
IP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_FRAGMENTATION | 定义后，此选项用于禁用 IP 拆分和重组逻辑。 |
| NX_DISABLE_IP_INFO | 定义后，此选项用于禁用 IP 信息收集。 |
| NX_DISABLE_IP_RX_CHECKSUM | 定义后，此选项用于禁用接收到的 IP 数据包上的校验和逻辑。 当网络设备能够验证 IP 头校验和，且应用程序不使用 IP 拆分功能时，此选项很有用。 |
| NX_DISABLE_IP_TX_CHECKSUM | 定义后，此选项用于禁用发送的 IP 数据包上的校验和逻辑。 当基础网络设备能够生成 IP 标头校验和，且应用程序不使用 IP 拆分功能时，此选项很有用。 |
| NX_DISABLE_LOOPBACK_INTERFACE | 定义后，此选项用于禁用 NetX 对环回接口的支持。 |
| NX_DISABLE_RX_SIZE_CHECKING | 定义后，此选项用于禁用对接收到的数据包的大小检查。 |
| NX_ENABLE_IP_STATIC_ROUTING | 定义后，此选项用于启用 IP 静态路由，可在其中向目标地址分配特定的下一跃点地址。 默认情况下，IP 静态路由处于禁用状态。 |
| NX_IP_PERIODIC_RATE | 定义后，此选项用于指定 ThreadX 计时器时钟周期的数量（以秒为单位）。 默认值派生自 ThreadX 符号 TX_TIMER_TICKS_PER_SECOND，默认情况下，此值设置为 100（10ms 计时器）。 应用程序应谨慎修改此值，因为其他 NetX 模块将从 NX_IP_PERIODIC_RATE 派生计时信息。* |
| NX_IP_ROUTING_TABLE_SIZE | 定义后，此选项用于设置 IP 静态路由表中的最大条目数，这是传出接口以及 |
| 给定目标地址的下一个跃点地址的列表。 默认值为 8，在 nx_api.h. 中定义。此符号仅在定义 NX_ENABLE_IP_STATIC_ROUTING 时使用。 |
数据包配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_PACKET_INFO | 定义后，此选项用于禁用数据包池信息收集。 |
| NX_PACKET_HEADER_PAD | 定义后，此选项允许在 NX_PACKET 控制块的末尾处进行填充。 要填充的 ULONG 字词的数量由 NX_PACKET_HEADER_PAD_SIZE 定义 。 |
| NX_PACKET_HEADER_PAD_SIZE | 设置要填充到 NX_PACKET 结构中的 ULONG 字词的数量，允许数据包有效负载区从所需的 |
| 对齐位置开始。 当缓冲区描述符点直接传入 NX_PACKET 有效负载区，且网络接口接收逻辑或缓存操作逻辑要求缓冲区起始地址满足特定的对齐要求时，此功能很有用。 仅当定义了 NX_PACKET_HEADER_PAD 时，此值才有效。 |
RARP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_RARP_INFO | 定义后，此选项用于禁用 RARP 信息收集。 |
TCP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_RESET_DISCONNECT | 定义后，当提供的超时值指定为 NX_NO_WAIT 时，将禁用断开连接期间的重置处理。 |
| NX_DISABLE_TCP_INFO | 定义后，此选项用于禁用 TCP 信息收集。 |
| NX_DISABLE_TCP_RX_CHECKSUM | 定义后，此选项用于禁用接收到的 TCP 数据包上的校验和逻辑。 仅当链路层具有可靠的校验和或 CRC 处理，或者接口驱动程序能够验证硬件中的 TCP 校验和时，此选项才很有用。 |
| NX_DISABLE_TCP_TX_CHECKSUM | 定义后，此选项用于禁用用于发送 TCP 数据包的校验和逻辑。 仅当接收网络节点接收到禁用了 TCP 校验和逻辑，或者基础网络驱动程序能够生成 TCP 校验和时，此选项才很有用。 |
| NX_ENABLE_TCP_KEEPALIVE | 定义后，此选项用于启用可选的 TCP KeepAlive 计时器。 默认设置未启用。 |
| NX_ENABLE_TCP_MSS_CHECKING | 定义后，可以在接受 TCP 连接之前验证对等 MSS 的最小值。 若要使用此功能，必须定义符号 NX_ENABLE_TCP_MSS_MINIMUM。 默认情况下不启用此选项。 |
| NX_ENABLE_TCP_WINDOW_SCALING | 启用 TCP 应用程序的窗口缩放选项。 定义后，在 TCP 连接阶段会协商窗口缩放选项，且应用程序可以指定大于 64 K 的窗口大小。 未启用默认设置（未定义）。 |
| NX_MAX_LISTEN_REQUESTS | 指定服务器侦听请求的最大数量。 默认值为 10，在 nx_api.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_ACK_EVERY_N_PACKETS | 指定发送 ACK 之前要接收的 TCP 数据包的数量。 注意，如果启用了 NX_TCP_IMMEDIATE_ACK，但未启用 NX_TCP_ACK_EVERY_N_PACKETS，则此值将自动设置为 1，以实现向后兼容性 。 |
| NX_TCP_ACK_TIMER_RATE | 指定如何划分系统时钟周期 (NX_IP_PERIODIC_RATE) 的数量，以计算 TCP 延迟 ACK 处理的计时器速率。 默认值为 5（表示 200ms），在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_ENABLE_KEEPALIVE | 已重命名为 NX_ENABLE_TCP_KEEPALIVE。 尽管此设计仍受支持，但建议使用新设计以使用 NX_ENABLE_TCP_KEEPALIVE。 |
| NX_TCP_ENABLE_WINDOW_SCALING | 已重命名为 NX_ENABLE_TCP_WINDOW_SCALING。 尽管此设计仍受支持，但建议使用新设计以使用 NX_ENABLE_TCP_WINDOW_SCALING。 |
| NX_TCP_FAST_TIMER_RATE | 指定如何划分 NetX 的内部时钟周期 (NX_IP_PERIODIC_RATE) 的数量，以计算快速 TCP 计时器速率。 快速 TCP 计时器用于驱动各种 TCP 计时器，包括延迟 ACK 计时器。 默认值为 10，表示 100ms（假设 ThreadX 计时器在 10ms 时运行）。 此值在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_IMMEDIATE_ACK | 定义后，此选项用于启用可选的 TCP 即时 ACK 响应处理。 定义此符号等效于将 NX_TCP_ACK_EVERY_N_PACKETS 定义为 1。 |
| NX_TCP_KEEPALIVE_INITIAL | 指定在 KeepAlive 计时器激活之前处于非活动状态的秒数。 默认值为 7200（表示 2 小时），在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_KEEPALIVE_RETRIES | 指定在连接被视为中断之前允许 KeepAlive 重试的次数。 默认值为 10（表示 10 次重试），在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_KEEPALIVE_RETRY | 指定在连接的另一方没有响应时，KeepAlive 计时器重试之间间隔的秒数。 默认值为 75（表示重试之间间隔 75 秒），在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_MAX_OUT_OF_ORDER_PACKETS | 用于定义可在 TCP 套接字接收队列中保留的无序 TCP 数据包最大数量的符号。 此符号可用于限制在 TCP 接收套接字中排队的数据包数量，防止数据包池耗尽。 默认情况下未定义此符号，因此在 TCP 套接字中排队的无序数据包数没有限制。 |
| NX_TCP_MAXIMUM_RETRIES | 指定在连接被视为中断之前允许的数据传输重试次数。 默认值为 10（表示 10 次重试），在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_MAXIMUM_TX_QUEUE | 指定 TCP 发送请求被挂起或拒绝之前 TCP 传输队列的最大深度。 默认值为 20，这表示在任意给定时间，传输队列中最多可以有 20 个数据包。 请注意，数据包将保留在传输队列中，直到从连接的另一端接收到涵盖部分或全部数据包数据的 ACK。 此常量在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| X_TCP_MSS_CHECKING_ENABLED | 已重命名为 NX_ENABLE_TCP_MSS_CHECKING。 尽管此设计仍受支持，但建议使用新设计以使用 NX_ENABLE_TCP_MSS_CHECKING。 |
| NX_TCP_MSS_MINIMUM | 定义 NetX TCP 模块接受的最小 MSS 值的符号。 此功能由 NX_ENABLE_TCP_MSS_CHECK 启用 |
| NX_TCP_RETRY_SHIFT | 指定重试之间的重新传输超时期限如何变化。 如果此值为 0，则初始重新传输超时与后续重新传输超时相同。 如果此值为 1，则每个连续重新传输时长为前一个的 2 倍。 如果此值为 2，则每个后续的重新传输超时时长为前一个的 4 倍。 默认值为 0，在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
| NX_TCP_TRANSMIT_TIMER_RATE | 指定如何划分系统时钟周期 (NX_IP_PERIODIC_RATE) 的数量，以计算 TCP 传输重试处理的计时器速率。 默认值为 1，表示 1 秒，在 nx_tcp.h 中定义。 应用程序可以在包含 nx_api.h 之前定义该值，以替代默认值。 |
UDP 配置选项
| 选项 | 说明 |
|---|---|
| NX_DISABLE_UDP_INFO | 定义后，此选项用于禁用 UDP 信息收集。 |
| NX_DISABLE_UDP_RX_CHECKSUM | 定义后，此选项用于禁用传入 UDP 数据包上的 UDP 校验和计算。 当网络接口驱动程序能够验证硬件中的 UDP 标头校验和，且应用程序不启用 IP 拆分逻辑时，此选项很有用。 |
| NX_DISABLE_UDP_TX_CHECKSUM | 定义后，此选项用于禁用传出 UDP 数据包上的 UDP 校验和计算。 当网络接口驱动程序能够计算 UDP 标头校验和，并在传输数据之前将值插入 IP 标头，且应用程序不启用 IP 拆分逻辑时，此选项很有用。 |
NetX 版本 ID
当前版本的 NetX 在运行时可供用户和应用程序软件使用。 程序员可以从 nx_port.h 文件获取 NetX 版本。 此外，该文件还包含相应端口的版本历史记录。 应用程序软件可以通过在 nx_port.h 中检查全局字符串 _nx_version_id 来获取 NetX 版本 。
应用程序软件还可以从以下常量中获取版本信息，这些常量在 nx_api.h 中定义。
这些常量通过名称和产品的主要版本和次要版本来确定产品的当前版本。
#define EL_PRODUCT_NETX
#define NETX_MAJOR_VERSION
#define NETX_MINOR_VERSION