Translation pending. This page is currently available in Chinese.
集群传输适配器¶
三个适配器共用 a20_clx_transport_t:send 拷贝/发送一个完整帧,poll推进有界 I/O,session 返回直连对端协商结果。驱动不能把下一跳网关的会话当作最终目的节点的会话。node_id=NULL 只查询邻接会话,供核心验证下一跳 RELAY;可靠间接目的由 CS 双向挑战确认(参见 02-wire-protocol.md)。
1. 传输合同¶
send返回 0 或负错误,不能在返回后保留调用方帧指针。- RX 通过
a20_clx_rx_frame提交拥有独立副本的帧,长度先检查再分配,成功入队后在锁外唤醒 RX 等待者;满队列/分配失败不发布伪事件。 - POLLING 由独立核心线程执行,单轮有工作预算;UDP socket 就绪可提前唤醒,空闲等待最多 1 ms。共同 RX ring 达到 32 项时等待空间,降至 31 项唤醒;某 adapter 连续 100 ms 未获轮询时,仍给它一次有界轮询机会,推进 UART 泵与心跳控制。满 ring 仍可能拒绝业务帧,由可靠层重试。socket 在等待前持有独立引用,关闭/失败/超时均释放,不嵌套 socket 锁与调度锁。
- 链路 UP 只能来自握手/有效存活证据,不能把 send 成功当作对端存活。
- 链路 DOWN 取消所有经该下一跳到达的代理,包括下游路由。
- 只有 RELAY 角色可转发;逐跳递减 TTL、重新计算 CRC,保留原始事务字段。
- 出口 MTU 较小时不能静默截断。v1 完整 UDP 路径可协商端到端分片;未协商或转发片超出出口预算时拒绝,由有界调用结束。
| id | 传输 | next_hop | 帧 MTU |
|---|---|---|---|
| 0 | loopback | 4 B 虚拟节点号 | 65536 |
| 1 | UDP/IPv4 | IPv4 4 B + 网络序端口 2 B | 1472 |
| 2 | UART | 小端短地址 2 B | 256 |
2. loopback¶
用于本机身份与测试虚拟节点。虚拟节点共享同一内核导出表,不能作为独立节点数量、网络可用性或故障隔离证据。默认无丢包;历史测试钩子仍可注入异常。真正跨内核的验收使用 tools/cluster/check-cluster-udp.py。
3. UDP/IPv4¶
配置路由时惰性启动非阻塞 datagram socket,默认本地端口 44020;引导参数clxport=N 可指定其他端口,必须为 1–65535。例:目的 10.0.3.3:44020 的 next_hop 为 {10, 0, 3, 3, 0xab, 0xf4},不使用宿主机本地字节序整数。
配置线程只临时持有 fd。适配器保留 vfile 引用并关闭临时 fd,后续 poll/send 使用 socket 对象接口,因此配置进程退出不破坏链路。
只接收已配置链路地址。HELLO 必须匹配预期完整 node_id、源哈希、地址长度和能力/版本约束。新会话必须回答本方新 challenge 才能被采用,旧 HELLO_ACK 不会把会话回退。非直连来源只有经声明 RELAY 的 peer 才允许提交到核心。
每轮最多收 16 个 datagram。心跳周期 1 s,3 s 无有效接收进入 SUSPECT,6 s 进入 DOWN,随后继续 HELLO。Native 汇总状态已同步 UDP SUSPECT;RTT 细节尚未完整暴露,不能把它当作已完成的性能观测。
心跳轮询通过占用位图访问已配置 peer,不再逐项锁定整个容量表。 peer 初始化与置位、删除与清位均由 g_udp_lock 同步;轮询在锁内复制位图,逐项读取前重新检查 used,之后才在锁外发送控制帧。快照后新占用的槽位最迟在下一次轮询参与;快照槽位若在锁内读取前已被删除,则跳过。槽位复用可在当次轮询中处理新 peer,仍使用锁内读到的完整新记录。解锁之后的配置变更不会撤回已经取出的控制帧快照;该规则不改变原有锁外 I/O、心跳时间和会话协议。
位图按 ceil(route_capacity/64) 个 u64 分配:DEFAULT 档增加 32 B BSS 和 32 B 轮询局部数组,SERVER 档各 512 B;这不是函数全部栈用量。静态 MCU leaf 不编译主机 UDP 适配器。配置/删除和其他 peer 查询仍有全表扫描,这项优化没有消除整个集群的所有容量相关开销。
python3 tools/cluster/check-cluster-udp-peers.py 提取生产 peer 类型、添加/删除和轮询函数执行,验证稀疏/满表、非 64 对齐容量、删加交错、别名保留、容量耗尽、槽位复用、3/6 秒心跳边界和每档 10000 次变更,启用 ASan/UBSan。该入口已纳入 check-cluster-unit;它验证状态与锁访问预算,不替代真实网络、SMP 或物理 MCU 测试。
同一 UDP 下一跳可以承载多条下游路由:先安装网关自身路由,再安装经它转发的目的路由。适配器保留网关直连身份,不用下游身份覆盖它。
4. UART 主节点¶
板级代码通过 a20_clx_uart_link_register 提供 getc、putc、本机身份、短地址及角色能力。可提供明确 boot session;没有提供时使用启动时混合值,量产部署仍需板级持久 epoch 或可靠熵来源。x86 COM2 板级绑定已接入内核串口驱动与测试验证。
SLIP 使用头/尾 END,转义 END 和 ESC;CRC 强制开启,帧 MTU 256。 50 ms 字节间超时丢弃半帧。每链路发送队列为 4 帧,只有 poll 写字节,控制帧和 CALL 不会互相穿插。主节点每轮最多读取 128 字节。
HELLO 由主节点引导;v1 双方通过当前 challenge 的 ACK 确认对端会话,叶子完成确认后采用短地址。注销 UP 链路也发 DOWN 以取消代理。5 s PING,连续 3 次未应答进入 SUSPECT,再 3 次进入 DOWN。首次漏掉 PONG 时先尝试新的 HELLO 挑战,让重启的被动 leaf 提前恢复。确认不同启动 epoch 后原代理需重建。
5. MCU 叶子¶
kernel/mcu/leaf.c 使用静态 RX/TX 缓冲和一个有界回复缓存,单轮最多收 64 字节。专用集群固件有独立的 1 ms 泵;受限 QEMU MCU 探针默认不携带完整 leaf,可显式开启测试配置。
叶子支持 v0 单帧调用,双方协商 v1 后支持相同的会话前缀、序号窗口、回复重放与完成收据。单回复缓存满且未获收据时明确拒绝新请求,不能提前覆盖仍可能需要重放的结果。叶子当前无分片、广播和任意进程执行能力。
默认演示身份不能用于多板部署。必须在握手前通过 identity 配置安装不同的持久 node_id;STM32 集群固件使用 UID 与持久 boot epoch journal。经 RELAY 到达的调用者有 8 个固定来源槽位及独立窗口,共用单回复缓存。 50 s 无 PING 使叶子断开并作废短地址。可在首次握手前安装一个静态 SEND 接收器,按相同会话、窗口和收据规则接纳最多 206 B 输入,不增加重组或任意进程能力;参见 02-wire-protocol.md 及 10-operator-guide.md。
6. 证据边界¶
test_clx_uart_pair.c 同时运行实际 uart.c 与 leaf.c,只替换板级字节 I/O、时钟和锁,验证握手、共享算子、重放、缓存满、旧会话与重连。它是生产协议的主机仿真,不是物理串口或真实 MCU 性能测试。 STM32 固件成功链接也不等价于硬件运行成功。
STM32 的 UID 与持久 boot epoch 已从生产 main 接入,配置失败禁用 leaf; journal、Flash 保留区和物理证据边界参见 MCU 共享内存内核规范。
STM32 部署使用 STM32_CLUSTER_PORT=2/3 独立集群固件:专用 USART⅔ 原始字节流、512 B IRQ 环、独立 1 ms 协议泵。原外设固件默认不启用 leaf,控制台 USART1 不参与二进制帧收发。配置、持久身份和实际资源参见 MCU 共享内存内核规范。