可选通用组件¶

这些声明来自公共头文件。选择、生命周期、支持的执行模式和物理资源授权范围仍以对应设计及支持记录为准。

字节传输、TLS 与 MQTT 装配¶

byte_stream.h 定义了带有限绝对截止时间的即时部分读取和复制写入。SUCCESS 表示本地字节准入，不表示已交付对端；BUSY 且字节数为零时，需要所有者显式推进。字节流操作返回后，不再借用调用者的缓冲区。可选的 Nexus::LwIPTCP 客户端在锁定的 NO_SYS IPv4 协议栈之上实现此接口。执行器、对端选择、可信时间、熵源以及停机和重连策略仍由产品负责。

调用者	选定目标与头文件	边界
通用以太网适配器调用者	`Nexus::LwIP`, `nexus/network/lwip_adapter.h`	Nexus 类型；不暴露厂商头文件或配置宏
通用 TCP 字节接口调用者	`Nexus::LwIPTCP`, `nexus/network/lwip_tcp.h`	不透明客户端与既有只读字节接口
静态 netif 装配	`Nexus::LwIPStorage`, `nexus/network/lwip_storage.h`	锁定版本的精确 netif／适配器布局，仅供装配使用
静态 TCP 装配	`Nexus::LwIPTCPStorage`, `nexus/network/lwip_tcp_storage.h`	锁定版本的精确 PCB／pbuf 客户端布局，仅供装配使用

装配代码仅初始化一次 lwIP，并提供有效的网络适配器、调用者拥有的存储以及正数接收帧预算。全部原始协议栈 API、回调、网络推进和客户端由同一串行 NO_SYS 执行器负责。接口的数据和控制调用必须位于原始回调之外；跨接口的嵌套修改以 BUSY 拒绝。组件不创建 socket 层、worker、调度器、锁、名称注册表或最大尺寸不透明对象池。TCP start 成功只表示准入 CONNECTING，不表示连接已经建立。首次有限连接截止时间不能延长。既有字节接口是带状态的句柄，不是就绪证明。

TCP 写入使用官方复制准入：正数部分写入计数表示调用者可立即复用输入，已排队数据仍保存在协议栈的有界存储中。之后的输出失败不能撤销该准入。诊断持续报告该失败，后续数据／推进调用在显式 abort 之前仍保持失败。RX 最多持有一条已接受的 pbuf 链；被拒收的链仍归 lwIP 所有。只对实际消费的字节返还接收额度。缓冲数据先于有序 FIN 交付，对端半关闭后仍允许写入。帧预算限制取得的帧数，不限制任意原始回调的总耗时。每次非零字节尝试最多可以执行一轮显式预算的网络推进。

官方 PCB 分配共享有界协议栈池及其回收策略。它可能推进待关闭连接，或回收 TIME_WAIT、LAST_ACK、CLOSING 及较低优先级的活动连接；即使新的 start 随后失败，也可能调用其他客户端的错误回调。本地拒绝表示该客户端不保留新的引用，不承诺整个协议栈未发生变化。

生产者完成 join 后，所有者消费缓冲 RX，并在首次有限关闭截止时间内遇到 BUSY 时显式推进和重试 close。该截止时间不能延长。超时后必须显式 abort，存储在此期间仍须有效；abort 丢弃本地数据并撤除回调引用。close 成功仅证明此客户端上下文已完成最后一次协议栈访问。官方协议栈仍可能保留待后续处理的 FIN 及 TIME_WAIT 状态。在产品的完整协议栈停机／重启流程允许撤回之前，网络适配器、全局存储池、定时器和未改变的时钟域都必须保持有效。客户端上下文脱离回调引用不证明全局协议栈停机或 MAC／PHY 已排空。

普通 TLS／MQTT 调用者包含 tls.h 或 client.h，并链接 Nexus::TLS 或 Nexus::CoreMQTT。公共会话类型是不透明类型，不暴露厂商头文件或配置宏。只有静态装配翻译单元选择 Nexus::TLSStorage 与 nexus/tls/storage.h，或 Nexus::CoreMQTTStorage 与 nexus/mqtt/core_mqtt_storage.h，以分配锁定后端的精确布局。显式存储目标必须局限于装配代码；字段是实现状态，不是业务控制 API 或二进制 ABI 承诺。产品显式调用 nexus_add_tls() 或 nexus_add_coremqtt() 创建选定目标。

TLS 配置是单一串行 TLS 1.2 客户端／PSA 域，使用 ECDHE-ECDSA P-256 和 AES-128-GCM/SHA-256。它要求显式 DER 信任材料、可信 UTC 和经过审查的熵质量声明。调用者提供的 64 KiB 内存区和 512 B TX 暂存区不包含会话元数据、传输存储和栈。先 join 全部接口使用者，再 abort 会话，然后停止 runtime；失败或 BUSY 的清理仍保留资源。MQTT 3.1.1 配置提供 clean session 和 QoS0/1；回调仅在返回前借用传入视图。显式 DISCONNECT 和 TLS close 表示本地推进，不替代下层排空或对端确认。网络、TLS 和 MQTT 组件合同详细规定所有权及固定配置限制。

对于两种 Ethernet adapter 配置，link output 成功表示帧已被接纳。失败的 SETTLED TX 结果会保留，并通过 nx_lwip_adapter_service 报告一次；在该次观察之前，另一次 link output 不得覆盖或复用 TX 缓冲区。观察错误只会清除已经结清且不再被借用的请求。此机制不新增错误队列或实例存储，也不复位 MAC、重放数据包或选择产品恢复策略。ACTIVE 或 QUARANTINED 的借用仍被保留。TCP 字节 facade 保留其既有的连接失败策略；观察到帧错误不承诺恢复。

选定的 lwIP RX 负载借用¶

每个镜像选择一个单例 NO_SYS 协议栈配置。默认 Nexus::LwIP 和 Nexus::LwIPTCP 配置保留复制式 RX 及其既有存储布局。下列显式目标选择 RX 负载借用；CMake 拒绝在同一镜像中组合复制式与借用式配置，也拒绝将复制式 TCP 目标与借用式 adapter 存储组合。这些目标不创建第二个协议栈、netif、执行器、worker 或分配器。

调用者	选定目标与头文件	边界
借用式 RX adapter 调用方	`Nexus::LwIPLoanedRX`, `nexus/network/lwip_loaned_rx.h`	不透明 adapter；显式借用式启动
借用式 RX TCP 字节调用方	`Nexus::LwIPTCPLoanedRX`, `nexus/network/lwip_tcp.h`	既有的复制式字节流合同
静态借用式 RX 装配	`Nexus::LwIPLoanedRXStorage`, `nexus/network/lwip_loaned_rx_storage.h`	精确的 adapter、帧槽和 custom-pbuf 存储
基于借用式 RX 的静态 TCP 装配	`Nexus::LwIPTCPLoanedRXStorage`, `nexus/network/lwip_tcp_storage.h`	精确的选定 TCP 布局；同时提供借用式 adapter 存储

owner 只初始化 lwIP 一次，并通过 nx_lwip_loaned_adapter_start 挂接。须提供零初始化且互不重叠的 adapter、TX、片段视图、帧槽和 custom-pbuf 片段存储。选择非零 slot_count，并提供至少 slot_count * base.rx_capacity 个片段；片段容量须按实际 provider 的描述符布局确定。MAC 负载区间也必须与 adapter、TX／视图及槽／片段存储互不重叠。获取到的无效区间会被释放，不会交付。所有 raw API、引用操作、回调、service 和 stop 共用同一个串行、不可重入的任务 owner。对仍存活实例的再次挂接或重入挂接不会清除保留中的引用或令牌。

Nexus::LwIPLoanedRXStorage -> adapter + caller slots/pieces
MAC exact RX loan -> copied REF header[136] -> immutable ROM tails
final pbuf_free -> slot ready -> owner service/stop -> exact MAC release

每个帧槽最多将 136 B 复制到自身可写的 PBUF_REF 前缀。该前缀覆盖 14 B Ethernet 头、最大 60 B IPv4 头和最大 60 B TCP 头，包括官方 TCP 输入路径会原地更新的字段。前缀可能包含负载；不超过 136 B 的帧会被完整复制。只有前缀之后的字节通过 PBUF_ROM 尾部引用原始、不可变的 MAC 片段。raw 消费方必须将这些尾部视为只读，并在写入前克隆。这是 RX 负载尾部零复制；不提供整帧或 TX 零复制。ICMP echo 使用官方的复制后回复路径。VLAN 交付、IPv6、DHCP、DNS 和 IP 重组仍未选用。

保留的头部或尾部 pbuf 引用会使其帧槽及精确 MAC 借用持续存活。custom-pbuf 的最终释放只标记片段已归还；它从不调用 provider，也不重新武装 DMA。在每个片段的最后一个引用都结束后，后续 owner service 或 stop 才释放精确借用。释放失败会保留令牌与存储，并关闭后续 adapter 接纳。产品须先关闭 PCB，并等待 raw 用户、回调、队列和观察者退出。只要仍有任何 pbuf 引用，stop 就返回 BUSY；只有精确 RX 释放及既有 MAC／TX 撤离义务均已完成后才解除挂接。排空失败绝不撤销借用。

槽数是元数据容量，不是 provider 能力，也不是 ACK 推进承诺。并发获取还要求 provider 支持独立借用，并为实际帧提供足够描述符。维护中的 enhanced F407 和 GD470 MAC 引擎在软件模型中支持独立持有 RX 头及逆序释放；该事实不建立通用容量、无损运行或任意保留流量下的推进保证。产品须针对所选帧布局和工作负载预算并释放借用。

选定的借用式配置保留两个备用的 512 B PBUF_POOL 载荷块；复制式配置仍使用既有的 24 块。16 KiB arena 和其他固定协议池保持不变。RX custom-pbuf 元数据、136 B 前缀、MAC 缓冲区和复制式 TX 缓冲区仍需调用方另行提供存储。TX 和 ICMP 回复回退可使用既有的有界 RAM 分配器。该池容量需要维护的组织 fork，仅让显式 custom-RX／custom-pbuf 配置豁免原版 PBUF_POOL／TCP_WND 容量启发式检查。其他协议栈 sanity 检查全部保留。此豁免不能证明原版上游也准入该配置，或证明完整 SRAM 可容纳。标称池计数不是完整 SRAM 测量。

C11 仅链接的外部开发配置探针使用两个帧槽、四个 piece、2048 B 主栈且无 libc heap。选定镜像通过 32 KiB SRAM 预算。对于两款参考芯片，复制式配置的 BIN 字节和调用方存储均与同一源码、包含公共 TX 结果可观察性改进的基线一致。

仅链接参考配置	复制式 RX Flash／SRAM（B）	借用式 RX Flash／SRAM（B）
STM32F407VE	32616 / 35416	33244 / 24344
GD32F470ZG	33920 / 35388	34548 / 24316

这些探针没有提供真实的 MAC 描述符环或载荷缓冲区。在此精确配置中，选定 adapter 多占用 628 B Flash，总 SRAM 减少 11072 B。保持 adapter 行为和布局不变，将选定池从 24 块减少到两块可节省 11616 B。这些数据来自镜像／链接测量；已安装 SDK 资格及实际 DMA／cache、PHY、吞吐量、延迟和物理 HIL 证据仍须独立取得。

软件主机互通参考链路¶

FIG-32 描述主机测试的数据流参考，不是产品架构或 MCU 网络资格。双向实线在两条独立 TCP 连接上传送同一密文：Nexus 客户端与仅用于测试的 lwIP 对端之间使用软件以太网帧，透明中继与本地 Mosquitto 之间使用主机 socket。虚线标出唯一的 TLS 会话，其端点是 Nexus TLS 客户端和 Mosquitto；中继不解密或终止 TLS。每个 lwIP 进程拥有各自的串行协议栈和时钟。可编辑 DOT、网络合同以及维护的中继工装给出图的源码及生命周期边界。

主机工装使用软件帧接口和受控服务，执行实际锁定的协议栈与协议实现。直接 POSIX TLS／MQTT 工装和完整 lwIP／TCP 中继工装各自保留执行证据。模型以太网或真实主机 broker 都不证明板卡接线、物理 PHY／DMA、MCU 熵质量、实测资源峰值、安装版 SDK 验收或 HIL。

byte_stream.h¶

不保留缓冲区的即时部分字节传输。

作者 Nexus Team

struct nx_byte_stream_ops_t¶

#include <byte_stream.h>

用于串行化非阻塞字节流的只读方法。

备注

每次调用均使用传输层明确时间域内的有限绝对单调截止时间。调用不等待、不创建工作线程，也不在返回后保留输入/输出缓冲区。已接受的写入将字节复制到传输层自己的有界存储中；不承诺对端收到。非空写入 SUCCESS 时接受 1..requested 字节；读取 SUCCESS 时取得 1..requested 字节。读取计数为零的 SUCCESS 表示正常 EOF。BUSY 的计数为零，表示所有者显式推进后重试。其他结果均为错误，不能用来变相表示 would-block。零字节调用返回 SUCCESS/计数零，不执行下层 I/O。输出计数与全部缓冲区及有效传输存储互不重叠。传输层、方法表和上下文必须存活至全部使用方及其关闭操作结束。

公共成员

nx_result_t (*write)(void *context, const uint8_t *data, size_t bytes, size_t *accepted, nx_time_us_t deadline)¶

nx_result_t (*read)(void *context, uint8_t *data, size_t bytes, size_t *received, nx_time_us_t deadline)¶

struct nx_byte_stream_t¶

#include <byte_stream.h>

稳定只读接口；不查 factory、不分配或启动。

公共成员

const nx_byte_stream_ops_t *ops¶

void *context¶

lwip_adapter.h¶

显式单所有者 lwIP 以太网复制适配器。

作者 Nexus Team

类型定义

typedef struct nx_lwip_adapter nx_lwip_adapter_t¶: 后端存储仅由显式存储头文件定义。

函数

nx_result_t nx_lwip_adapter_start(nx_lwip_adapter_t *adapter, const nx_lwip_config_t *config)¶

连接调用者拥有的一个 netif，不初始化 MAC 或 PHY。

备注

仅限任务上下文，由单一串行协议栈执行所有者调用。地址配置为静态 IPv4；底层协议栈是锁定的 NO_SYS 配置。存储必须与配置、TX 字节和 RX 视图互不重叠。失败不保留新的硬件借用。链路初始为 down；只有显式外部 PHY 观测才可将其设为 up。

参数:

adapter – [inout] 零初始化且尚未处于有效状态的后端存储。
config – [in] 显式配置；复制内容，不保留其引用。

返回:

成功、输入无效，或 netif 已连接时的 BUSY。

nx_result_t nx_lwip_adapter_service(nx_lwip_adapter_t *adapter, size_t receive_budget)¶

推进 MAC、有界数量的完整 RX 帧以及协议栈定时器回调。

备注

与所有 lwIP raw API／回调共用同一任务 owner。定时器回调开销由固定协议栈配置和应用回调决定；这不构成整个调用的硬性时间上界。复制式配置在精确归还令牌前复制 RX 字节。显式借用式 RX 配置保留不可变载荷尾部，直到 custom-pbuf 引用结束。release 失败会保留令牌并关闭后续接收推进；stop 重试 release，不会将重复字节送入协议栈。inline 和延后结清的 TX 失败在请求复用前均保持可观察；尚未观察时，新 link output 返回 ERR_IF，不接纳字节。inline SUCCESS 仍可立即复用。消费已结清的失败会将 TX 请求置为 READY，不会自动复位、重放、关闭 adapter 或强制重启。产品决定 provider 恢复策略；实际尚未结束的借用绝不会被撤销。

参数:

adapter – [inout] 仍有效且包含所有未结束借用的存储。
receive_budget – [in] 此次调用最多取得的帧数，必须为正数。

返回:

成功、一个待观察的已结清 TX 失败，或 provider／release／状态错误。已结清的 TX 失败会在继续推进前消费一次。

nx_result_t nx_lwip_adapter_apply_link(nx_lwip_adapter_t *adapter, const nx_eth_link_t *link)¶

先将经过确认的外部 PHY 事实应用到 MAC，再应用到 netif。

备注

由单一任务所有者调用。既有 provider 静止规则仍适用。该操作不协商、不复位、不供电，也不证明物理链路。

参数:

adapter – [inout] 有效且尚未关闭准入的适配器存储。
link – [in] 实际 PHY 观测，不是软件默认值。

返回:

底层 MAC 准入结果；失败时保留 netif 标志。

nx_result_t nx_lwip_adapter_stop(nx_lwip_adapter_t *adapter)¶

关闭适配器准入，只有实际 MAC 排空后才脱离连接。

备注

产品必须先关闭其 PCB、原始回调、队列及观察者。该操作只停止 netif／MAC 适配器，不停止全局 lwIP 协议栈或全部应用连接。超时或排空失败从不撤销 TX／RX 借用；显式恢复 provider 后重试。不自动复位或重放。成功脱离连接后的 stop 是幂等操作。

参数:

adapter – [inout] 有效存储；撤回未完成时仍保留。

返回:

成功脱离连接后返回成功，否则返回实际撤回错误。

uint32_t nx_lwip_port_now_ms(void)¶

由产品提供的 lwIP 定时器单调毫秒时钟。

备注

仅由任务所有者调用。每个选定协议栈配置只提供一次此符号；时钟源及其生命周期必须覆盖全部待处理协议栈定时器。

返回:: 协议栈未改变且仍有效的时间域内，允许自然回绕的毫秒数。

uint32_t nx_lwip_port_random_u32(void)¶

由产品提供的随机字；没有 libc 或时间戳回退。

备注

由串行协议栈所有者调用。源失败必须进入产品的不返回故障路径；仅在显式未资格化的主机测试工装中允许返回固定值。

返回:: 来自产品已准入随机源的一个字。

void nx_lwip_port_assert(const char *message)¶

由产品提供的不返回协议栈不变量失败观测。

备注

由任务所有者调用。不能仅因为协议栈报告断言就返回或释放隔离中的硬件存储。不链接默认 abort。

参数:

message – [in] 静态诊断文本，不是保留的所有权 token。

struct nx_lwip_config_t¶

#include <lwip_adapter.h>

显式静态 IPv4 配置及调用者拥有的帧存储。

备注

串行协议栈所有者在连接之前仅初始化一次 lwIP。接口、时钟、TX 缓冲区和视图的生命周期必须覆盖连接及全部借用。时钟与 provider 截止时间使用同一有效单调域。不提供默认 worker、锁、PHY、地址、DHCP、DNS 或堆。

公共成员

const nx_eth_frames_port_t *port¶

nx_clock_t clock¶

nx_time_us_t tx_timeout_us¶

uint8_t *tx_buffer¶

size_t tx_capacity¶

nx_eth_fragment_t *rx_views¶

size_t rx_capacity¶

uint8_t hardware_address[6]¶

uint8_t address[4]¶

uint8_t netmask[4]¶

uint8_t gateway[4]¶

lwip_loaned_rx.h¶

lwIP 的显式不可变 RX 负载借用配置。

作者 Nexus Team

类型定义

typedef struct nx_lwip_rx_slot nx_lwip_rx_slot_t¶: 由其存储目标定义的精确选定后端槽。

typedef struct nx_lwip_rx_piece nx_lwip_rx_piece_t¶: 精确选定的 custom-pbuf 片段，不是数据包分配器。

函数

nx_result_t nx_lwip_loaned_adapter_start(nx_lwip_adapter_t *adapter, const nx_lwip_loaned_config_t *config)¶

挂接显式选定的负载零复制 RX 配置。

备注

仅限任务上下文，与所有 raw 调用使用同一个串行、不可重入的 NO_SYS owner。此镜像中只选择借用式配置及其存储目标。Ethernet／ARP／最大 IPv4／最大 TCP 头会被复制；不可变负载尾部被借用。这不是整帧或 TX 零复制。不新增 VLAN、IPv6、DHCP、DNS、重组、worker、堆或物理链路。MAC 负载区间必须与 adapter、TX／视图存储及所有选定槽／片段元数据互不重叠；接纳路径会释放无效借用。custom-pbuf 的最终释放只标记槽已就绪。后续 service 或 stop 执行精确 provider 释放。释放失败会保留令牌并关闭接纳。引用尚存时，stop 返回 BUSY。产品须在 adapter 撤离前关闭 PCB 和所有 raw 观察者。

参数:

adapter – [inout] 零初始化的选定后端存储。
config – [in] 互不重叠且稳定的存储描述；成功时复制。

返回:

成功、配置无效，或已有挂接的 owner。

struct nx_lwip_loaned_config_t¶

#include <lwip_loaned_rx.h>

调用方选定的 RX 借用和片段元数据，不含隐藏池。

备注

槽和片段须零初始化，并持续存活至最终 pbuf 释放、精确 MAC 释放和 adapter 解除挂接完成。至少提供 slot_count * base.rx_capacity 个片段。每个槽拥有一个复制的 136 字节可写头部前缀。其余数据包负载引用不可变 MAC 字节；raw 消费方不得写入这些 PBUF_ROM 尾部字节。实际 provider 的精确描述符布局仍限制并发借用数。

公共成员

nx_lwip_config_t base¶

nx_lwip_rx_slot_t *slots¶

size_t slot_count¶

nx_lwip_rx_piece_t *pieces¶

size_t piece_count¶

lwip_loaned_rx_storage.h¶

此选定配置的头文件仅用于静态装配。其字段描述保留中的帧与 pbuf 存储，不是可变的消费方接口。

精确选定的 RX 借用／custom-pbuf 装配存储。

作者 Nexus Team

struct nx_lwip_rx_piece¶

#include <lwip_loaned_rx_storage.h>

一个调用方拥有的 custom-pbuf 头及其唯一归属槽。

备注

私有后端字段；raw 用户只拥有普通 pbuf 引用。

公共成员

struct pbuf_custom custom¶

nx_lwip_rx_slot_t *slot¶

struct nx_lwip_rx_slot¶

#include <lwip_loaned_rx_storage.h>

由该帧所有保留片段共享的一个精确 RX 令牌。

备注

该联合体在维护中的配置下提供八字节对齐。释放回调只减少引用数；它从不访问硬件。只有 provider 接受精确释放后才可复用槽。raw 用户在归还 pbuf 的最后一个引用后不得再访问它。

公共成员

nx_eth_frames_rx_loan_t loan¶

nx_lwip_rx_piece_t header¶

uint64_t alignment¶

uint8_t bytes[136]¶

union nx_lwip_rx_slot prefix¶

size_t live_pieces¶

bool held¶

lwip_tcp.h¶

面向单个 NO_SYS 协议栈的有界复制 TCP 客户端。

类型定义

typedef struct nx_lwip_tcp nx_lwip_tcp_t¶

枚举

enum nx_lwip_tcp_state_t¶

取值：

enumerator NX_LWIP_TCP_IDLE¶

enumerator NX_LWIP_TCP_CONNECTING¶

enumerator NX_LWIP_TCP_ESTABLISHED¶

enumerator NX_LWIP_TCP_CLOSING¶

enumerator NX_LWIP_TCP_CLOSED¶

enumerator NX_LWIP_TCP_FAILED¶

函数

nx_result_t nx_lwip_tcp_start(nx_lwip_tcp_t *client, const nx_lwip_tcp_config_t *config, nx_time_us_t deadline)¶

使用复制的配置准入一次异步连接。

备注

调用者先初始化一次 lwIP。SUCCESS 从不表示已达 ESTABLISHED。拒绝时，本客户端不保留新的 PCB、pbuf 或配置引用。准入后的客户端必须显式 close 或 abort。

备注

PCB 共享官方协议栈的池及其回收策略。分配可能推进待完成的关闭，并回收 TIME_WAIT、LAST_ACK、CLOSING 或较低优先级的活动 PCB。即使本次 start 随后失败，也可能因此调用其他连接的错误回调。局部拒绝并不保证整个协议栈保持不变。

参数:

client – [inout] 精确布局的零初始化存储；所有先前使用者均已完成 join。
config – [in] 有效适配器、复制的 IPv4 对端，以及非零端口和预算。
deadline – [in] 首个有限的连接绝对截止时间。

返回:

SUCCESS 准入 CONNECTING。操作域已被占用时以 BUSY 拒绝。INVALID 拒绝配置；EXHAUSTED/IO 报告栈准入错误。

nx_result_t nx_lwip_tcp_service(nx_lwip_tcp_t *client)¶

执行一次受预算限制的网络推进，并推进本连接。

备注

不等待，也不创建工作线程。致命错误持续保留，直到显式 abort。截止时间到期不会释放 PCB、pbuf 或任何底层 MAC 借用。

参数:

client – [inout] 有效客户端，由串行任务执行器独占使用。

返回:

推进时返回 SUCCESS；连接中、拥塞或重入时返回 BUSY；已锁定截止时间到期时返回 TIMEOUT；也可能返回实际 provider／协议栈错误。

nx_result_t nx_lwip_tcp_try_write(nx_lwip_tcp_t *client, const uint8_t *data, size_t bytes, size_t *accepted, nx_time_us_t deadline)¶

将本次可立即接受的部分写入复制到有界栈存储。

备注

接受正数个字节表示准入 TCP 队列，不表示已交付对端。交付与确认策略由调用方负责。后续输出失败无法撤销已经复制的接受结果。计数对象发生非法别名时，在写入该计数前拒绝。

参数:

client – [inout] 有效客户端，由串行任务上下文独占使用，且调用发生在 raw 回调之外。
data – [in] 本次调用期间稳定的输入；返回后绝不保留。
bytes – [in] 请求长度；为零时无需读取时钟或推进 provider。
accepted – [out] 与其他存储不重叠的已复制字节计数；有效的 BUSY／错误返回时为零。
deadline – [in] 适配器时间域中的有限准入绝对截止时间。

返回:

复制正数个字节时返回 SUCCESS；未准入时返回 BUSY；准入前超时返回 TIMEOUT；关闭中返回 STATE；也可能返回持续保留的失败。

nx_result_t nx_lwip_tcp_try_read(nx_lwip_tcp_t *client, uint8_t *data, size_t bytes, size_t *received, nx_time_us_t deadline)¶

复制部分 RX 数据，并仅为实际消耗的字节归还接收额度。

备注

最多持有一个已接受的 pbuf 链。被拒绝的链仍由 lwIP 持有。先返回缓冲字节，再报告 FIN；对端半关闭后仍允许写入。TLS 独立认证 close-notify。计数对象发生非法别名时，在写入该计数前拒绝。

参数:

client – [inout] 由串行任务上下文独占使用；关闭过程中可通过读取排空数据。
data – [out] 返回后不保留的输出，与全部已知有效存储不重叠。
bytes – [in] 容量；为零时无需读取时钟或推进 provider。
received – [out] 与其他存储不重叠的计数；有效的 BUSY／错误或 EOF 返回时为零。
deadline – [in] 适配器时间域中本次尝试的有限绝对截止时间。

返回:

有数据时返回 SUCCESS；有序 TCP EOF 返回 SUCCESS 且计数为零；无数据时返回 BUSY；也可能返回 TIMEOUT、脱离后的 STATE 或持续保留的失败。

nx_result_t nx_lwip_tcp_close(nx_lwip_tcp_t *client, nx_time_us_t deadline)¶

关闭准入，并在显式局部排空后脱离。

备注

CONNECTING 可以在建立连接前关闭。调用 tcp_close 前先解除回调引用；调用成功后绝不能再访问其 PCB。固定版本的协议栈可在返回成功时延后分配 FIN。FIN/TIME_WAIT 属于仍在存续的协议栈／网络域。本操作不证明全局或 PHY 已排空。超时后必须显式 abort。

参数:

client – [inout] 生产者均已完成 join；可通过读取排空保留的 RX。
deadline – [in] 首个有限的关闭截止时间；绝不隐式延长。

返回:

SUCCESS 使本上下文脱离。BUSY 保留已持有或被拒绝的 RX、未确认的 TX 或失败的关闭状态。TIMEOUT 保留全部所有权责任。

nx_result_t nx_lwip_tcp_abort(nx_lwip_tcp_t *client)¶

显式丢弃数据、解除回调引用，并 abort 仍由本客户端持有的 PCB。

备注

BUSY 不释放任何资源。错误回调已释放其 PCB。全部客户端完成退出后，产品代码另行排空 MAC／netif。

参数:

client – [inout] 全部接口使用者完成 join 后的独占存储。

返回:

局部清理完成后返回 SUCCESS，包括冷态客户端；任何接口操作或回调执行期间返回 BUSY；client 为 NULL 时返回 INVALID。

const nx_byte_stream_t *nx_lwip_tcp_stream(const nx_lwip_tcp_t *client)¶

返回已有的只读字节接口，不推进执行。

备注

在同一串行任务域中进行只读查询。接口存在不表示连接就绪；其数据方法返回实际状态。

参数:

client – [in] 必须保持存储有效，直到每个接口使用者均结束访问。

返回:

初始化有效期间返回稳定接口，包括 CONNECTING/FAILED 状态；准入前或成功 close／abort 后返回 NULL。

nx_result_t nx_lwip_tcp_diagnostic(const nx_lwip_tcp_t *client, nx_lwip_tcp_diagnostic_t *diagnostic)¶

复制只读的所有者状态快照，不推进协议栈。

备注

使用串行执行器。快照既不准入 I/O，也不授权释放。脱离后的查询绝不追踪旧的借用状态。

参数:

client – [in] 有效或已局部脱离、但仍保持分配的存储。
diagnostic – [out] 与已知有效控制／数据存储不重叠的输出。

返回:

成功取得快照时返回 SUCCESS；输出为空或非法别名时返回 INVALID。

struct nx_lwip_tcp_config_t¶

#include <lwip_tcp.h>

复制的 IPv4 对端，以及显式网络推进预算。

备注

网络存储及其时钟纪元必须比每个客户端存续更久，也必须覆盖协议栈中脱离上下文后仍存在的 FIN/TIME_WAIT 状态。

备注

一个串行 NO_SYS 执行器拥有 raw API 和全部客户端。接口的数据／控制调用必须位于 raw 回调之外。跨接口实例的嵌套修改返回 BUSY，不递归推进。

备注

非零 I/O 最多服务 receive_budget 个以太网帧。不新增工作线程、DNS、重连策略或实例注册表。

公共成员

nx_lwip_adapter_t *network¶

size_t receive_budget¶

uint8_t address[4]¶

uint16_t port¶

struct nx_lwip_tcp_diagnostic_t¶

#include <lwip_tcp.h>

所有者状态快照；不授予修改连接的权限。

公共成员

nx_lwip_tcp_state_t state¶

nx_result_t result¶

int stack_error¶

size_t pending_receive¶

size_t pending_transmit¶

bool peer_fin¶

lwip_tcp_storage.h¶

该精确配置头文件仅用于静态装配。其字段不扩展通用客户端接口。

固定版本的精确 TCP 客户端存储；仅供装配使用。

struct nx_lwip_tcp¶

#include <lwip_tcp_storage.h>

公共成员

nx_lwip_tcp_config_t config¶

nx_byte_stream_t stream¶

struct tcp_pcb *pcb¶

struct pbuf *receive¶

nx_time_us_t connect_deadline¶

nx_time_us_t close_deadline¶

nx_lwip_tcp_diagnostic_t diagnostic¶

uint16_t receive_offset¶

bool initialized¶

bool active¶

bool callback_active¶

tls.h¶

显式有界 TLS 1.2 客户端与密码域生命周期。

作者 Nexus Team

宏定义

NX_TLS_ARENA_BYTES¶

NX_TLS_TX_STAGE_BYTES¶

NX_TLS_DER_MAX¶

类型定义

typedef struct nx_tls_runtime nx_tls_runtime_t¶

typedef struct nx_tls_session nx_tls_session_t¶

枚举

enum nx_tls_entropy_quality_t¶

源质量声明，绝不从健康检查推断。

取值：

enumerator NX_TLS_ENTROPY_UNKNOWN¶

enumerator NX_TLS_ENTROPY_FULL_SOURCE¶

enum nx_tls_state_t¶

取值：

enumerator NX_TLS_IDLE¶

enumerator NX_TLS_INITIALIZED¶

enumerator NX_TLS_HANDSHAKING¶

enumerator NX_TLS_ESTABLISHED¶

enumerator NX_TLS_CLOSING¶

enumerator NX_TLS_CLOSED¶

enumerator NX_TLS_FAILED¶

函数

nx_result_t nx_tls_runtime_start(nx_tls_runtime_t *runtime, const nx_tls_runtime_config_t *config, nx_time_us_t deadline)¶

初始化一个显式 PSA/arena 域，而非每次连接都初始化。

备注

无工作线程、堆或锁。第二个有效域返回 BUSY。每次库熵回调均受操作截止时间与熵截止时间中较早者约束。

参数:

runtime – [inout] 已清零的静态后端存储。
config – [in] 复制配置；被引用资源继续借用。
deadline – [in] 有限绝对初始化截止时间。

返回:

成功；未声明质量时返回权限错误；或实际有界操作错误。

nx_result_t nx_tls_runtime_stop(nx_tls_runtime_t *runtime)¶

仅在全部会话和外部使用方退出后停止 PSA。

备注

会话清理不会隐式调用此操作。产品代码不得在此显式域外使用 PSA 或重置其全局分配器。

参数:

runtime – [inout] 有效域的独占所有者。

返回:

仍有会话时返回 BUSY；成功时先释放 PSA，再擦除整个 arena。

nx_result_t nx_tls_initialize(nx_tls_session_t *session, const nx_tls_config_t *config, nx_time_us_t deadline)¶

使用公共 Mbed TLS API 和强制对端认证准备一个客户端。

备注

返回后不保留原始凭据输入。端口和暂存区继续借用到 abort；失败时清理部分后端状态。

参数:

session – [inout] 已清零的静态后端存储。
config – [in] 显式信任、主机名和可选客户端身份/端口。
deadline – [in] 包括密钥导入的有限初始化截止时间。

返回:

成功；域已占用时为 BUSY；或未准入的失败。

nx_result_t nx_tls_handshake_step(nx_tls_session_t *session, nx_time_us_t deadline)¶

在首次锁定的截止时间内执行一次公共握手步骤。

备注

首个步骤通过公共 API 在有限约束下重新播种 PSA。对可信 UTC 取一致快照；库日期检查期间失去可信时间会被锁存，并覆盖库的成功结果。禁用重新协商。

参数:

session – [inout] 已初始化的独占客户端。
deadline – [in] 有限截止时间；后续调用不能延长首次截止时间。

返回:

仅认证验证成功后返回成功；推进/WANT 时返回 BUSY；或致命错误。

nx_result_t nx_tls_service(nx_tls_session_t *session)¶

推进唯一已接受的明文暂存块，不等待。

备注

WANT 重试保留后端原始指针和长度。排队写入过期会使会话失败；仅 abort 释放其暂存区。

参数:

session – [inout] 有效的串行化所有者。

返回:

无待发字节时成功；WANT 时 BUSY；或锁存的致命错误。

nx_result_t nx_tls_try_write(nx_tls_session_t *session, const uint8_t *data, size_t bytes, size_t *accepted, nx_time_us_t deadline)¶

将即时部分写入复制到显式有界暂存区。

备注

原始输入可立即复用。待发暂存区不会被覆盖、重放或在超时后丢弃。后续失败会锁存。无效别名计数在写该计数之前被拒绝。

参数:

session – [inout] 已建立连接的串行化客户端。
data – [in] 只读输入，返回后不保留。
bytes – [in] 请求字节数；零不执行 I/O。
accepted – [out] 互不重叠的复制计数；BUSY/错误时为零。
deadline – [in] 为已接受字节保留的有限绝对截止时间。

返回:

成功表示复制准入，不表示对端收到；或 BUSY/错误。

nx_result_t nx_tls_try_read(nx_tls_session_t *session, uint8_t *data, size_t bytes, size_t *received, nx_time_us_t deadline)¶

尝试复制已认证明文，不保留调用方输出。

备注

未收到 close-notify 的底层传输 EOF 是锁存的截断错误。准入前已过期时保留会话状态，不建立新借用。无效别名计数在写该计数之前被拒绝。待发暂存区的有效截止时间较晚时返回 BUSY，不自动执行 I/O；所有者显式推进先前已接受的写入。

参数:

session – [inout] 已建立连接的串行化客户端。
data – [out] 不保留的输出，与全部有效会话存储互不重叠。
bytes – [in] 可写容量；零不执行 I/O。
received – [out] 互不重叠的计数；BUSY/错误或认证 EOF 时为零。
deadline – [in] 本次非阻塞尝试的有限绝对截止时间。

返回:

成功/字节数、BUSY、已认证 close-notify EOF 或错误。

nx_result_t nx_tls_close_step(nx_tls_session_t *session, nx_time_us_t deadline)¶

使用首次显式锁定的截止时间发送 close-notify。

备注

必须先排空待发应用字节。此操作不关闭下层传输，也不证明对端已消费数据。仍需 abort 释放存储。

参数:

session – [inout] 生产者全部退出后的独占有效客户端。
deadline – [in] 有限绝对截止时间；不隐式延长。

返回:

成功表示本地警报已接受；WANT 时为 BUSY；或锁存错误。

nx_result_t nx_tls_abort(nx_tls_session_t *session)¶

最终访问结束后释放同步会话状态并擦除其暂存区。

备注

BUSY 保留全部存储；外层所有者在回调退出后重试。不执行网络 I/O 或重放。下层传输关闭仍由外部负责。锁定的内置同步密码配置不在返回后保留回调。PSA 域/arena 保持有效，供下一个显式会话使用。

参数:

session – [inout] 独占所有者，全部外部接口使用方已退出。

返回:

清理完成后成功（冷态也成功）；密码/BIO 正在执行时为 BUSY。

const nx_byte_stream_t *nx_tls_stream(const nx_tls_session_t *session)¶: 返回已有、不建立借用的字节接口；不启动或分配。

nx_result_t nx_tls_diagnostic(const nx_tls_session_t *session, nx_tls_diagnostic_t *diagnostic)¶: 将当前所有者诊断复制到不保留、互不重叠的输出。

struct nx_tls_utc_t¶

#include <tls.h>

显式可信 UTC，与单调操作截止时间分离。

备注

SUCCESS 表示可信 Unix 秒数。未知、不可信或不可用时间返回错误。日历年份必须处于所选 time_t 表示范围内的 1970..9999。产品负责认证和时钟策略。

公共成员

nx_result_t (*read)(void *context, int64_t *seconds)¶

void *context¶

struct nx_tls_runtime_config_t¶

#include <tls.h>

一个串行化密码所有者、调用方 arena 与有限熵源。

备注

arena 按 max_align_t 对齐，大小恰为 NX_TLS_ARENA_BYTES。全部接口和不透明上下文必须存活至每个会话结束。FULL_SOURCE 向选定的 PSA 熵驱动 API 显式声明 8 bits/byte；软件健康检查和此枚举不能建立物理资格。配置禁用操作系统熵与种子回退。时钟必须在回调期间持续推进并保持单一时间域。

公共成员

void *arena¶

size_t arena_bytes¶

const nx_entropy_port_t *entropy¶

nx_clock_t clock¶

nx_tls_utc_t utc¶

nx_time_us_t entropy_timeout_us¶

nx_tls_entropy_quality_t entropy_quality¶

struct nx_tls_config_t¶

#include <tls.h>

初始化期间由后端复制的客户端凭据。

备注

仅 DER；不隐式加载文件、发现密钥或提供默认信任。hostname 包含 hostname_length 个非 NUL 字节，后接 NUL，长度为 1..253。双向认证证书和密钥必须同时提供或同时缺省。TX 暂存区恰为调用方的 512 字节，与运行时、会话、arena 和传输状态互不重叠。它继续借用到 abort。单一串行化执行器负责全部会话和 PSA 调用。

公共成员

nx_tls_runtime_t *runtime¶

const nx_byte_stream_t *transport¶

const uint8_t *trust_der¶

size_t trust_bytes¶

const uint8_t *client_der¶

size_t client_bytes¶

const uint8_t *key_der¶

size_t key_bytes¶

const char *hostname¶

size_t hostname_length¶

uint8_t *tx_stage¶

size_t tx_stage_bytes¶

struct nx_tls_diagnostic_t¶

#include <tls.h>

只读诊断；快照不授予操作许可。

公共成员

nx_tls_state_t state¶

nx_result_t result¶

int library_error¶

uint32_t verify_flags¶

size_t pending_plaintext¶

bool want_read¶

bool want_write¶

bool peer_closed¶

client.h¶

基于显式流的有界同步 MQTT 3.1.1 客户端。

作者 Nexus Team

类型定义

typedef struct nx_mqtt_session nx_mqtt_t¶

typedef struct nx_mqtt_memory nx_mqtt_memory_t¶

枚举

enum nx_mqtt_event_kind_t¶

取值：

enumerator NX_MQTT_EVENT_PUBLISH¶

enumerator NX_MQTT_EVENT_PUBACK¶

enumerator NX_MQTT_EVENT_SUBACK¶

enumerator NX_MQTT_EVENT_UNSUBACK¶

函数

nx_time_us_t nx_mqtt_port_now_us(void)¶

全部客户端及其传输层共用的产品时钟。

备注

必需的无上下文钩子与上游计时器 API 一致。绝不得静默更换纪元或时间域。UINT64_MAX 无效。此适配器不使用活动实例全局注册表。

返回:: 同一稳定启动纪元/时间域内的绝对单调微秒数

void nx_mqtt_port_assert(const char *file, unsigned line)¶

不返回的产品不变量失败钩子。

备注

不得因断言而回收 DMA 或传输存储。

参数:

file – [in] 静态源码位置
line – [in] 源码行号

nx_result_t nx_mqtt_init(nx_mqtt_t *client, const nx_mqtt_config_t *config, const nx_mqtt_memory_t *memory)¶

初始化调用方的准确存储，不打开传输。

备注

仅限任务上下文，无 I/O 或堆。全部存储与端口上下文必须保持有效、独占，直到 deinit 成功。

参数:

client – [inout] 已清零或已 deinit 的元数据
config – [in] 有效稳定端口；复制数值，借用上下文
memory – [inout] 互不重叠的网络、QoS 与控制存储

返回:

SUCCESS、INVALID、STATE、OVERFLOW 或 EXHAUSTED

nx_result_t nx_mqtt_connect(nx_mqtt_t *client, const nx_mqtt_connect_t *connect, nx_mqtt_call_t call)¶

同步发送 clean-session CONNECT 并等待 CONNACK。

备注

不连接 TCP/TLS。产品提供传输与认证策略。失败 CONNECT 不会被重放。

参数:

client – [inout] 使用全新已打开流、已初始化但未活动的客户端
connect – [in] 合法 MQTT UTF-8 字段，仅本次调用借用
call – [in] 有限绝对截止时间及非零 I/O 预算

返回:

SUCCESS、准入错误或锁存的会话/传输失败

nx_result_t nx_mqtt_publish(nx_mqtt_t *client, const nx_mqtt_publish_t *publish, uint16_t *packet_id, nx_mqtt_call_t call)¶

使用调用期主题与负载借用发布 QoS0/1。

备注

QoS1 记录继续借用到 deinit。PUBACK 表示确认；应用负责消息重试和数据保留。不提供持久会话重放或 QoS2。

参数:

client – [inout] 已连接的串行化客户端
publish – [in] 合法 UTF-8 主题与字节负载；不得别名重叠
packet_id – [out] 仅成功时写入；QoS0 为零
call – [in] 有限截止时间及非零 I/O 预算

返回:

本地流准入返回 SUCCESS，绝不代表 broker 已收到

nx_result_t nx_mqtt_subscribe(nx_mqtt_t *client, const char *topic, size_t topic_size, uint8_t qos, uint16_t *packet_id, nx_mqtt_call_t call)¶

发送一个有界订阅请求。

参数:

client – [inout] 已连接且有空闲调用方控制槽的客户端
topic – [in] 调用期合法 MQTT UTF-8 过滤器
topic_size – [in] 非零字节数，至多 UINT16_MAX
qos – [in] 请求的最大 QoS 为零或一
packet_id – [out] 仅发送成功时写入
call – [in] 显式截止时间与 I/O 预算

返回:

SUCCESS 表示已发送；SUBACK 事件报告授权或拒绝

nx_result_t nx_mqtt_unsubscribe(nx_mqtt_t *client, const char *topic, size_t topic_size, uint16_t *packet_id, nx_mqtt_call_t call)¶

发送一个有界取消订阅请求。

参数:

client – [inout] 已连接且有空闲调用方控制槽的客户端
topic – [in] 调用期合法 MQTT UTF-8 过滤器
topic_size – [in] 非零字节数，至多 UINT16_MAX
packet_id – [out] 仅发送成功时写入
call – [in] 显式截止时间与 I/O 预算

返回:

SUCCESS 表示已发送；在 process 期间观察 UNSUBACK

nx_result_t nx_mqtt_process(nx_mqtt_t *client, nx_mqtt_call_t call)¶

调用方推进的接收、确认与保活步骤。

备注

回调视图在返回时失效；需要的数据须在回调内复制。无隐式计时器/任务注册或自动重放。

参数:

client – [inout] 已连接的串行化客户端
call – [in] 显式截止时间与 I/O 预算

返回:

SUCCESS、数据不完整时的 BUSY 或锁存失败

nx_result_t nx_mqtt_disconnect(nx_mqtt_t *client, nx_mqtt_call_t call)¶

发送 MQTT DISCONNECT，不关闭传输。

参数:

client – [inout] 已连接的串行化客户端
call – [in] 显式截止时间与 I/O 预算

返回:

SUCCESS 表示本地准入，不表示 TCP/TLS 已排空

nx_result_t nx_mqtt_deinit(nx_mqtt_t *client)¶

全部同步调用返回后结束本地借用。

备注

无 I/O。产品在下一 MQTT 会话之前另行排空/关闭 TCP/TLS；deinit 不能撤回已接受的字节。

参数:

client – [inout] 未活动的已初始化客户端，包括失败客户端

返回:

SUCCESS、重入时的 BUSY 或 INVALID

nx_result_t nx_mqtt_fault(const nx_mqtt_t *client)¶

在同一串行任务上下文检查锁存失败。

参数:

client – [in] 已初始化实例

返回:

首次失败、SUCCESS 或未活动实例的 STATE

struct nx_mqtt_event_t¶

#include <client.h>

回调期事实；全部指针随回调返回失效。

公共成员

nx_mqtt_event_kind_t kind¶

uint16_t packet_id¶

uint8_t qos¶

bool retain¶

bool duplicate¶

nx_result_t status¶

const char *topic¶

size_t topic_size¶

const uint8_t *payload¶

size_t payload_size¶

struct nx_mqtt_call_t¶

#include <client.h>

显式有限操作截止时间及传输调用预算。

公共成员

nx_time_us_t deadline¶

uint32_t io_budget¶

struct nx_mqtt_config_t¶

#include <client.h>

借用至 deinit 的调用方端口。

备注

全部调用和回调使用单一串行任务上下文。事件回调与可选 idle 回调必须有界，不得重入此客户端。idle 可在下层推进或等待；不创建工作线程、锁、调度器或隐式重连。idle 返回 SUCCESS/BUSY 允许重试；其他结果使会话失败。事件视图不是 NUL 结尾字符串。

公共成员

nx_byte_stream_t stream¶

void (*event)(void *context, const nx_mqtt_event_t *event)¶

void *event_context¶

nx_result_t (*idle)(void *context, nx_time_us_t deadline)¶

void *idle_context¶

struct nx_mqtt_connect_t¶

#include <client.h>

临时 CONNECT 参数；此配置始终使用 clean session。

公共成员

const char *client_id¶

size_t client_id_size¶

const char *username¶

size_t username_size¶

const uint8_t *password¶

size_t password_size¶

uint16_t keepalive_seconds¶

struct nx_mqtt_publish_t¶

#include <client.h>

临时发布；QoS1 确认由后续 PUBACK 事件报告。

公共成员

const char *topic¶

size_t topic_size¶

const uint8_t *payload¶

size_t payload_size¶

uint8_t qos¶

bool retain¶

TMP117 单次采样合同¶

在固件目标的 LIBRARIES 中选择 Nexus::TMP117 器件协议与 Nexus::TMP117I2C 已结清 I2C 适配器。这些可选 CMake 目标不新增生成式器件类别或另一套配置入口。产品提供已配置的固定地址端点、单调时钟、非零时钟域与 epoch，以及预期的现有数字偏移。ADD0 接线、电源、总线调度和物理恢复由外部负责。I/O 所有权架构继续适用；不引入传感器工作线程、堆、地址扫描或额外的 owner 框架。

已审查器件限定为完整标识 0x0117 的 TI TMP117，采用单次模式、一次转换并禁用平均。初始化检查标识、EEPROM 就绪和锁定状态，核对现有偏移，再请求并读回 shutdown 状态，保留无关配置位。一旦发出 shutdown 写入，写入或核验失败即保留相同端口、配置及时钟，将实例标记为未初始化且状态不确定；清理使用独立 deadline。更早的失败不会取得新绑定。begin 先清除过期就绪状态再请求一次转换；poll 读取就绪状态后再读取温度。每次寄存器读取先写指针，再以重复 START 读取两个高字节在前的字节。仅接受同步端点事务：每次返回，包括错误，均结束对描述符和 TX/RX 存储区的使用。不能用仅支持异步的端点替代这一已结清合同。

仅 SUCCESS 发布包含独立数值的样本。BUSY 和错误均保持整个输出不变。有符号原始值与现有偏移均以 1/128 摄氏度为一个 LSB。micro_celsius 舍入至最近的微摄氏度，恰好位于中点时远离零；完整有符号格式的换算不会超出 int32_t。已审查输出范围为芯片应用现有偏移之后的 -55 至 150 摄氏度。POR、饱和及超出该范围的值返回 IO。芯片已经应用偏移：驱动仅核对并报告，不会重复相加、编程校准或修改 EEPROM。

observed 复用 nx_io_timestamp_t，采用微秒速率、显式时钟域与 epoch、SERVICE_OBSERVATION 来源，以及未知的物理不确定度。它表示成功读取寄存器的完成时间。转换发生于 conversion_started_at 与 observed.ticks 之间；两者均非硬件转换时间戳。需要保守限制最大样本年龄时，先校验时钟域、epoch 和速率，再将当前时间与转换开始下界比较。最近读取寄存器本身不能证明数据新鲜。样本副本在器件 stop 后仍有效，不保留器件、传输或样本缓冲区引用；消费者仍须遵守时钟连续性假设。

所有调用由一个串行任务执行器执行，并使用有限绝对 deadline。Poll 在交换前后检查转换 deadline。成功读取到未就绪状态时返回 BUSY 并保留转换元数据。任何传输错误，包括传输 BUSY，都会结束采样并要求显式重新同步；读取 CONFIG 会清除就绪标志，因此随后温度读取失败时，不能将其重试为缓存零值或无限未就绪转换。一次样本成功后再次 poll 返回 STATE。已知控制与输出存储区重叠会被拒绝；由于通用驱动无法推断不透明上下文及借用总线存储的范围，调用者必须保证这些存储不重叠。

cancel 使用独立的有限清理 deadline，只有读回 shutdown 状态后才成功。它不能抢占正在执行的同步交换。清理失败保留绑定及外部物理恢复责任；timeout 或错误从不证明物理停止。应重试取消或执行外部恢复，然后显式重新初始化已经关闭的实例。仅在调用和外层 owner 用户均已 join 后，stop 才可解除软件绑定。Stop 不执行 I/O，不关闭器件电源，不释放 Board 资源，也不消除尚未解决的物理恢复责任。Owner 不能把同步栈事务排到自身执行器之后。

协议遵循 TI SNOSD82D，2018 年 6 月发布、2022 年 9 月修订，第 6.5 和 7.3–7.6 节（官方数据手册）。AVG=00 时单次转换最小、典型、最大耗时分别为 13/15.5/17.5 ms；调用者还需计入总线和调度余量。上电就绪需要 1.5 ms，通过总线及 EEPROM 状态报告，不使用隐藏 sleep。审查参考的 Zephyr 实现为提交 413b789deb391d3a37d06b463288a5fe765ee57e 的 drivers/sensor/ti/tmp11x；未复制驱动源码。

软件模型测试覆盖有符号换算、舍入、现有偏移、就绪状态、失败切点、deadline、取消、独立实例及已结清通用 owner 组合。ARM 链接探针采用维护中的 F407 与 GD470 空装配，并显式使用未接线的软件端点；仅证明 C11 链接和资源成本。器件精度、PCB 接线、I2C 波形、上电行为、真实转换延迟及取消仍需物理 HIL，目前尚未执行。工位必须记录精确器件标识、ADD0 地址、供电与上电时序、上拉、总线频率、已知温度参考、偏移、时钟身份、失败注入及已 join 的停机结果。

tmp117.h¶

显式已结清 TMP117 单次采样与来源信息。

作者 Nexus Team

函数

nx_result_t nx_tmp117_init(nx_tmp117_t *device, nx_tmp117_transport_port_t transport, const nx_tmp117_config_t *config, nx_time_us_t deadline)¶

校验标识 0117h、EEPROM 锁定、偏移及 shutdown 状态。

备注

不扫描、复位、sleep、写 EEPROM、创建工作线程或执行 Board 动作。使用独立清理 deadline 执行 cancel，或在相同绑定上重试 init。更换绑定需要先 join 并执行软件 stop；外部不确定状态的恢复仍由 owner 负责。写入失败不等同于器件复位。

参数:

device – [inout] 首次清零、已 stop 或同绑定下状态不确定的存储
transport – [in] 成功时或已调用 shutdown 写入后状态不确定时复制并保留
config – [in] 稳定的显式事实，不得与 device 重叠
deadline – [in] 所有访问共享的有限绝对 deadline

返回:

SUCCESS、上电或 EEPROM 导致的 BUSY，或原始传输错误；不支持的标识、偏移不符及未锁定 EEPROM 均不执行写入即拒绝。调用 shutdown 写入之前失败不保留新绑定。一旦发出 shutdown 写入，失败将保留相同端口、配置及时钟，实例保持未初始化且状态不确定。

nx_result_t nx_tmp117_begin(nx_tmp117_t *device, nx_time_us_t deadline)¶

禁用平均并开始一次新的转换。

备注

接纳 OS 请求前清除过期就绪状态。BUSY 仅保留转换元数据，从不保留栈或调用者缓冲区。I/O 后失败将关闭采样，直至显式重新同步。

参数:

device – [inout] 已初始化、未测量的独占器件
deadline – [in] 同一时钟中的有限转换与读取 deadline

返回:

SUCCESS、INVALID、BUSY、STATE、TIMEOUT 或传输错误

nx_result_t nx_tmp117_poll(nx_tmp117_t *device, nx_tmp117_sample_t *sample)¶

观察就绪状态并发布一个完整的新样本。

备注

读取 CONFIG 会清除就绪标志。随后温度读取失败为终止性失败，必须重新同步，不能变为缓存零值或无限就绪重试。任何传输错误，包括 BUSY，均关闭采样直至重新同步；仅成功读取到未就绪状态才保留转换。成功后再次 poll 返回 STATE。输出不得与 device、不透明端口或时钟上下文存储、借用总线存储重叠；只能检查已知范围。POR、饱和及超出已审查范围的值返回 IO。

参数:

device – [inout] 已开始转换的器件，保持同一任务执行器
sample – [out] 对齐且独立的输出；每个错误路径均保持不变

返回:

SUCCESS、INVALID、未就绪时的 BUSY、STATE 或传输/IO 错误

nx_result_t nx_tmp117_cancel(nx_tmp117_t *device, nx_time_us_t deadline)¶

使用独立清理预算请求并核验 shutdown 状态。

备注

不能抢占同步交换。取消失败从不证明物理停止；端口返回后不存在 MCU 存储借用。成功也不会关闭 bus owner 或 join 其观察者。

参数:

device – [inout] 活跃或状态不确定的同一绑定，由串行 owner 使用
deadline – [in] 独立的有限清理 deadline，不复用已过期采样 deadline

返回:

仅观察到 shutdown 后返回 SUCCESS；其他结果保留恢复责任，可能需要重新 init 同步

void nx_tmp117_stop(nx_tmp117_t *device)¶

调用及外层 owner 均 join 后解除软件绑定。

备注

不执行物理 I/O，不等同于断电、核验取消、Board 释放，也不消除外部不确定状态责任。需要物理 shutdown 时，调用者应先完成 cancel 或外部恢复。回调期间调用不执行任何动作。

参数:

device – [inout] 不存在进行中调用的静止实例

struct nx_tmp117_transport_port_t¶

#include <tmp117.h>

每次返回均已结清的同步寄存器交换。

备注

读取先写一个寄存器字节，再通过重复 START 读取两个字节；写入发送寄存器及两个高字节在前的字节。串行任务 owner 在使用、不确定状态清理及已 join 的软件 stop 期间保持 context 和 clock 有效。每种结果均释放 TX/RX 存储区，包括 TIMEOUT/CANCELLED。不允许异步 submit 或保留栈存储区。

公共成员

void *context¶

nx_result_t (*exchange)(void *context, const uint8_t *tx, size_t tx_bytes, uint8_t *rx, size_t rx_bytes, nx_time_us_t deadline)¶

nx_clock_t clock¶

struct nx_tmp117_config_t¶

#include <tmp117.h>

显式时钟身份与预期现有校准。

备注

非零 domain/epoch 遵循 nx_io_timestamp_t。发生不连续、复位或速率变更时，owner 必须变更 epoch。芯片已经应用偏移；本驱动只核对并报告，从不编程校准或 EEPROM。

公共成员

uint32_t clock_domain¶

uint32_t clock_epoch¶

int16_t expected_offset_lsb¶

struct nx_tmp117_sample_t¶

#include <tmp117.h>

仅 SUCCESS 发布的独立样本副本。

备注

micro_celsius 将 raw/128 摄氏度舍入至最近微摄氏度，中点远离零。raw/offset 每 LSB 为 1/128 摄氏度，不会再次叠加 offset。已审查输出范围为 -55..150C。observed 为软件寄存器读取完成时间，物理不确定度未知，绝非硬件转换时间。转换发生于相同 domain/epoch 的 [conversion_started_at, observed.ticks] 之间。消费者可使用下界执行保守的逻辑年龄检查；最近读取完成本身不能确立新鲜度。所有字段均为值，不保留器件或 payload 引用。副本在 stop 后仍有效；时钟域假设仍依赖调用者的连续性和生命周期合同。

公共成员

int32_t micro_celsius¶

int16_t raw_lsb¶

int16_t offset_lsb¶

nx_time_us_t conversion_started_at¶

nx_io_timestamp_t observed¶

struct nx_tmp117_t¶

#include <tmp117.h>

调用者拥有精确实例，首次 init 前须清零。

备注

仅限任务中单一执行器，不允许并发或重入调用。不确定物理状态保留端口以供显式 cancel/resync，不产生 MCU 缓冲区借用。字段均为内部状态，不能作为回收借用存储的许可。

公共成员

nx_tmp117_transport_port_t transport¶

nx_tmp117_config_t config¶

nx_time_us_t deadline¶

nx_time_us_t conversion_started_at¶

nx_time_us_t last_clock¶

uint16_t base_configuration¶

bool initialized¶

bool measuring¶

bool uncertain¶

bool in_call¶

tmp117_i2c.h¶

基于显式已结清 I2C 端点的 TMP117 传输。

作者 Nexus Team

函数

nx_tmp117_transport_port_t nx_tmp117_i2c_transport(const nx_i2c_endpoint_t *endpoint, nx_clock_t clock)¶

绑定现有轮询端点，不执行 I/O 或设备发现。

备注

实际 ADD0 接线及地址 48h..4Bh 由外部负责。拒绝仅支持异步的端点；没有借用栈描述符的 submit 后备路径。仅一个串行总线执行器执行交换，不嵌套 owner 队列。

参数:

endpoint – [in] 显式固定地址接口，保持有效直至 stop/join
clock – [in] 与端点事务 deadline 相同的活跃时钟域

返回:

已结清传输；方法无效时返回无效零端口

bmp280.h¶

BMP280 校准与显式强制转换驱动。

作者 Nexus Team

函数

nx_result_t nx_bmp280_parse_calibration(const uint8_t *bytes, size_t length, nx_bmp280_calibration_t *calibration)¶

解析准确的 24 字节小端校准块。

参数:

bytes – [in] 从 0x88 开始的寄存器块
length – [in] 必须恰为 24
calibration – [out] 仅成功时写入

返回:

SUCCESS；长度错误或压力除数为零时为 INVALID

nx_result_t nx_bmp280_compensate(const nx_bmp280_calibration_t *calibration, uint32_t raw_temperature, uint32_t raw_pressure, nx_bmp280_sample_t *sample)¶

使用经过检查的整数运算补偿一个原始样本。

参数:

calibration – [in] 已解析的校准数据
raw_temperature – [in] 无符号 20 位 ADC 值
raw_pressure – [in] 无符号 20 位 ADC 值
sample – [out] 仅成功时写入

返回:

SUCCESS；校准格式错误或溢出时为 INVALID；ADC 禁用哨兵值或物理输出超出数据手册范围时为 IO

nx_result_t nx_bmp280_init(nx_bmp280_t *device, nx_bmp280_transport_port_t transport, nx_time_us_t deadline)¶

验证芯片 ID 并加载校准，不扫描设备。

备注

任务上下文；失败时 initialized 保持 false，且无借用。不软复位器件，也不创建等待循环或任务。BUSY 必须由调用者显式重试。

参数:

device – [out] 零初始化且尚未使用的实例
transport – [in] 调用返回前已结清的同步接口，以及有效的单调时钟
deadline – [in] 覆盖全部初始化访问的绝对截止时间

返回:

SUCCESS；NVM 更新期间为 BUSY；也可能返回传输或身份错误

nx_result_t nx_bmp280_begin(nx_bmp280_t *device, nx_time_us_t deadline)¶

启动一次强制温度／压力转换。

备注

仅限任务上下文的串行驱动所有者；过采样为 x1/x1。

参数:

device – [inout] 已初始化且未在测量的实例
deadline – [in] 覆盖转换与读取的绝对截止时间

返回:

SUCCESS、BUSY、TIMEOUT 或传输错误

nx_result_t nx_bmp280_poll(nx_bmp280_t *device, nx_bmp280_sample_t *sample)¶

轮询转换，不使用隐式执行任务或阻塞延迟。

备注

仅限任务上下文。每次接口调用在返回前释放临时缓冲。BUSY 保留器件转换状态，不保留栈或调用者缓冲。终止失败后可再次 begin；策略由外部所有者选择。

参数:

device – [inout] 已启动过转换的实例
sample – [out] 仅在 SUCCESS 时写入

返回:

SUCCESS；转换期间为 BUSY；也可能返回 TIMEOUT 或传输错误

void nx_bmp280_stop(nx_bmp280_t *device)¶

全部同步调用退出后停止软件使用。

备注

不为物理器件断电或复位。传感器内部转换可在不访问 MCU 存储的情况下完成。不再存在 MCU 借用。

参数:

device – [inout] 已静默的驱动实例

struct nx_bmp280_transport_port_t¶

#include <bmp280.h>

同步、已结清的 SPI 事务端口。

备注

exchange 始终在返回前释放全部 TX/RX 缓冲，包括 TIMEOUT 或错误路径。一个 CS 区间覆盖全部字节；采用模式 0 或 3、8 位字、频率不超过 10 MHz。调用者串行使用该器件及其总线所有者。驱动的栈上事务不会跨越异步借用边界。

公共成员

void *context¶

nx_result_t (*exchange)(void*, const uint8_t*, uint8_t*, size_t, nx_time_us_t deadline)¶

nx_clock_t clock¶

struct nx_bmp280_calibration_t¶

#include <bmp280.h>

由一个设备实例拥有的寄存器校准数据。

公共成员

uint16_t t1¶

int16_t t2¶

int16_t t3¶

uint16_t p1¶

int16_t p2¶

int16_t p3¶

int16_t p4¶

int16_t p5¶

int16_t p6¶

int16_t p7¶

int16_t p8¶

int16_t p9¶

struct nx_bmp280_sample_t¶

#include <bmp280.h>

仅成功转换／补偿时输出有效。

公共成员

int32_t centi_celsius¶

uint32_t pressure_pa¶

struct nx_bmp280_t¶

#include <bmp280.h>

显式设备上下文，不含 Board 引脚或自动采样任务。

公共成员

nx_bmp280_transport_port_t transport¶

nx_bmp280_calibration_t calibration¶

nx_time_us_t deadline¶

nx_time_us_t earliest_ready¶

bool initialized¶

bool measuring¶

bmp280_spi.h¶

固定 SPI 端点上的可选 BMP280 适配器。

作者 Nexus Team

函数

nx_bmp280_transport_port_t nx_bmp280_spi_transport(const nx_spi_endpoint_t *endpoint, nx_clock_t clock)¶

绑定真实轮询 SPI 端点作为能结清的传输端口。

参数:

endpoint – [in] 在器件使用期间始终保持有效的固定端点
clock – [in] 与 I/O 传输截止时间相同的单调时钟域

返回:

窄传输接口；不进行全局发现或 CS 选择

bus_owner.h¶

显式、有界的多生产者、单执行者适配器。

作者 Nexus Team

函数

nx_result_t nx_bus_owner_init(nx_bus_owner_t *owner, nx_owner_slot_t *slots, size_t capacity, nx_owner_guard_port_t guard, nx_owner_executor_port_t executor, nx_clock_t clock, const nx_wait_port_t *wake)¶

初始化尚未使用的 owner／slot 存储。

备注

启动上下文；不创建任务、工作线程、定时器或堆。

参数:

owner – [out] 尚未使用且由调用者拥有的适配器存储
slots – [in] 精确队列容量，不使用最大容量池
capacity – [in] 槽数量，必须大于零
guard – [in] 保持有效的短临界区接口
executor – [in] 单个真实执行接口
clock – [in] 与请求截止时间相同的单调时钟域
wake – [in] 可选的静态执行者通知，或 NULL

返回:

SUCCESS 或 INVALID

nx_result_t nx_bus_owner_submit(nx_bus_owner_t *owner, nx_request_t *request, void *operation, const nx_wait_port_t *completion, nx_owner_ticket_t *ticket)¶

建立请求链唯一的准入判定。

备注

任务中的多生产者上下文。空槽准入和 FIFO 入队在保护域内只执行常量规模的元数据操作。epoch 耗尽的槽永久退役。截止时间包含排队驻留。准入后调用者不得修改请求、操作或缓冲。准入后的通知错误不能将 SUCCESS 改为拒绝；执行者必须定期重新检查并推进。

参数:

owner – [inout] 有效且接受准入的适配器
request – [inout] 已准备为 READY 的存储，持续保留至 SETTLED
operation – [in] 特定执行者使用的描述符及载荷存储
completion – [in] 可选的静态调用者唤醒接口，或 NULL
ticket – [out] 稳定的取消身份，在 SUCCESS 时有效

返回:

SUCCESS 表示 ACCEPTED；拒绝时不保留任何引用

nx_result_t nx_bus_owner_cancel(nx_bus_owner_t *owner, nx_owner_ticket_t ticket)¶

通过稳定适配器存储提交取消。

备注

任务中的多生产者上下文。不接受请求指针。排队中的取消在不启动操作的情况下结清。活动操作的取消通过协作排空推进；不可逆操作可能已经传输了数据。

参数:

owner – [inout] 有效的适配器
ticket – [in] 先前接受的槽及 epoch

返回:

标记成功时为 SUCCESS；身份过期或已释放时为 STATE

nx_result_t nx_bus_owner_service(nx_bus_owner_t *owner)¶

至多推进一个有界执行步骤。

备注

仅限任务或显式循环。消费者不得通过等待操作执行服务。停止期间持续调用至空闲；回调不会创建工作线程。

参数:

owner – [inout] 有效的适配器，由其唯一执行者调用

返回:

取得进展或空闲时为 SUCCESS；等待提供者或存在争用时为 BUSY；也可能返回提供者错误，同时保留所有权以继续恢复

void nx_bus_owner_stop(nx_bus_owner_t *owner)¶

关闭准入，并请求每个已接受操作停止。

备注

任务上下文。生产者等待或汇合期间，执行者必须持续服务并排空。停止不表示已结清，也不表示可以回收存储。

参数:

owner – [inout] 有效的适配器

bool nx_bus_owner_idle(nx_bus_owner_t *owner)¶

检查执行及完成发布是否都已退出。

备注

回收所有者、槽、保护接口或通知存储前，必须等待生产者和所有唤醒发布者退出。此后不得再次 submit 或 cancel。

参数:

owner – [inout] 有效的适配器

返回:

队列、活动操作和服务发布者均不存在时为 true

struct nx_owner_guard_port_t¶

#include <bus_owner.h>

显式、有界元数据排斥端口。

备注

仅由任务生产者调用。enter/leave 必须串行化全部生产者与执行者。不得在 start/service/cancel、等待、载荷复制或通知回调期间持有该保护。使用架构保护时，状态会恢复进入时的中断屏蔽。接口存储必须保持有效。

公共成员

void *context¶

uintptr_t (*enter)(void*)¶

void (*leave)(void*, uintptr_t)¶

struct nx_owner_executor_port_t¶

#include <bus_owner.h>

真实且唯一的执行所有者，注入时不依赖 OS。

start 返回 SUCCESS 后开始借用 operation，直到 service 返回 SUCCESS。BUSY 或任何 start 错误都必须不保留 operation 引用／硬件效果；部分启动后发生的错误必须改为接受操作，再通过 service 报告。service 返回 SUCCESS 必须证明全部硬件／IRQ／延后访问已停止，写入最终 result/count，并释放 operation。BUSY 仍保留借用。其他 service 错误保留所有权，并要求继续恢复／service。cancel 请求排空，绝不单独释放 operation。回调只在外部调度的执行者中运行，且必须位于适配器元数据临界区之外。

备注

terminal_authority 选择自行观察截止时间并锁存首个终止硬件事实的提供者。其最终结果不会被晚到的取消或发布覆盖。其他执行者使用适配器的截止时间和取消结果。排队请求的截止时间始终由适配器负责。

公共成员

void *context¶

nx_result_t (*start)(void*, void *operation, nx_time_us_t deadline)¶

nx_result_t (*service)(void*, nx_result_t *result, size_t *transferred)¶

nx_result_t (*cancel)(void*)¶

bool terminal_authority¶

struct nx_owner_ticket_t¶

#include <bus_owner.h>

稳定控制身份；绝不解引用过期请求指针。

公共成员

size_t slot¶

uint64_t epoch¶

struct nx_owner_slot_t¶

#include <bus_owner.h>

调用者拥有的准确槽，连接在空闲链或 FIFO 链中；只能通过 owner init 初始化。

公共成员

nx_request_slot_t identity¶

void *operation¶

nx_wait_port_t completion¶

size_t next¶

bool cancel_requested¶

bool cancel_sent¶

struct nx_bus_owner_t¶

#include <bus_owner.h>

显式适配器状态；全部存储由外部应用供给。

公共成员

nx_owner_slot_t *slots¶

size_t capacity¶

size_t head¶

size_t tail¶

size_t active¶

size_t free_head¶

nx_owner_guard_port_t guard¶

nx_owner_executor_port_t executor¶

nx_clock_t clock¶

nx_wait_port_t wake¶

nx_result_t cancellation_result¶

bool accepting¶

bool servicing¶

clock_domain.h¶

显式时钟消费者与绑定 epoch 的排空控制。

类型定义

typedef struct nx_clock_domain nx_clock_domain_t¶: 不透明提供者，由其特权所有者静态供给。

typedef struct nx_clock_lease nx_clock_lease_t¶: 一个稳定、调用者拥有的消费者 token。

备注

首次取得前必须零初始化。SUCCESS 后提供者借用该精确对象；释放成功前不得复制、修改或回收。内部字段不是应用控制项。释放是提供者的最终访问，不证明外设已停止。只有该消费者的 IRQ、DMA 和观测者均已排空后才释放。

枚举

enum nx_clock_power_mode_t¶

仅浅睡眠保持既有时钟／时间域。

取值：

enumerator NX_CLOCK_SHALLOW_SLEEP¶

enumerator NX_CLOCK_DEEP_STOP¶

enumerator NX_CLOCK_DYNAMIC_RUN¶

函数

nx_result_t nx_clock_domain_acquire(nx_clock_domain_t *domain, nx_clock_lease_t *lease)¶

无等待地取得一个允许准入的时钟消费者。

备注

仅限特权 Thread 或可配置 IRQ；同一 CPU，以保存并恢复屏蔽状态的保护执行元数据操作。不支持 NMI、HardFault 或 SMP。容量限制令牌和别名扫描。即使准入已关闭，令牌仍持续借用至释放成功。

返回:: SUCCESS；准入关闭时为 BUSY；预算耗尽时为 EXHAUSTED；或 INVALID/STATE/CONTEXT，此时不保留令牌或效果

nx_result_t nx_clock_domain_release(nx_clock_domain_t *domain, nx_clock_lease_t *lease)¶

消费者排空后移除准确保留的 token。

备注

上下文与 acquire 相同。复制的令牌不能释放原令牌。SUCCESS 后不存在回调或最后一次访问。

返回:: SUCCESS；或 INVALID/STATE/CONTEXT，此时不移除借用

nx_result_t nx_clock_domain_close(nx_clock_domain_t *domain, nx_clock_barrier_t *control)¶: 关闭准入并返回当前 epoch 控制身份。

备注

仅限串行的特权 Thread。不等待、不取消、不写时钟，也不隐式关闭消费者。在同一关闭 epoch 内幂等；输出不得与活动存储重叠。

nx_result_t nx_clock_domain_quiescent(nx_clock_barrier_t control)¶

验证准入已关闭且保留消费者为零。

备注

同一 CPU 上的特权 Thread。该证明仅涵盖显式登记的消费者。不授权重新配置 PLL、暂停内核 Tick 或改变 Core 截止时间域。

返回:: SUCCESS；消费者仍存在时为 BUSY；控制身份过期或处于开放状态时为 STATE；也可能为 INVALID 或 CONTEXT，均不改变状态

nx_result_t nx_clock_domain_reopen(nx_clock_barrier_t control)¶

在新的准入 epoch 下重新开放已排空的时钟域。

备注

串行的特权 Thread。不重启时钟，也不重新解释现有截止时间。真正的冷态时钟变更还要求停止全部 Tick/时间提供者，并显式建立新的截止时间域；本 API 不执行这两项操作。

返回:: SUCCESS、BUSY、STATE、EXHAUSTED 或 CONTEXT，不产生变更

struct nx_clock_lease¶

#include <clock_domain.h>

一个稳定、调用者拥有的消费者 token。

备注

首次取得前必须零初始化。SUCCESS 后提供者借用该精确对象；释放成功前不得复制、修改或回收。内部字段不是应用控制项。释放是提供者的最终访问，不证明外设已停止。只有该消费者的 IRQ、DMA 和观测者均已排空后才释放。

公共成员

nx_clock_domain_t *owner¶

struct nx_clock_lease *next¶

uint64_t epoch¶

struct nx_clock_barrier_t¶

#include <clock_domain.h>

绑定 epoch 的关闭控制与静止证据。

备注

允许按值复制。该值不是授权令牌，也不能证明未登记消费者的状态。时钟域存储的寿命必须长于每份副本。成功重新开放会使全部旧控制身份失效，但不重置 epoch。

公共成员

nx_clock_domain_t *domain¶

uint64_t epoch¶

dp83848.h¶

显式 DP83848 身份、复位与链路观察机制。

作者 Nexus Team

宏定义

NX_DP83848_TI_ID¶

NX_DP83848_NS_ID¶

NX_DP83848_10_HALF¶

NX_DP83848_10_FULL¶

NX_DP83848_100_HALF¶

NX_DP83848_100_FULL¶

函数

nx_result_t nx_dp83848_probe(nx_dp83848_t *phy, nx_time_us_t deadline)¶

读取准确支持的身份；不匹配时绝不改用默认 PHY。

参数:

phy – [inout] 显式的 MDIO 接口、地址及预期支持的型号。
deadline – [in] MDIO 时钟域中的有限绝对截止时间。

返回:

成功；身份不符时为 UNSUPPORTED；或 MDIO 错误。

nx_result_t nx_dp83848_reset(nx_dp83848_t *phy, nx_time_us_t deadline)¶

有界 BMCR 软件复位，并观察自清除确认。

备注

仅限任务上下文，使用有限绝对截止时间；复位会重新采样器件 strap，并清除已配置事实。这不证明 GPIO、电源或 strap 正确。

参数:

phy – [inout] 已证明的身份及调用者拥有的组件状态。
deadline – [in] MDIO 时钟域中的有限绝对截止时间。

返回:

真实复位得到确认后成功；否则返回状态或 MDIO 错误。

nx_result_t nx_dp83848_configure(nx_dp83848_t *phy, const nx_dp83848_mode_t *mode, nx_time_us_t deadline)¶

启动显式协商或固定模式，不等待伪造链路。

备注

仅限任务上下文；必须已证明身份。SUCCESS 表示寄存器已配置，不表示自协商已完成。失败时 configured 保持 false。

参数:

phy – [inout] 已证明的身份，操作期间持续保持有效。
mode – [in] 显式的固定模式或协商通告。
deadline – [in] MDIO 时钟域中的有限绝对截止时间。

返回:

成功表示寄存器已配置；其他结果不建立已配置事实。

nx_result_t nx_dp83848_link(nx_dp83848_t *phy, nx_eth_link_t *link, nx_time_us_t deadline)¶

对锁存低电平 BMSR 读取两次，并观察 DP83848 PHYSTS 的真实速率／双工状态。

备注

仅限任务上下文；只在 SUCCESS 时改变输出。up 要求真实链路有效，且选用自协商时必须完成自协商。协议或远端故障不能虚构速率或链路状态。向 MAC 应用该状态仍是外部动作。

参数:

phy – [inout] 已探测并配置、由调用者拥有的组件。
link – [out] 观察值，必须与组件存储分离。
deadline – [in] MDIO 时钟域中的有限绝对截止时间。

返回:

成功时复制观察到的链路；其他结果保持输出不变。

struct nx_dp83848_mode_t¶

#include <dp83848.h>

外部策略显式选择自动协商或固定模式。

公共成员

uint8_t advertisement¶

bool autonegotiation¶

bool full_duplex¶

uint16_t speed_mbps¶

struct nx_dp83848_t¶

#include <dp83848.h>

调用者拥有的 PHY 状态；不提供默认板级地址、reset GPIO 或执行任务。

备注

expected_id 选择 TI 或 NS 型号，仅忽略修订号的四位字段。由一个任务所有者串行使用该组件及共享 MDIO 接口。

公共成员

const nx_mdio_port_t *mdio¶

uint32_t expected_id¶

uint8_t address¶

bool probed¶

bool configured¶

nx_dp83848_mode_t mode¶

file_flash.h¶

支持故障注入的 Native 持久文件 Flash 模型。

函数

nx_storage_status_t nx_file_flash_open(nx_file_flash_t *flash, const char *path, size_t size, size_t erase_size, size_t program_size)¶

打开使用独占锁的持久主机 Flash 模型。

备注

仅限任务上下文的 POSIX 模型。不为 MCU Flash 或真实掉电建立资格；现有文件大小不匹配时拒绝，不截断文件。

参数:

flash – [out] 尚未使用且由调用者拥有的存储
path – [in] 普通文件路径；拒绝符号链接遍历
size – [in] 精确的持久字节数
erase_size – [in] 均匀擦除块的字节数
program_size – [in] 对齐的编程字节数，范围 1..256

返回:

OK 或 INVALID/IO；打开失败时不保留文件描述符

void nx_file_flash_close(nx_file_flash_t *flash)¶

全部存储使用者静止后关闭主机文件。

备注

显式重新打开前不得再次调用接口。

参数:

flash – [inout] 已打开且串行使用的模型

void nx_file_flash_fail_after(nx_file_flash_t *flash, int64_t events)¶

设置显式模型中断边界。

备注

零表示模拟断电，直到显式清除。

参数:

flash – [inout] 串行使用的已打开模型
events – [in] 允许编程或擦除的字节数及同步尝试次数；负值表示禁用限制

struct nx_file_flash_t¶

#include <file_flash.h>

公共成员

int fd¶

nx_storage_port_t port¶

int64_t fail_after¶

uint64_t mutation_events¶

flash_storage.h¶

显式物理 Flash 区域适配器，不使用全局登记表。

作者 Nexus Team

函数

nx_result_t nx_flash_storage_bind(nx_flash_storage_adapter_t *adapter, nx_flash_region_t region, nx_time_us_t deadline, nx_storage_port_t *port)¶

绑定显式可写、擦除粒度统一的物理区域。

备注

仅限任务上下文，由调用者串行使用。平台不保留任何区域。混合扇区几何需要另一个显式存储适配器，本适配器会拒绝。I/O 脉冲结清保证同步持久化；接口调用返回后不保留任何调用者缓冲。物理掉电仍未取得资格。直接使用该接口时，调用者必须遵守 geometry.program_flags：ECC 单元需要真实擦除来源证明，不能凭全 0xff 读取推断。nx_storage_save 擦除非活动 bank，在下次擦除前对每个不同的完整编程单元最多写入一次，包括独立的最终提交标记。本适配器不跟踪隐藏的编程脉冲历史。

参数:

adapter – [out] 尚未使用的调用者存储，在全部存储调用期间保持有效
region – [in] 由外部选定的可写物理区域
deadline – [in] 覆盖完整修改事务的绝对截止时间
port – [out] 窄同步持久化接口，在 SUCCESS 时有效

返回:

SUCCESS；或 INVALID/PERMISSION/UNSUPPORTED 几何错误

void nx_flash_storage_set_deadline(nx_flash_storage_adapter_t *adapter, nx_time_us_t deadline)¶

设置下一事务唯一的绝对修改截止时间。

备注

调用者必须串行使用，并在 open/save/recovery 前设置该值。逐脉冲超时不能抢占硬件脉冲；I/O 在返回前结清。

参数:

adapter – [inout] 已绑定且无活动存储操作的适配器
deadline – [in] nx_time_now_us 域中的绝对截止时间

struct nx_flash_storage_adapter_t¶

#include <flash_storage.h>

调用者拥有的适配器，不使用动态绑定或全局 token 查找。

公共成员

nx_flash_region_t region¶

nx_time_us_t deadline¶

log.h¶

实例内同步、有界日志接收端。

作者 Nexus Team

枚举

enum nx_log_level_t¶

结构化严重级别；在访问接收端前完成过滤。

取值：

enumerator NX_LOG_DEBUG¶

enumerator NX_LOG_INFO¶

enumerator NX_LOG_WARNING¶

enumerator NX_LOG_ERROR¶

函数

nx_result_t nx_log_init(nx_log_t *logger, nx_log_sink_port_t sink, nx_log_level_t minimum)¶

向任务暴露日志对象之前初始化。

参数:

logger – [out] 尚未使用的调用者存储
sink – [in] 必需的有界同步输出端
minimum – [in] 接受的最低严重级别

返回:

SUCCESS 或 INVALID

nx_result_t nx_log_write(nx_log_t *logger, nx_log_level_t level, const void *bytes, size_t length, nx_time_us_t deadline)¶

写入调用者字节，不进行隐式分配／格式化。

备注

任务中的多生产者入口，使用非阻塞串行化。M0/M0+ 使用 CPU 本地保存并恢复 PRIMASK 的元数据临界区，要求调用者在同一 CPU 上具有特权。恢复进入时的屏蔽状态后才调用输出端。这不允许 NMI/HardFault 或跨安全域写入者使用。禁止 IRQ 调用。丢弃或重试策略由外部调用者负责。

参数:

logger – [inout] 有效的实例
level – [in] 消息严重级别
bytes – [in] 消息字节，仅在本次调用期间借用
length – [in] 字节数；为零时允许 NULL
deadline – [in] 输出端理解的绝对截止时间

返回:

被过滤或已发送的字节返回 SUCCESS；并发或递归写入返回 BUSY；停止后为 STATE；其他情况返回输出端错误

nx_result_t nx_log_flush(nx_log_t *logger, nx_time_us_t deadline)¶

刷新显式接收端，不创建后台执行任务。

备注

与 write 相同的任务、权限和 CPU 域。

参数:

logger – [inout] 有效的实例
deadline – [in] 输出端的绝对截止时间

返回:

SUCCESS、BUSY、STATE、UNSUPPORTED 或输出端错误

nx_result_t nx_log_stop(nx_log_t *logger)¶

拒绝新写入并检查接收端是否已退出。

备注

任务上下文。停止调用者可以重试；不会强行取消活动的输出端调用。回收日志器或输出端存储前必须等待发布者退出。

参数:

logger – [inout] 有效实例；外部使用者最终必须退出并完成汇合

返回:

没有活动的输出端调用时为 SUCCESS；排空期间为 BUSY

struct nx_log_sink_port_t¶

#include <log.h>

调用者注入的同步接收端。

备注

write/flush 即使超时或出错，也在返回前释放每个字节缓冲；异步或 DMA 输出端需要自行提供已结清的适配器。调用位于任务上下文，并受绝对单调截止时间约束。不存在输出端发现、分配、格式化、工作线程或全局错误处理器。

公共成员

void *context¶

nx_result_t (*write)(void*, nx_log_level_t, const void*, size_t, nx_time_us_t deadline)¶

nx_result_t (*flush)(void*, nx_time_us_t deadline)¶

struct nx_log_t¶

#include <log.h>

日志存储属于调用者；共享不可变端口在初始化时复制。

公共成员

nx_log_sink_port_t sink¶

nx_log_level_t minimum¶

uint32_t busy¶

uint32_t stopped¶

modbus_rtu.h¶

有界 Modbus RTU 核心与显式 RS485 端口。

作者 Nexus Team

宏定义

NX_MODBUS_ADU_MAX¶

NX_MODBUS_REGISTER_MAX¶

枚举

enum nx_modbus_register_result_t¶

取值：

enumerator NX_MODBUS_OK¶

enumerator NX_MODBUS_ILLEGAL_ADDRESS¶

enumerator NX_MODBUS_ILLEGAL_VALUE¶

enumerator NX_MODBUS_DEVICE_FAILURE¶

enumerator NX_MODBUS_DEVICE_BUSY¶

enum nx_modbus_link_state_t¶

取值：

enumerator NX_MODBUS_RX_IDLE¶

enumerator NX_MODBUS_RX_FRAME¶

enumerator NX_MODBUS_RX_DISCARD¶

enumerator NX_MODBUS_LINK_FAULTED¶

函数

uint16_t nx_modbus_crc16(const uint8_t *bytes, size_t length)¶

对调用者字节计算标准 Modbus CRC16。

参数:

bytes – [in] 输入，仅长度为零时允许 NULL
length – [in] 字节数

返回:

CRC16；非零长度配合无效 NULL 输入时返回零

bool nx_modbus_rtu_init(nx_modbus_rtu_t *server, const nx_modbus_config_t *config)¶

初始化尚未使用或完全静止的协议实例。

备注

仅限任务上下文；配置被复制，各 context 保持有效。报告首次 direction(false) 失败；不创建工作线程或 UART。禁止重新初始化仍持有故障 TX 借用的实例，必须先 stop/recover。

参数:

server – [out] 调用者拥有的存储，不存在先前的传输借用
config – [in] 显式的寄存器及 RS485 接口，以及有限预算

返回:

初始化成功进入 RX 静默判定阶段时为 true

bool nx_modbus_rtu_feed(nx_modbus_rtu_t *server, uint8_t byte, uint64_t arrival_us)¶

输入外部添加时间戳的 UART 字节。

备注

仅限任务上下文。IRQ 队列在外部显式提供且容量有界；队列溢出时必须调用 rx_error。不进行活动 UART 发现，也没有 ISR 回调。

参数:

server – [inout] 已初始化的实例，由调用者串行使用
byte – [in] 线上字节
arrival_us – [in] 接口单调时钟域中的捕获时间戳

返回:

字节并入帧时为 true；丢弃或出错时为 false

bool nx_modbus_rtu_poll(nx_modbus_rtu_t *server, uint64_t now_us)¶

推进 RTU 静默间隔与有界同步 RS485 响应。

备注

仅限任务上下文，由外部显式调度。RS485 排空必须观察最终停止位。中止失败时，LINK_FAULTED 保留 TX 字节并保持 DE 置位；直到 recover 或 stop 成功前，必须保持实例及接口有效。

参数:

server – [inout] 已初始化且具有单一执行所有者的实例
now_us – [in] 同一单调时钟域中的快照

返回:

取得进展时为 true；时钟或传输错误时为 false

void nx_modbus_rtu_rx_error(nx_modbus_rtu_t *server, uint64_t now_us)¶

丢弃发生错误或溢出的接收帧。

备注

仅限任务上下文。不丢弃仍保留的故障 TX 借用。

参数:

server – [inout] 已初始化且串行使用的实例
now_us – [in] 接口单调时钟域中的错误时间戳

bool nx_modbus_rtu_recover(nx_modbus_rtu_t *server)¶

结清保留的 TX，再恢复接收静默判定。

备注

显式的任务维护动作，不虚构恢复。

参数:

server – [inout] 已初始化且串行使用的实例，各接口保持有效

返回:

只有实际完成接口中止和排空，并切换到接收方向后才为 true

bool nx_modbus_rtu_stop(nx_modbus_rtu_t *server)¶

回收协议存储之前先使端口结清。

备注

必须先停止将来可能调用 feed/poll 的使用者。成功停止后，除显式初始化外不得再次使用。

参数:

server – [inout] 已初始化且独占拥有的实例

返回:

传输借用全部结束且实例已停止时为 true；false 保留故障状态、TX 字节及全部接口生命周期责任

struct nx_modbus_registers_t¶

#include <modbus_rtu.h>

公共成员

void *context¶

nx_modbus_register_result_t (*read)(void*, uint16_t, uint16_t, uint16_t*)¶

nx_modbus_register_result_t (*authorize_write)(void*, uint16_t, uint16_t, const uint16_t*)¶

nx_modbus_register_result_t (*write_atomic)(void*, uint16_t, uint16_t, const uint16_t*)¶

struct nx_modbus_rs485_port_t¶

#include <modbus_rtu.h>

公共成员

void *context¶

uint64_t (*now_us)(void*)¶

bool (*direction)(void*, bool transmit)¶

bool (*write)(void*, const uint8_t*, size_t, uint64_t deadline_us)¶

bool (*drain)(void*, uint64_t deadline_us)¶

bool (*abort_and_settle)(void*, uint64_t deadline_us)¶

struct nx_modbus_counters_t¶

#include <modbus_rtu.h>

公共成员

uint64_t frames¶

uint64_t accepted¶

uint64_t crc_errors¶

uint64_t timing_errors¶

uint64_t overflows¶

uint64_t exceptions¶

uint64_t broadcasts¶

uint64_t tx_errors¶

uint64_t clock_errors¶

struct nx_modbus_config_t¶

#include <modbus_rtu.h>

公共成员

uint8_t address¶

uint32_t baudrate¶

uint8_t bits_per_character¶

uint32_t tx_timeout_us¶

uint32_t abort_timeout_us¶

nx_modbus_registers_t registers¶

nx_modbus_rs485_port_t port¶

struct nx_modbus_rtu_t¶

#include <modbus_rtu.h>

公共成员

nx_modbus_config_t config¶

nx_modbus_counters_t counters¶

nx_modbus_link_state_t state¶

uint32_t t1_5_us¶

uint32_t t3_5_us¶

uint64_t last_byte_us¶

uint64_t last_event_us¶

uint16_t rx_length¶

uint16_t tx_length¶

uint8_t rx[NX_MODBUS_ADU_MAX]¶

uint8_t tx[NX_MODBUS_ADU_MAX]¶

uint16_t values[NX_MODBUS_REGISTER_MAX]¶

bool initialized¶

bool clock_started¶

owner_observer.h¶

显式 owner 推进诊断，不含默认状态。

作者 Nexus Team

函数

nx_result_t nx_owner_observer_bind(nx_owner_observer_t *observer, nx_bus_owner_t *owner)¶

绑定已初始化的准确 owner，不创建工作。

参数:

observer – [inout] 新的零初始化或已分离附属状态，与所有者分开存储。
owner – [inout] 已初始化的稳定所有者，不存在并发生命周期操作。

返回:

SUCCESS 或 INVALID/STATE；拒绝时不执行服务，也不建立借用。

nx_result_t nx_owner_observer_service(nx_owner_observer_t *observer, nx_time_us_t now, nx_owner_observation_t *out)¶

准确执行一次真实 service 步骤并复制诊断。

备注

时钟倒退不会阻止排空或重写结果。快照在硬件服务之外使用现有保护。该保护内不执行回调、槽扫描或工作线程。隔离状态和已到期截止时间都不会释放借用。输出还必须避开已接受的描述符及载荷。这里只检查所有者和槽控制对象的存储区间。

参数:

observer – [inout] 由唯一执行者使用的已绑定附属状态。
now – [in] 单调时间戳，与服务结果独立。
out – [out] 独立且稳定的输出，不保留引用。

返回:

实际服务结果；无效绑定在执行前拒绝。

void nx_owner_observer_detach(nx_owner_observer_t *observer)¶

仅撤销观察绑定，不拆除 owner 或借用。

参数:

observer – [inout] 由调用者串行使用的附属状态，不再存在读取者。

struct nx_owner_observation_t¶

#include <owner_observer.h>

已复制的 service 事实，不含 request、payload 或 slot 引用。

公共成员

nx_result_t service_result¶

nx_result_t diagnostic_result¶

nx_time_us_t observed_at¶

nx_time_us_t max_gap¶

uint32_t calls¶

uint32_t busy¶

uint32_t errors¶

uint32_t quarantines¶

uint32_t clock_errors¶

nx_owner_ticket_t active¶

nx_request_state_t active_state¶

bool has_active¶

bool idle¶

bool accepting¶

bool queued¶

bool slot_available¶

struct nx_owner_observer_t¶

#include <owner_observer.h>

调用者显式选择的附加状态；不向默认 owner 增加指针。

备注

精确的所有者、槽和保护接口必须保持有效，直到分离完成且全部观测者调用退出。同一唯一所有者执行者调用该包装接口；生产者调用继续使用所有者保护。不得在绑定期间重新初始化或替换底层所有者。

公共成员

nx_bus_owner_t *owner¶

nx_time_us_t last_observed¶

nx_owner_observation_t observation¶

bool observed¶

settings.h¶

在持久化整块存储上提供有界 key/value 暂存。

作者 Nexus Team

宏定义

NX_SETTINGS_HEADER_SIZE¶

函数

nx_storage_status_t nx_settings_open(nx_settings_t *settings, nx_storage_t *storage, uint32_t schema, void *image, size_t image_bytes, uint32_t max_entries)¶

加载精确 schema，或暂存空的未提交镜像。

备注

仅任务上下文同步扫描。缺少 blob 时暂存空镜像，不读取默认值或写 Flash。不同 schema/format 返回 UNSUPPORTED，绝不重写。截断、重复或无序 key 返回 CORRUPT。加载失败不能变成空的可写存储；实例保持关闭。

参数:

settings – [out] 未使用或已关闭的独占实例
storage – [inout] 已打开的持久化存储；Settings 打开期间不得有其他变更性客户端
schema – [in] 产品定义的 schema 身份，允许零
image – [inout] 调用者 buffer，与两个实例及 storage workspace 独立；借用至 close 或失败的 commit
image_bytes – [in] 至少 HEADER_SIZE，至多 UINT32_MAX
max_entries – [in] 暂存条目数量的非零上限

返回:

OK、INVALID、NO_SPACE、CORRUPT、UNSUPPORTED 或 port 错误

nx_storage_status_t nx_settings_get(const nx_settings_t *settings, uint32_t key, void *output, size_t *size)¶

复制暂存值，不暴露内部存储。

备注

仅任务上下文同步复制，不保留指针。缺 key 时报告长度零。NO_SPACE 保持输出不变并报告所需字节数。不执行底层 Flash 操作。

参数:

settings – [in] 已打开实例，与全部变更操作串行化
key – [in] 精确的产品分配标识
output – [out] 独立目标，或以 NULL 只查询长度
size – [inout] 输入为容量，输出为所需或实际值字节数；与元数据、暂存镜像及 output 独立

返回:

OK、NOT_FOUND、NO_SPACE 或 INVALID

nx_storage_status_t nx_settings_set(nx_settings_t *settings, uint32_t key, const void *value, size_t size)¶

在有界 RAM 暂存中插入或替换复制的值。

备注

仅任务上下文，由镜像容量和条目上限约束。准入失败不改变条目或 dirty 状态。值变化使暂存变脏，不写 Flash；值相同时保留镜像和原 dirty 状态。

参数:

settings – [inout] 已打开且独占拥有的实例
key – [in] 精确的产品分配标识
value – [in] 输入与实例及暂存镜像独立；仅空值允许 NULL，调用期间借用
size – [in] 值字节数，至多 UINT32_MAX

返回:

OK、NO_SPACE 或 INVALID

nx_storage_status_t nx_settings_remove(nx_settings_t *settings, uint32_t key)¶

移除暂存 key，不写 Flash。

备注

仅任务上下文同步操作。缺 key 时无影响。成功时压紧暂存并标记 dirty。

参数:

settings – [inout] 已打开且独占拥有的实例
key – [in] 精确的产品分配标识

返回:

OK、NOT_FOUND 或 INVALID

nx_storage_status_t nx_settings_commit(nx_settings_t *settings)¶

通过持久化 Storage 提交完整暂存快照。

备注

仅任务上下文同步完成调用；底层 Flash 可能暂停执行。干净暂存不写入，保存成功清除 dirty。变更性 I/O 失败会关闭实例并保留 dirty 供诊断，不再借用暂存。先重新打开 Storage，再打开 Settings 以确定保留的提交；失败可能发生在新 marker 已持久化之后。不恢复就重试失败 commit 会被拒绝。

参数:

settings – [inout] 已打开且独占拥有的实例

返回:

OK 或底层 storage 错误

void nx_settings_close(nx_settings_t *settings)¶

释放 Settings 元数据，不提交暂存值。

备注

仅任务上下文，在全部调用之后串行化。不执行 I/O，也无保留引用。底层 Storage 保持打开；其 scratch 生命周期仍由 Storage 合同决定。

参数:

settings – [inout] 已静默的实例，或 NULL

struct nx_settings_t¶

#include <settings.h>

调用者拥有的 Settings 元数据与有界暂存镜像。

备注

仅任务上下文；全部操作及底层存储须串行化。无 heap、worker 或全局 key 注册表。Key 为产品分配的 uint32 标识，值为字节串，允许空串。格式为 little-endian，不提供认证。产品拥有默认值、schema 迁移、授权、持久化频率和 Flash 预留。只有 commit 写存储；close 丢弃暂存变更。

公共成员

nx_storage_t *storage¶

uint8_t *image¶

size_t capacity¶

size_t size¶

uint32_t schema¶

uint32_t count¶

uint32_t max_entries¶

bool opened¶

bool dirty¶

spi_async_owner.h¶

一个显式总线的可选有限异步 SPI 执行者。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_spi_async_owner_executor_port(nx_spi_async_owner_executor_t *executor, const nx_spi_port_t *port)¶

将具备异步能力的总线绑定到显式 owner 执行者。

备注

启动或任务上下文。操作仅使用本总线上的 nx_spi_owner_operation_t 端点；准入前检查成员关系。不选择轮询回退。控制器和执行者必须保持有效，直到排空、控制确认及观测者退出全部完成。QUARANTINED 保留两项缓冲借用。所有者关闭后，硬件停止及 IRQ/通知销毁仍是外部显式步骤，不属于此次绑定。

参数:

executor – [out] 新存储，不存在先前尚未结束的借用。
port – [in] 已初始化且由该执行者独占拥有的控制器；直接客户端和其他所有者必须静默。

返回:

有效的执行接口；方法不完整时返回全零接口。

struct nx_spi_async_owner_executor_t¶

#include <spi_async_owner.h>

独立于轮询适配器的准确异步存储。

备注

inner 是私有发布对象。外层所有者发布 SETTLED 前，必须先结束其借用。不创建队列、不复制载荷，也不分配或创建隐藏工作线程。

公共成员

const nx_spi_port_t *port¶

nx_spi_request_t inner¶

bool pending¶

spi_owner.h¶

有界 owner 适配器的显式轮询 SPI 执行者。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_spi_owner_executor_port(nx_spi_owner_executor_t *executor, const nx_spi_port_t *port)¶

绑定显式同步 SPI 执行适配器。

备注

start 执行真实的 CPU 主动轮询事务，并在返回前释放全部 I/O 缓冲。所有者的 service 随后才发布调用者拥有的请求。另一任务的 cancel 不能抢占轮询；轮询调用返回后，即使取消或发布延迟随后到来，其结果仍为最终结果。不得宣称 IRQ/DMA 模式或低 CPU 占用的异步硬件执行。产生任何线上效果前，端点必须证明其控制器身份；同一控制器上的不同片选仍然有效。控制器和执行者的寿命必须覆盖所有者关闭及全部观测者。

参数:

executor – [out] 新存储，不存在尚未结束的操作
port – [in] 仅由该所有者服务的控制器

返回:

供 nx_bus_owner_init 使用的接口；输入无效时为全零接口

struct nx_spi_owner_operation_t¶

#include <spi_owner.h>

调用者拥有的 SPI 事务描述符，借用保持到 SETTLED。

公共成员

const nx_spi_endpoint_t *endpoint¶

const uint8_t *tx¶

uint8_t *rx¶

size_t length¶

struct nx_spi_owner_executor_t¶

#include <spi_owner.h>

准确轮询执行者存储，不复制载荷或设置队列。

公共成员

const nx_spi_port_t *port¶

nx_result_t result¶

size_t transferred¶

bool pending¶

storage.h¶

使用显式窄端口的双 bank 持久 blob 存储。

作者 Nexus Team

宏定义

NX_STORAGE_HEADER_SIZE¶

枚举

enum nx_storage_status_t¶

存储错误显式暴露重试／重开／恢复决策。

取值：

enumerator NX_STORAGE_OK¶

enumerator NX_STORAGE_INVALID¶

enumerator NX_STORAGE_IO¶

enumerator NX_STORAGE_CORRUPT¶

enumerator NX_STORAGE_NO_SPACE¶

enumerator NX_STORAGE_NOT_FOUND¶

enumerator NX_STORAGE_UNSUPPORTED¶

函数

nx_storage_status_t nx_storage_open(nx_storage_t *storage, const nx_storage_port_t *port, size_t offset, size_t bank_size, void *workspace, size_t workspace_bytes)¶

打开／恢复两个外部供给、擦除粒度统一的 bank。

备注

仅限任务上下文，对两个 bank 的载荷执行有界扫描。工作区由实例持续借用，覆盖此后每次 load/save 调用。

参数:

storage – [out] 尚未使用或已静默的实例，不存在并发调用
port – [in] 返回前已结清的持久化接口，可以是存储对象原有的接口
offset – [in] 接口区域内按擦除粒度对齐的起点
bank_size – [in] 每个 bank 按擦除粒度对齐的字节数
workspace – [in] 调用者缓冲，与实例及载荷不重叠
workspace_bytes – [in] 至少为 max(32, port.program_size)

返回:

恢复成功或存储为空时为 OK；代次有歧义，或仅存在无效的已提交代次时为 CORRUPT；接口或几何错误时为 IO/INVALID

nx_storage_status_t nx_storage_load(nx_storage_t *storage, void *output, size_t *size)¶

加载并验证最新提交的完整 blob。

备注

只有 OK 时输出字节才有效；失败时可能已部分写入输出。返回后不保留目标指针。

参数:

storage – [inout] 已打开的实例，本次调用期间独占拥有
output – [out] 目标；NULL 表示只查询所需大小
size – [inout] 输入为容量，输出为载荷字节数或所需字节数

返回:

OK、NOT_FOUND、NO_SPACE、CORRUPT 或 IO/INVALID

nx_storage_status_t nx_storage_save(nx_storage_t *storage, const void *data, size_t size)¶

将完整 blob 提交到非活动 bank。

备注

同步后最后编程提交标记。修改失败时保留先前的 bank，并要求重新打开；标记失败有歧义时，新 blob 可能已经提交。迁移、认证及恢复策略由产品负责。

参数:

storage – [inout] 已打开且独占拥有的实例
data – [in] 与工作区不重叠的载荷，仅调用期间借用
size – [in] 载荷字节数；为零时允许 NULL

返回:

OK、NO_SPACE、INVALID 或底层接口错误

size_t nx_storage_capacity(const nx_storage_t *storage)¶

查询可用 blob 容量，不访问硬件。

参数:

storage – [in] 已建立几何信息的实例，或 NULL

返回:

每个 bank 的载荷字节数；几何无效时为零

struct nx_storage_port_t¶

#include <storage.h>

同步且已结清的持久 Flash 端口。

备注

仅限任务上下文；调用者串行使用全部操作。偏移以所提供区域的起点为基准，单位为字节。program 只在完整且对齐的编程单元内将 1 改为 0；erase 使用完整且均匀的擦除单元。sync 使先前成功的写入持久化。错误可能改变所寻址单元的一部分，但返回后绝不保留调用者缓冲。RAM 是模型，不是持久化实现。区域、布局及电源策略由产品负责。

公共成员

void *ctx¶

size_t size¶

size_t erase_size¶

size_t program_size¶

nx_storage_status_t (*read)(void*, size_t, void*, size_t)¶

nx_storage_status_t (*program)(void*, size_t, const void*, size_t)¶

nx_storage_status_t (*erase)(void*, size_t, size_t)¶

nx_storage_status_t (*sync)(void*)¶

struct nx_storage_t¶

#include <storage.h>

实例元数据与调用者确定容量的工作区。

备注

两个可独立擦除的 bank 提交完整 blob。不使用堆、全局注册表、最大容量池或默认产品预留。线上格式 v1 显式采用小端和 CRC 保护，不提供认证。实例、接口 context 和工作区必须保持有效，直到关闭并静默。修改性 I/O 错误会使 opened 失效；需要重新打开，才能确定哪个提交实际保留。

公共成员

nx_storage_port_t flash¶

size_t offset¶

size_t bank_size¶

size_t payload_offset¶

uint64_t generation¶

size_t payload_size¶

int active_bank¶

bool opened¶

uint8_t *workspace¶

size_t workspace_bytes¶

uart_owner.h¶

显式 IRQ UART 执行者与私有提供者请求结清。

作者 Nexus Team

函数

nx_owner_executor_port_t nx_uart_owner_executor_port(nx_uart_owner_executor_t *executor, const nx_uart_port_t *uart)¶

将 UART 控制器绑定到一个显式 service 执行者。

备注

启动或任务上下文。控制器和执行者保持有效，直到所有者停止、排空及外部观测者静默。直接 UART 使用者不得共享该控制器。排队时间由总线所有者负责；启动后，以 UART 首次观察到的终止 TC、错误、取消或截止时间事实为准。cancel 先观察提供者完成或截止时间，再请求中止。排空失败时，两个请求均保持 QUARANTINED；恢复期间必须持续 service。外层 SETTLED 绝不能早于以 acquire 语义观察到的内层 SETTLED 及指针分离。只有全部所有者操作和控制均静默后，应用才分别停止硬件及 RX 消费者。

参数:

executor – [inout] 尚未使用且由调用者拥有的存储，不存在并发调用
uart – [inout] 已初始化且由该执行者独占拥有的 UART

返回:

供 nx_bus_owner_init 使用的接口；NULL 输入时为无效的全零接口

struct nx_uart_owner_operation_t¶

#include <uart_owner.h>

调用者拥有的 TX 载荷描述符，借用保持到外层 SETTLED。

公共成员

const uint8_t *data¶

size_t length¶

struct nx_uart_owner_executor_t¶

#include <uart_owner.h>

一个执行者准确且私有的提供者请求。

备注

inner 是独立的发布对象，不是另一个外层队列或调用者准入。只有该执行者访问 inner；总线所有者发布外层 SETTLED 前，生产者持续保留外层请求及载荷。不复制缓冲，不使用堆、工作线程或池。绝不将 inner 交给应用观测者。

公共成员

const nx_uart_port_t *port¶

nx_uart_tx_request_t inner¶

bool pending¶

usb_acm.h¶

由调用者拥有存储的可选 CDC ACM 控制子集。

作者 Nexus Team

枚举

enum nx_usb_acm_change_t¶

取值：

enumerator NX_USB_ACM_GET_LINE_CODING¶

enumerator NX_USB_ACM_SET_LINE_CODING¶

enumerator NX_USB_ACM_SET_CONTROL_LINE_STATE¶

enumerator NX_USB_ACM_SEND_BREAK¶

函数

nx_result_t nx_usb_acm_initialize(nx_usb_acm_t *acm, const nx_usb_device_profile_t *profile, uint8_t interface_number, const nx_usb_acm_state_t *initial)¶

绑定一个显式通信接口及初始状态。

备注

与 USBControl 使用同一个串行执行的特权 Task，进入时 IRQ 未屏蔽；不允许 ISR、callback 或第二个 Task 重入。外部分派器在适配器活动期间将 EP0 使用权独占交给它。接口描述符、类能力和配置就绪状态由外部负责；初始化不校验类描述符字节。

参数:

acm – [inout] 自然对齐、零初始化的调用者存储。
profile – [in] 不可变的选定 USB profile，包含按 epoch 防护的 SETUP 拒绝端口，且不与 acm 重叠。
interface_number – [in] 与外部描述准确对应的 ACM 接口。
initial – [in] 不重叠、自然对齐的初始软件意图。

返回:

SUCCESS、INVALID、STATE 或 CONTEXT；不启动硬件。

nx_result_t nx_usb_acm_begin(nx_usb_acm_t *acm, uint64_t epoch, nx_time_us_t deadline)¶

将当前已由软件发布的 SETUP 分派到此子集。

备注

严格校验 class/interface 的方向、wIndex、wValue 和 wLength。GET_LINE_CODING 返回七个已提交的字节。SET_LINE_CODING 接收恰好七字节，但等待显式审批。control-line/break 请求等待审批后才启动 STATUS。非法或未知请求的分派按合同显式执行 STALL，但不新增借用。调用前须由外部先路由标准请求及其他类请求。

参数:

acm – [inout] 已绑定且非活动的适配器；没有其他 EP0 packet 使用者。
epoch – [in] 准确的、非零的已发布 SETUP 身份。
deadline – [in] 所有阶段及外部审批共用一个独立的绝对 deadline；NEVER 允许无限等待。

返回:

SUCCESS 表示接受操作；BUSY/STATE/TIMEOUT 表示拒绝且不新增借用。按 epoch 防护的 STALL 成功后，未知请求返回 UNSUPPORTED，字段格式错误返回 INVALID；否则返回防护拒绝操作的实际错误。

nx_result_t nx_usb_acm_step(nx_usb_acm_t *acm)¶

推进 USBControl 一步，仅归并已 acquire 观察到的完成。

备注

最多推进一次底层 USBControl，遵守其一次 service、一次 state 读取及一次 packet 动作的上限。不在循环中排空整笔事务。取消、替换或超时后仍须继续推进。OUT0 隔离仍需外部 device owner 显式 stop，然后继续 step。不得自动停止 controller。只有已批准的 outer 经 acquire 观察到 SUCCESS 才提交意图：它证明对应 STATUS 包已获真实 ACK。后来的 SETUP/reset、closing 或 state 读取失败不能撤销 packetizer 已 acquire 观察到的 ACK。ACK 前的替换会中止并排空，不提交。命令完成后重置类状态属于外部 owner 的独立策略。软件 epoch 检查不保证与尚未由 IRQ 采集的物理 SETUP 包原子同步。

参数:

acm – [inout] 同一执行者；活动期间保留全部存储。

返回:

推进／provider 结果；错误绝不撤销借用。

nx_result_t nx_usb_acm_pending(const nx_usb_acm_t *acm, nx_usb_acm_pending_t *pending)¶

复制暂存的意图，供外部校验及授权。

备注

线上格式允许非零 rate、stop bits 为 0..2、parity 为 0..4，以及 data bits 为 5/6/7/8/16。外部硬件或策略可只支持其中一部分值。该值可能已过时；approve 会重新核对软件 epoch。检查不等于批准。

参数:

acm – [in] 同一 Task；SET_LINE_CODING 必须处于 DATA_READY。
pending – [out] 不重叠、自然对齐的值输出；拒绝时保持不变。不向外提供指向被借用 payload 的指针。

返回:

SUCCESS、STATE、INVALID 或 CONTEXT。线编码 DATA 阶段格式错误或短于要求时返回 INVALID；owner 可显式拒绝。

nx_result_t nx_usb_acm_approve(nx_usb_acm_t *acm, uint64_t epoch, bool accepted)¶

在 STATUS 前授权暂存意图，或拒绝此 epoch。

备注

审批不得应用 UART 参数或物理线路。出现更新的 committed_epoch 后，由外部 owner 应用复制出的意图，并负责应用失败及恢复。此处不运行 callback。SEND_BREAK 记录 0（停止）、0xffff（无限期）或有限毫秒时长的意图，不创建计时器、不自动到期，也不声称物理 break 已发生。

参数:

acm – [inout] 同一个活动适配器及串行 Task 执行者。
epoch – [in] 准确的操作身份。
accepted – [in] true 仅授权；false 请求按 epoch 防护的 STALL。

返回:

SUCCESS 改变授权；其他结果保留活动借用且不授权变更。格式错误的线编码不能获批；在 DATA_READY 仍允许传入 false 拒绝。

nx_result_t nx_usb_acm_cancel(nx_usb_acm_t *acm, uint64_t epoch)¶

取消一个活动身份，保留全部已准入存储。

参数:

acm – [inout] 同一执行者，保留至实际排空。
epoch – [in] 准确的活动身份。

返回:

SUCCESS 请求排空，或丢弃尚未准入的零数据意图；身份过期返回 STATE。取消仅请求排空。在取消前或取消期间 acquire 到的匹配 STATUS ACK 仍由 packetizer 优先处理；step 在 acquire 返回 outer SUCCESS 时提交已批准的原 epoch 意图，后续 epoch 不撤销该提交。

nx_result_t nx_usb_acm_snapshot(const nx_usb_acm_t *acm, nx_usb_acm_snapshot_t *snapshot)¶

复制当前软件意图及最近观察到的结果。

备注

committed_epoch 的更新是软件通知，不是事件队列或物理应用确认。若必须消费每次已提交的变更，应在每次 step 后、分派下一操作前轮询。GET 不改变它。

参数:

acm – [in] 同一执行者；不刷新 device state。
snapshot – [out] 不重叠、自然对齐的值输出，错误时保持不变。result 是适配器结果，wire_result 是 outer 传输结果（未准入 outer 时为 STATE）。

返回:

SUCCESS、INVALID 或 CONTEXT；不返还借用。

struct nx_usb_acm_line_coding_t¶

#include <usb_acm.h>

CDC 线上取值，不表示 UART 支持每个值。

公共成员

uint32_t rate¶

uint8_t stop_bits¶

uint8_t parity¶

uint8_t data_bits¶

struct nx_usb_acm_state_t¶

#include <usb_acm.h>

最近已获 ACK 的软件意图；物理应用由外部负责。

公共成员

nx_usb_acm_line_coding_t line_coding¶

uint16_t control_lines¶

uint16_t break_duration¶

struct nx_usb_acm_pending_t¶

#include <usb_acm.h>

供外部授权的值副本，绝不是可修改的 DATA 视图。

公共成员

nx_usb_acm_state_t proposed¶

uint64_t epoch¶

nx_usb_acm_change_t change¶

struct nx_usb_acm_snapshot_t¶

#include <usb_acm.h>

公共成员

nx_usb_acm_state_t committed¶

uint64_t committed_epoch¶

uint64_t completed_epoch¶

nx_result_t result¶

nx_result_t wire_result¶

nx_usb_control_phase_t phase¶

bool active¶

struct nx_usb_acm_t¶

#include <usb_acm.h>

固定的调用者存储；绑定期间字段为私有。

备注

元数据须满足其 C 类型的自然对齐，地址范围不得回绕；wire bytes 只需字节对齐。由零初始化存储绑定一次。不得通过清零或重新绑定撤销借用。profile、face 及此完整 context 的生命周期须覆盖每个 packet/outer 借用与独立 observer。不使用动态分配、逐实例方法表、worker 或默认实例。provider face 仍共享只读 ops。

公共成员

nx_usb_control_t control¶

nx_usb_control_request_t reply¶

nx_usb_acm_state_t committed¶

nx_usb_acm_pending_t pending¶

nx_time_us_t deadline¶

uint64_t last_epoch¶

uint64_t committed_epoch¶

uint64_t completed_epoch¶

nx_result_t result¶

nx_result_t wire_result¶

uint8_t wire[7]¶

uint8_t interface_number¶

bool active¶

bool outer_started¶

bool approved¶

usb_control.h¶

由调用者拥有的单执行者 EP0 分包器。

作者 Nexus Team

枚举

enum nx_usb_control_reply_kind_t¶

取值：

enumerator NX_USB_CONTROL_IN_REPLY¶

enumerator NX_USB_CONTROL_OUT_REPLY¶

enumerator NX_USB_CONTROL_STATUS_REPLY¶

enum nx_usb_control_phase_t¶

取值：

enumerator NX_USB_CONTROL_IDLE¶

enumerator NX_USB_CONTROL_WAIT_REPLY¶

enumerator NX_USB_CONTROL_DATA_IN¶

enumerator NX_USB_CONTROL_DATA_IN_ZLP¶

enumerator NX_USB_CONTROL_DATA_OUT¶

enumerator NX_USB_CONTROL_DATA_READY¶

enumerator NX_USB_CONTROL_STATUS_IN¶

enumerator NX_USB_CONTROL_STATUS_OUT¶

enumerator NX_USB_CONTROL_DRAINING¶

enumerator NX_USB_CONTROL_NEEDS_DEVICE_STOP¶

enumerator NX_USB_CONTROL_STALLED¶

enumerator NX_USB_CONTROL_CLOSED¶

函数

nx_result_t nx_usb_control_initialize(nx_usb_control_t *control, const nx_usb_device_profile_t *profile)¶

将调用者零初始化的存储绑定到稳定且已校验的 ROM profile。

备注

除准备函数外，所有函数都由同一个串行化特权 Task 执行者调用，且进入时 IRQ masks 必须 clear。callback、第二个 Task 或 ISR 均不得重入。owner 授予该适配器 EP0 包的独占使用权，仍负责外部 event-ring 管理及显式 device 恢复策略。controller／endpoint reset 均不能使借用失效。绑定成功后，在 begin 前不持有 provider 引用。

参数:

control – [inout] 已零初始化、且与 profile 不重叠的存储。
profile – [in] 不可变的事实与接口面，其生命周期覆盖每一项 adapter 借用。

返回:

成功或拒绝；不启动硬件，不创建 Task，也不分配内存。

nx_result_t nx_usb_control_in_prepare(nx_usb_control_request_t *request, const uint8_t *bytes, size_t length, uint64_t epoch, nx_time_us_t deadline)¶

准备回复，不建立借用，也不读取不可变的 IN 字节。

备注

仅限 Task 的准备操作；字节必须保持有效，直到以 acquire 语义观察到已准入 outer 的 SETTLED。短于请求且恰好落在 MPS 边界的回复会发出须获 ACK 的 DATA ZLP。

参数:

request – [inout] 已初始化为 READY，或已消费 SETTLED 结果的存储。
bytes – [in] 不可变的外部 descriptor／reply；仅长度为空时允许 NULL。
length – [in] 可用字节数；回复截断至 SETUP wLength。
epoch – [in] 非零 SETUP 身份。
deadline – [in] 覆盖所有阶段的独立绝对单调 deadline。

返回:

成功、INVALID 或 STATE；拒绝时不保留任何引用。

nx_result_t nx_usb_control_out_prepare(nx_usb_control_request_t *request, uint8_t *bytes, size_t capacity, uint64_t epoch, nx_time_us_t deadline)¶

为需要显式审批的 OUT DATA 准备调用者存储。

备注

仅限 Task。已接受的字节持续被借用，直至 STATUS 完成或实际排空结束。DATA_READY 仅授予文档规定的 const 检查视图。

参数:

request – [inout] 已初始化且未被借用的请求。
bytes – [out] 稳定的可写 payload；准备期间不提前写入。
capacity – [in] 准入时必须覆盖匹配 SETUP 的 wLength。
epoch – [in] 非零 SETUP 身份。
deadline – [in] 独立的绝对 deadline，包含策略处理延迟。

返回:

成功、INVALID 或 STATE；begin 成功前不建立借用。

nx_result_t nx_usb_control_status_prepare(nx_usb_control_request_t *request, uint64_t epoch, nx_time_us_t deadline)¶

仅准备零数据请求的 status-IN 回复。

备注

仅限 Task。外部标准请求策略必须自行暂存 SET_ADDRESS，并在线上 ACK 后检查权威 address／closing 状态。

参数:

request – [inout] 已初始化且未被借用的请求。
epoch – [in] 非零且匹配的 SETUP 身份。
deadline – [in] 独立的绝对 deadline。

返回:

成功、INVALID 或 STATE；不启动传输。

nx_result_t nx_usb_control_begin(nx_usb_control_t *control, nx_usb_control_request_t *request)¶

为当前权威 SETUP epoch 准入一个显式回复。

备注

准入本身不提交包。payload、request、profile 和 adapter 必须保持有效，直到以 acquire 语义观察到 outer SETTLED。绝不能通过调用 prepare／重新初始化撤销借用。epoch 不重复。产品显式暂存 SET_ADDRESS；传输成功仅表示线上 ACK。

参数:

control – [inout] 已绑定的单执行者 adapter；不存在其他活动回复。
request – [inout] READY 元数据及与其不重叠的 payload。OUT 容量必须覆盖 wLength；IN 发送 min(length,wLength)，包含必要的 ZLP。

返回:

成功表示 ACCEPTED；任何失败均不保留 request 或 payload。

nx_result_t nx_usb_control_step(nx_usb_control_t *control)¶

推进一个有界步骤，至多进行一次 poll 和一次 packet 动作。

备注

不使用队列或 worker。所有 packet deadline 均使用 outer 独立的绝对单调 deadline。借用期间须持续 poll，即使已发生 cancel、reset、SETUP 替代或 device stop。cancel／drain／quarantine 均保留 descriptor 字节与 outer context。OUT0 quarantine 暴露 NEEDS_DEVICE_STOP；仅外部 controller owner 能授权 stop。该 adapter 绝不会自动停止共享 controller。在观察更新的 controller epoch 前，先折叠一个已 SETTLED 的 packet。

参数:

control – [inout] 同一个串行化执行者；沿用 begin 的生命周期要求。

返回:

成功或 provider 错误；错误绝不撤销已接受的存储借用。

nx_result_t nx_usb_control_cancel(nx_usb_control_t *control, nx_usb_control_request_t *request, uint64_t epoch)¶

请求取消，但不撤销旧 packet 或 outer 借用。

备注

已以 acquire 语义获取的 STATUS ACK 优先。下一步至多发出一次 packet cancel；须继续 poll，并保留 quarantine，直到实际撤回源。OUT0 恢复可能需要 device owner 显式执行 stop。

参数:

control – [inout] 同一个串行化特权 Task 执行者。
request – [inout] 精确的活动 outer request，保持有效直至 SETTLED。
epoch – [in] 精确的活动 SETUP 身份；不得跨 Task 使用原始指针。

返回:

成功时请求排空；STATE 无效果地拒绝过期身份。

nx_result_t nx_usb_control_out_view(const nx_usb_control_t *control, nx_usb_control_out_view_t *view)¶

在外部策略批准 STATUS 前检查已完成的 OUT DATA。

备注

视图在同一 owner 下一次调用 adapter 时失效。不得修改、释放或跨 Task 访问，也不隐含 status 确认。

参数:

control – [in] 处于 DATA_READY，且不存在 provider packet 引用。
view – [out] 不重叠的值输出；拒绝时保持原值。

返回:

成功仅授予 const 检查视图；outer 借用继续。

nx_result_t nx_usb_control_approve(nx_usb_control_t *control, uint64_t epoch, bool accepted)¶

在 STATUS IN 前批准 OUT 策略，或以有界 STALL 拒绝。

备注

字节、class 分派、configuration 就绪条件及恢复策略由外部负责。不提供 CDC／HID 栈。guard 保护的决定排除已由软件发布的替代 SETUP；尚未被 IRQ 采集的物理总线包不属于该软件 epoch 边界。取消须先排空，再结束 outer 借用。

参数:

control – [inout] 处于 DATA_READY、由同一 owner 管理的 adapter。
epoch – [in] 精确的活动 SETUP epoch，须根据新获取的状态检查。
accepted – [in] true 允许 status；false 对旧事务执行 STALL。

返回:

成功仅改变策略；下一次 step 才执行 packet／STALL。

nx_result_t nx_usb_control_snapshot(const nx_usb_control_t *control, nx_usb_control_snapshot_t *snapshot)¶

复制最近一次已获取的权威状态及 adapter 阶段。

备注

调用 step 刷新 controller 状态。线上成功不表示 address／configuration 已就绪。snapshot 绝不释放借用。

参数:

control – [in] 同一个单 Task 执行者；不执行 provider 操作。
snapshot – [out] 不重叠的值输出；拒绝时保持原值。

返回:

成功、INVALID 或 CONTEXT。

struct nx_usb_control_request_t¶

#include <usb_control.h>

公共成员

nx_request_t base¶

const uint8_t *in¶

uint8_t *out¶

size_t length¶

uint64_t setup_epoch¶

nx_usb_control_reply_kind_t kind¶

struct nx_usb_control_out_view_t¶

#include <usb_control.h>

公共成员

const uint8_t *bytes¶

size_t length¶

uint64_t setup_epoch¶

struct nx_usb_control_snapshot_t¶

#include <usb_control.h>

公共成员

nx_usb_device_state_t device¶

size_t confirmed_bytes¶

nx_usb_control_phase_t phase¶

bool outer_active¶

struct nx_usb_control_t¶

#include <usb_control.h>

由调用者拥有、容量固定的 adapter 私有字段。

备注

公共 context／request／output 元数据须按 C 类型自然对齐，且存储范围不得回绕。在 typed 访问前，未对齐地址即被判定为 INVALID。指针仍必须指向文档规定的可读／可写存储：数值检查无法验证任意地址映射或不透明的 provider 私有 context。

公共成员

const nx_usb_device_profile_t *profile¶

nx_usb_request_t packets[2]¶

nx_usb_control_request_t *active¶

nx_usb_device_state_t latest¶

nx_usb_setup_t setup¶

uint64_t completed_epoch¶

size_t goal¶

size_t confirmed_bytes¶

nx_result_t terminal¶

nx_usb_control_phase_t phase¶

bool borrowed[2]¶

bool cancel_sent[2]¶

bool cancel_pending¶

bool stall_pending¶

usb_descriptors.h¶

有界描述符视图；产品描述符字节仍由外部提供。

作者 Nexus Team

函数

nx_result_t nx_usb_descriptor_validate(const nx_usb_device_profile_t *profile, const nx_usb_descriptor_view_t *descriptor)¶

校验完整的 device、configuration 或 string 描述符字节。

备注

configuration 视图要求 alternate zero、与选定 bulk 或 interrupt IN 端口匹配的 endpoint 计划、一致的总长度及唯一的 interface 编号。interrupt bInterval 是外部 descriptor 字节中 full-speed 1 ms frame 的非零线性计数。bulk bInterval 不作解析，也不调度轮询。class-specific 从属字节仅检查边界，不作解码。class 分派、VID/PID、字符串、策略、CDC/HID 及 descriptor 查找仍由外部负责。成功仅表示结构校验通过，不表示枚举或物理资格。发送字节时，必须保持其有效，直到以 acquire 语义观察到 control adapter 的 outer SETTLED。view 结构体须按 C 类型自然对齐；拒绝机制不能用于探测任意地址。descriptor 字节仅需 byte alignment，且须保持外部可读。

参数:

profile – [in] 选定 FS endpoint 的不可变精确事实。
descriptor – [in] 完整的外部 descriptor；绝不复制或保留。

返回:

成功、INVALID 或 UNSUPPORTED；不产生硬件或输出效果。

struct nx_usb_descriptor_view_t¶

#include <usb_descriptors.h>

公共成员

const uint8_t *bytes¶

size_t length¶

user_io_broker.h¶

由内核调用的窄接口用户 GPIO 消息合同。

类型定义

typedef struct nx_user_io_broker nx_user_io_broker_t¶: broker 与持久内核调用存储保持提供者私有。

typedef struct nx_user_io_call nx_user_io_call_t¶

枚举

enum nx_user_io_constants¶

此消息 ABI 仅允许标量 GPIO 操作。

取值：

enumerator NX_USER_IO_ABI¶

enumerator NX_USER_GPIO_READ¶

enumerator NX_USER_GPIO_WRITE¶

函数

nx_user_io_result_t nx_user_io_broker_gpio(nx_user_io_broker_t *broker, nx_user_io_call_t *call, const nx_user_io_message_t *message, nx_user_io_reply_t *reply)¶

通过可信网关执行一个标量 GPIO 消息。

备注

由内核调用的特权 Thread，进入时屏蔽状态必须清除，只有一个串行 broker 执行者。principal 来自配置的可信内核身份接口。在调用任何 GPIO 前，必须固定两个已经验证的内存区间；输入只快照一次，复制已初始化的回复。内核调用存储在用户 RAM 外零初始化，其寿命必须覆盖保留的固定区间。该组件不提供 OS SVC/MPU/TZ 接线，也不提升用户权限。

返回:: REJECTED 表示 accepted=false，不保留固定区间，也不产生效果。ACCEPTED 可能已经分离，也可能在失败后继续保留清理责任。

nx_user_io_result_t nx_user_io_broker_gpio_finish(nx_user_io_broker_t *broker, nx_user_io_call_t *call)¶: 重试保留的清理，不读取用户存储或重放 I/O。

备注

同一特权串行内核所有者，进入时屏蔽状态必须清除。只有实际排空提供者和观测者后才能成功解除固定；解除固定失败时，内存、调用槽及身份继续保留。这不表示可以逆转先前已执行的 GPIO 写入。

struct nx_user_io_message_t¶

#include <user_io_broker.h>

来自不可信方的已复制消息；身份绝不取自用户输入。

备注

不接受任意接口、MMIO、回调、槽或 principal 指针。reserved 字必须为零。WRITE 要求 read_mask=0，且 set/reset 掩码不重叠。READ 要求 set/reset 掩码为零，并使用非零且已授权的 read_mask。网关完成前，或固定区间仍保留期间，调用者必须保持存储不可变。

公共成员

uint32_t abi¶

uint32_t device¶

uint32_t operation¶

uint32_t set_mask¶

uint32_t reset_mask¶

uint32_t read_mask¶

uint32_t reserved[2]¶

struct nx_user_io_reply_t¶

#include <user_io_broker.h>

完整初始化的复制结果；错误或 WRITE 时 value 为零。

公共成员

uint32_t result¶

uint32_t value¶

struct nx_user_io_result_t¶

#include <user_io_broker.h>

区分准入、保留清理责任与可能发生的效果。

备注

accepted 表示至少成功固定了一个内存区间。retained=true 时，精确的内核调用槽及用户地址空间继续被借用。device_effect_possible 在调用 WRITE 提供者前置位；出错不能授权重放。result 描述准入及器件执行结果；cleanup_result 独立描述最近一次释放尝试。这是软件责任，不是物理引脚证据。

公共成员

nx_result_t result¶

nx_result_t cleanup_result¶

bool accepted¶

bool retained¶

bool device_effect_possible¶

可选通用组件¶

字节传输、TLS 与 MQTT 装配¶

选定的 lwIP RX 负载借用¶

软件主机互通参考链路¶

byte_stream.h¶

lwip_adapter.h¶

lwip_loaned_rx.h¶

lwip_loaned_rx_storage.h¶

lwip_tcp.h¶

lwip_tcp_storage.h¶

tls.h¶

client.h¶

TMP117 单次采样合同¶

tmp117.h¶

tmp117_i2c.h¶

bmp280.h¶

bmp280_spi.h¶

bus_owner.h¶

clock_domain.h¶

dp83848.h¶

file_flash.h¶

flash_storage.h¶

log.h¶

modbus_rtu.h¶

owner_observer.h¶

settings.h¶

spi_async_owner.h¶

spi_owner.h¶

storage.h¶

uart_owner.h¶

usb_acm.h¶

usb_control.h¶

usb_descriptors.h¶

user_io_broker.h¶

Nexus Embedded Platform

导航