refactor(net): 单调时钟搬回时间模块,owner-only 入口补机器守卫

起因:104 适配层的 net 栈净增 5 个对外声明,其中 3 个是真新增。逐个查过:
net_pending_bytes / net_send_try 位置正确、不可替代(前者是 BSD FIONREAD 语义,
后者必须截到 NET_SEND_CHUNK_MAX 才不丢进度),保留不动;另外 2 个
net_accept_locked / net_drop_conn_locked 在更早的提交里只是把 static 去掉,
函数体一字未改,不是新函数。真正有问题的是三处:

一、net_mono_now_ms 放错层。这是"把 32 位 HAL_GetTick 扩成 64 位单调毫秒"的
时间工具,却挂在 socket 栈上。搬到 App/util/sys_clock,改名 sys_clock_mono_ms,
临界区保护读改写,零 NET 依赖(旧实现里的 owner 判定与非 owner 返回 0 语义
不再搬过来——时钟是纯读取,ABI 未要求)。

二、头注释把通用能力绑死到单个消费者。原文写"以下五个入口专供 netTask 内
IEC104 Net 后端使用",下一个读者要么不敢用、要么直接删掉。改写成通用
owner-only 能力描述,入口计数核准为 4。

三、两个 locked 函数没有任何 owner 校验,只在注释里写"必须在 netTask 上下文"。
而 net_accept_locked 函数体第一句就 net_poll() 跑真实 CH395F SPI 事务——别的
任务误调会与 netTask 抢同一根 SPI 总线,正是 TRAP-NET-14 的形态。两个函数头
各补 if (net_ctx_is_owner_task() == 0U) 守卫,非 owner 返回 NET_ERR_INVAL。

用户提出的关键疑问「项目里本来就有时间模块,用现成的不行吗」的答案是:
功能确实已搬进时间模块,但不能复用 sys_clock_get()。三条硬理由——
其一是单位,sys_clock_get() 内部整除 1000 返回 Unix 秒,而 104 退避常量
是毫秒级(TCP_SEND_RETRY_DELAY_MS = 10、TCP_ACCEPT_RETRY_DELAY_MS = 100),
拿秒比毫秒会把退避放大 1000 倍;其二是单调性,sys_clock_set() 第一句直接给
s_base_unix_secs 赋新值,SNTP 校时与 UI 改时都会调它,墙钟会跳变;其三是
语义,104 用 now_ms < at_ms 判退避是否到期,墙钟回拨会让重试长期不触发。
所以同一模块两个入口分工:sys_clock_get() 管墙钟 epoch 秒(可跳变,给日志
与文件时间戳),sys_clock_mono_ms() 管 64 位单调毫秒(只增不减,给定时器
与超时判定)。

测试:net_socket 677→683(新增 6 条守卫用例,删守卫变异必红)、
sys_clock 100→111(正常累加/回绕单调/不吞时间三类)、iec104_netmcu 13/13。
104 适配层改调 sys_clock_mono_ms 后,原先因旧函数被删而红的 netmcu runner
恢复全绿;host 侧新增 stub/sys_clock.h 替身(真头带 sd2506.h 依赖,主机编不了),
签名与真头逐字一致。

构建:0 Error(s), 0 Warning(s),Code 367584→367612(+28 B),RO/RW/ZI 全 0,
IRAM1 90.3%(阈值 92%)。+0 增量是符号级真抵消——sys_clock.o 新增
s_prev_lo/s_hi 共 8 B,net_socket.o 删掉同名两个 static 共 8 B。

文档:两份网络文档里 38 处写死的源码行号全部改成「文件路径 + 函数名」锚点
(那些行号本来就已随重构失效),owner 条目数 5→4;sys_clock 设计文档 §5
对外 API 表补 sys_clock_mono_ms 行,新增 §5.1 写清「墙钟 vs 单调:测超时该用
哪个」,§1 里「业务逻辑中基于真实时间的判定(定时、超时、调度等)」这句
会教人拿墙钟测超时的表述改成「墙钟不用于计时」。

门禁:net-handle 488 文件 0 违规 + selftest 42 条断言。
This commit is contained in:
2026-11-19 00:38:09 +08:00
parent dda30d9897
commit 1f51e8fa2f
24 changed files with 353 additions and 114 deletions
@@ -47,10 +47,10 @@ dhara 失败类 +84;RO 另 +208,全是该失败类名表)→ `ER_IROM1`
<!-- MEM_SNAPSHOT:BEGIN generated by scripts/check_mem_numbers.py -->
| 区域 | 用量 | 容量 | 占比 |
|---|---|---|---|
| ER_IROM1 | 416,188 B (406.43 KB) | 1,048,576 B (1024 KB) | 39.7% |
| ER_IROM1 | 416,216 B (406.46 KB) | 1,048,576 B (1024 KB) | 39.7% |
| RW_IRAM1 | 118,416 B (115.64 KB) | 131,072 B (128 KB) | 90.3% |
| RW_CCM | 57,376 B (56.03 KB) | 65,280 B (64 KB) | 87.9% |
| **Flash (ROM 合计)** | **418,924 B (409.1 KB)** | 1,048,576 B (1024 KB) | **40.0%** |
| **Flash (ROM 合计)** | **418,952 B (409.1 KB)** | 1,048,576 B (1024 KB) | **40.0%** |
<!-- MEM_SNAPSHOT:END -->
各区的容量与常量来源:
+3 -3
View File
@@ -15,18 +15,18 @@
<!-- MEM_BUDGET:BEGIN generated by scripts/ram_baseline.py -->
| 区域 | 用量 | 容量 | 占比 | 门禁(≤92%) |
|---|---|---|---|---|
| ER_IROM1 (Flash) | 416,188 B | 1,048,576 B | 39.7% | 参考 |
| ER_IROM1 (Flash) | 416,216 B | 1,048,576 B | 39.7% | 参考 |
| RW_CCM | 57,376 B | 65,280 B | 87.9% | PASS |
| UNINIT_CCM | 48 B | 256 B | 18.8% | 参考 |
| RW_IRAM1 | 118,416 B | 131,072 B | 90.3% | PASS |
| 子系统(静态 RW+ZI;除 RTOS 堆在 CCM 外均在 SRAM1) | 现值 | 配额 | 状态 |
|---|---|---|---|
| 网络 | 13,966 B | 12 KB | ⚠ 超 1.6 KB |
| 网络 | 13,958 B | 12 KB | ⚠ 超 1.6 KB |
| 存储 | 9,144 B | 12 KB | OK |
| UI | 36,791 B | 16 KB | ⚠ 超 19.9 KB |
| RTOS 堆 | 57,376 B | 56 KB | 堆=配额 |
| 应用 | 47,699 B | 8 KB | ⚠ 超 38.6 KB |
| 应用 | 47,707 B | 8 KB | ⚠ 超 38.6 KB |
| 其它 | 10,797 B | — | 参考 |
<!-- MEM_BUDGET:END -->
@@ -13,9 +13,12 @@
- 日志/调试信息打时间戳;
- 文件系统的文件创建/修改时间(FatFS 需要);
- 业务逻辑中基于真实时间的判定(定时、超时、调度等);
- 对外接口(如 FTP `LIST` 返回的文件时间、SNTP/NTP 校时等)。
**墙钟不用于计时。** 定时、超时、退避调度这类"过了多久"的判定必须用单调时钟
`sys_clock_mono_ms()`(毫秒、只增不减),**不能用墙钟 `sys_clock_get()`**——后者会被
校时跳变、且单位是秒。两类时间的选择依据见 §5.1。
本模块在 **SD2506 硬件 RTC(掉电保持)** 与 **HAL 系统节拍(运行期计时)** 之间做桥接:
- 启动时从 SD2506 读取一次真实时间,换算为 Unix 时间戳,建立"墙钟基准";
@@ -108,6 +111,35 @@ static volatile uint32_t s_base_unix_secs = UINT32_MAX; /* 基准对应的 Unix
| `uint32_t sys_clock_get(void)` | 获取当前 Unix 时间戳(秒) | 当前秒数;未初始化返回 `UINT32_MAX` | `sys_clock_init()` 已调用 |
| `char *sys_clock_get_str(char *buf, size_t buf_size)` | 获取格式化字符串 `YYYY-MM-DD HH:MM:SS` | `buf` 指针;未初始化输出 `----/--/-- --:--:--` | `buf` 有效且 `buf_size ≥ 20` |
| `int sys_clock_set(uint32_t unix_secs, const sd2506_time_t *sd_time)` | 更新基准,可写回 SD2506 | `0`(始终成功) | `unix_secs` 为合法时间戳 |
| `uint64_t sys_clock_mono_ms(void)` | 64 位单调毫秒(32 位 `HAL_GetTick()` 的宽扩展),跨 tick 回绕不回退;用于定时/超时/退避判定 | 64 位单调毫秒,跨回绕只增不减 | 任意任务上下文可调用;**禁止中断上下文**(内部 `taskENTER_CRITICAL()` 在 ISR 不成立);调用方须至少每 49.7 天调用一次 |
> 表中 `sys_clock_mono_ms()` 的签名直接取自 `App/util/sys_clock.h` 的声明(表格内省略语句末尾分号,
> 与其余各行风格相同)。它于 2026-11-18 从网络层迁入本模块(原为
> `Drivers/BSP/NET/net_socket.c` 的 `net_mono_now_ms`),现已不依赖任何网络接口。
### 5.1 墙钟 vs 单调:测超时该用哪个
**这一节回答"我要取时间时该用哪个入口"——先分清两类时间,选错会让超时判定静默失效。**
本模块提供两类时间,职责不重叠:
| 时间类型 | 入口 | 单位与范围 | 会被校时跳变吗 | 该用于什么 |
|---|---|---|---|---|
| 墙钟(日历时间) | `sys_clock_get()` | Unix epoch **秒**,`uint32_t` | **会**——`sys_clock_set()` 直接改基准,SNTP 校时与 UI 改时都会调用它 | 日志/文件时间戳、日历显示、对外时间字段 |
| 单调时钟 | `sys_clock_mono_ms()` | **毫秒**,`uint64_t`,只增不减 | 不会——只基于 `HAL_GetTick()`,不读 RTC 基准 | 定时器、超时、退避调度等"过了多久"的判定 |
**测超时、计间隔一律用 `sys_clock_mono_ms()`,不能用 `sys_clock_get()` 顶替。** 三条硬理由:
1. **单位不对**:`sys_clock_get()` 内部整除 1000 返回秒;而 IEC 60870-5-104 的退避常量是毫秒级
(`IEC104_TcpServer.c` 的 `TCP_SEND_RETRY_DELAY_MS` = 10、`TCP_ACCEPT_RETRY_DELAY_MS` = 100)。
拿秒去比较毫秒期限,会把退避放大 1000 倍。
2. **会被校时跳变**:`sys_clock_get()` 的基准由 `sys_clock_set()` 直接赋值改写,调用方包括
SNTP 校时(`App/sync/time_sntp.c`)与 UI 手工改时(`App/task/ui_task.c`)。校时回拨时墙钟倒退。
3. **语义会被破坏**:104 的重试用 `now_ms < at_ms` 判退避是否到期
(`IEC104_TcpServer.c` 的 `Send_Retry_Paused()` / `Accept_Retry_Paused()`)。若用可回拨的墙钟,
回拨后 `now_ms` 长期小于 `at_ms`,**重试会长期不触发**;单调时钟只增不减就没这个问题。
> 单调时钟的回绕前提(两次调用间隔不足一圈、约 49.7 天)与禁止中断上下文的约束见上表与
> `App/util/sys_clock.h` 的函数头注释。本仓调用者是 netTask 的 1 ms 主循环(104 tick),IWDG 兜底。
> `sys_clock_init()` 返回 `-1` 表示 RTC 芯片不可用:`RTC_DEFAULT_INIT_ENABLE=1` 时墙钟降级为编译期默认时间基准(日志时间戳仍有效),`app_main` 记录"时钟芯片异常"自检;禁用时墙钟保持"未初始化"(各取时接口返回无效哨兵)。`sys_clock_set()` 只更新基准(写回 RTC 尽力而为),恒返回 `0`。
@@ -267,7 +299,8 @@ sys_clock_init(); /* 再建立墙钟基准:所有后续日志即带正确时
char ts[24];
DBG_INFO("now: %s", sys_clock_get_str(ts, sizeof(ts)));
uint32_t now = sys_clock_get(); /* Unix 秒,可用于 FatFS 文件时间、超时判定等 */
uint32_t now = sys_clock_get(); /* Unix 秒,用于 FatFS 文件时间等日历场景;
测超时/计间隔请用 sys_clock_mono_ms(),见 §5.1 */
```
---
+34 -26
View File
@@ -9,8 +9,8 @@
成熟库按 **Windows/Winsock 式的"独立 client fd"** 设计:监听 socket 与接入后的数据 socket
是两个不同句柄,因此 `Accept` 失败清理、以及"已有客户端时又来一个"的分支,一律
`IEC104_Net_Close(client, NULL)`——`App/protocol/iec60870/104/IEC104_TcpServer.c` 里共 **7 处**
(约 1606 / 1611 / 1616 / 1628 / 1636 / 1652 / 1665 行)。在 Winsock 下这让两侧各自独立,语义自洽。
`IEC104_Net_Close(client, NULL)`——`App/protocol/iec60870/104/IEC104_TcpServer.c` 的 `Accept_Clients()` 内共 **7 处**
(按源码顺序集中在同函数中)。在 Winsock 下这让两侧各自独立,语义自洽。
CH395F 是**单连接模型**:`net_accept()` 返回的是**监听 socket 自己**,接入瞬间同一个 fd 从
"监听"变成"数据通道"(见 `docs/网络/BSD_Socket_API_使用指南.md` §2.3 的 fd 模型对照表)。
@@ -47,9 +47,10 @@ LISTEN 分支还有一个顺序约束:若此时仍存在客户端槽,**先
## 3. 双句柄模型:LISTEN 恒定,CLIENT 每次 Accept 新建
库内 `server->listen_socket` 在 `IEC104_TcpServer.c` 里**只被赋值一次**(Listen 成功时,约
2129 行),此后在 Accept、Wait、事件匹配等多处使用(约 1579 / 1782 / 1874 / 1983 行),
**整个监听生命周期内永不更新**。因此:
库内 `server->listen_socket` 在 `IEC104_TcpServer.c` 的 `IEC104_TcpServer_Init()` 里**只被赋值一次**
(Listen 成功时),此后在 `Accept_Clients()` / `Wait_For_Events()` / `Process_Events()` 等多处使用,
**整个监听生命周期内永不更新**;置无效只发生在 `Reset_Server()`、`IEC104_TcpServer_Init()` 的失败清理与
`IEC104_TcpServer_Close()` 收尾。因此:
- **LISTEN 槽**:`handle` 在监听生命周期内**不变**,`role` 恒为 `SLOT_LISTEN`。
**绝不翻转监听槽的 role**,否则库的 `Close(listen)` / `Wait(ACCEPT)` 会失联。
@@ -84,15 +85,24 @@ Listen 发的")。因此不能靠句柄内嵌校验,只能靠**值本身不
表容量等于 net 层 fd 上限(`NET_MAX_SOCKETS` = 8)。N6 是这条的反例自证:连续多次
listen/close 后旧 handle 必然查表失败。
## 6. 编译期边界:5 个 MCU 专有接口模拟器看不到
## 6. 编译期边界:4 个 owner-only 入口模拟器看不到
后端需要的 5 个 owner 出口声明在 `net_socket.h` 的 `#ifndef NET_NO_OS` … `#endif` 段内
(约 702–809 行):`net_drop_conn_locked`、`net_accept_locked`、`net_pending_bytes`、
`net_send_try`、`net_mono_now_ms`。**模拟器定义 `NET_NO_OS`,因此看不到它们**——
这一节回答"哪些 net 接口只有 MCU 能用、为什么模拟器必须走替身"——定位靠门控宏与函数名,不靠行号。
后端需要的 **4 个 owner-only 入口**声明在 `net_socket.h` 的 `#ifndef NET_NO_OS` … `#endif` 段内:
`net_drop_conn_locked` / `net_accept_locked` / `net_pending_bytes` / `net_send_try`。它们不经过
`netMsgQueue`,在 netTask 上下文调用即执行、绝不等待。原先另有一个单调毫秒入口挂在 net 栈上,
现已从 net 栈删除并**迁出**:功能搬迁到 `App/util/sys_clock.h` 的 `sys_clock_mono_ms()`,
由 `App/protocol/iec104/iec104_net_mcu.c` 的 `IEC104_Net_Now_Ms()` 直接调用(纯读取、无 owner 保护)。
**模拟器定义 `NET_NO_OS`,看不到这四个声明**——
这也正是 `iec104_net_mcu.c` 只进 MCU 构建、模拟器由 `sim/iec104_sim.c` 提供同 ABI 替身的原因。
**owner 约束已有机器表达(不再只是文档约定)**:`net_accept_locked` 与 `net_drop_conn_locked`
的函数体开头都先判 `net_ctx_is_owner_task()`,非 owner 立即返回 `NET_ERR_INVAL`(在任何 SPI 事务之前),
因此"必须在 netTask 上下文调用"由代码守卫而非注释保证。
**已知一致性缺口**:头文件有 `NET_NO_OS` 门控,但 `net_socket.c` 里 `NET_NO_OS` 零命中——
5 个实现**无条件编译**。当前不构成故障(模拟器不编 `net_socket.c`),但如果将来把
4 个实现**无条件编译**。当前不构成故障(模拟器不编 `net_socket.c`),但如果将来把
`net_socket.c` 编进模拟器,会得到"实现存在但未声明"的孤儿符号:**链接不报错、
调用处静默走空**。改这一块之前必须先把这个不对称补齐。
@@ -111,24 +121,22 @@ listen/close 后旧 handle 必然查表失败。
---
## 附:源码行号索引(以 2026-11-17 本工作树为准)
## 附:源码定位索引(按函数名,不写行号)
> `net_socket.c` / `net_socket.h` 的行号会随改动漂移(同一天已经漂过两次)。
> **正文一律用函数名指代,行号只在此处集中登记**,引用时请重新 grep 核对。
这一节回答"正文提到的符号在哪个文件的哪个函数里"——项目文档规范禁止写死源码行号,
定位一律用 `文件路径 + 函数名`;同一事实正文已有详述的,这里只给检索坐标。
| 符号 / 事实 | 位置 |
| 符号 / 事实 | 定位(文件路径 + 函数名) |
|---|---|
| `net_wait_result()` 定义 | `Drivers/BSP/NET/net_socket.c:930` |
| 其阻塞点 `xTaskNotifyWait(..., portMAX_DELAY)` | `net_socket.c:945`(`:939` 是零等待那一次,不是阻塞点) |
| 公开 `net_close` / `net_drop_conn`(无 owner 分支) | `net_socket.c:2515` / `:2574` |
| `net_close_locked`(static,非对外接口) | `net_socket.c:2098` |
| `net_drop_conn_locked`(owner 出口,拆会话保监听) | `net_socket.c:2174` |
| `net_close_sock`(owner 出口,关单个 socket) | `net_socket.c:3041` |
| `net_init` 内 `memset(s_net_socks, ...)` / `ch395f_reset()` | `net_socket.c:337` / `:351` |
| 5 个新声明所在的 `#ifndef NET_NO_OS` 段 | `net_socket.h:702` ~ `:809` |
| `net_drop_conn_locked` / `net_accept_locked` 声明 | `net_socket.h:769` / `:770` |
| `net_pending_bytes` / `net_send_try` / `net_mono_now_ms` 声明 | `net_socket.h:777` / `:785` / `:792` |
| `net_wait_result()` 两段等待(零等待拾取 + `xTaskNotifyWait` 阻塞) | `Drivers/BSP/NET/net_socket.c` 的 `net_wait_result()` |
| 公开 API 的 `osMessageQueuePut(..., osWaitForever)`(12 处) | 同文件 `net_bind()` / `net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_recv_to()` / `net_close()` / `net_drop_conn()` / `net_udp_set_peer()` / `net_udp_get_mode()` |
| `net_close_locked`(static,非对外接口)/ 对外版 | 同文件 `net_close_locked()` / `net_close()` |
| `net_drop_conn_locked`(owner 出口,拆会话保监听)/ 公开版 | 同文件 `net_drop_conn_locked()` / `net_drop_conn()` |
| `net_close_sock`(owner 出口,关单个 socket) | 同文件 `net_close_sock()` |
| `net_init` 里 `memset(s_net_socks, ...)` 与 `ch395f_reset()` | 同文件 `net_init()` |
| 4 个 owner-only 声明所在 `#ifndef NET_NO_OS` 段 | `Drivers/BSP/NET/net_socket.h` 的 `NET_NO_OS` 段(声明 `net_drop_conn_locked` / `net_accept_locked` / `net_pending_bytes` / `net_send_try`) |
| 后端的 LISTEN / CLIENT 分流 | `App/protocol/iec104/iec104_net_mcu.c` 的 `IEC104_Net_Close()` |
| 后端的 role 查表 | 同文件 `find_role()` / `slot_by_handle()` |
| 7 处 `IEC104_Net_Close(client, NULL)` | `App/protocol/iec60870/104/IEC104_TcpServer.c` 约 1606/1611/1616/1628/1636/1652/1665 |
| `server->listen_socket` 赋值点 | 同文件 `:2129`(Listen 成功)/ `:322`、`:2146`、`:3322`(置无效) |
| 单调毫秒时钟(已迁出 net 栈) | `App/util/sys_clock.h` 的 `sys_clock_mono_ms()`;调用方 `App/protocol/iec104/iec104_net_mcu.c` 的 `IEC104_Net_Now_Ms()` |
| 7 处 `IEC104_Net_Close(client, NULL)` | `App/protocol/iec60870/104/IEC104_TcpServer.c` 的 `Accept_Clients()` |
| `server->listen_socket` 赋值 / 置无效 | 同文件 `IEC104_TcpServer_Init()`(Listen 成功)/ `Reset_Server()` / `IEC104_TcpServer_Init()` 失败清理 / `IEC104_TcpServer_Close()` 收尾 |
@@ -538,7 +538,13 @@ net_pending_capture_owner() ← 捕获执行者
- 清除掩码必须全 1(传 0 = 不清除,会残留上次结果被误读为本次结果);
- **禁止在本路径加逐调用日志**——该路径每条 API 调用都过一遍,会淹没排查用的证据日志。
**源码定位与 netTask 内调用边界**(板端割接实测,`Drivers/BSP/NET/net_socket.c`):`net_wait_result()` 定义在 `:930`,真正阻塞的是 `:945` 的 `xTaskNotifyWait(0xFFFFFFFFU, 0xFFFFFFFFU, &v, portMAX_DELAY)`;`:939` 的零等待那次是防丢通知的第一段,不是阻塞点。`net_send()` 本体的入队在 `:2289`(紧接 `:2297` 调 `net_wait_result("snd")`);全文件 `osMessageQueuePut(..., osWaitForever)` 共 12 处(`:1086` / `:1313` / `:1480` / `:1650` / `:2289` / `:2370` / `:2472` / `:2541` / `:2600` / `:2718` / `:2852` / `:2973`),即公开 `net_*` 入队一律无上界等待。公开版 `net_close`(`:2515`)、`net_drop_conn`(`:2574`)没有 owner 上下文分支,在 netTask 内调用就是等自己的回执而死锁;netTask 内要关单个 socket 用 `net_close_sock(net_sock_t *)`(`:3041`),要拆会话保留监听用 `net_drop_conn_locked(net_sock_t *)`(`:2174`)——不存在名为 `net_close_locked` 的对外接口,它只是 `net_close` 内部的 static 实现。本轮新增的 5 个声明 `net_drop_conn_locked`(`:769`)、`net_accept_locked`(`:770`)、`net_pending_bytes`(`:777`)、`net_send_try`(`:785`)、`net_mono_now_ms`(`:792`)都位于 `net_socket.h` 的 `:702` `#ifndef NET_NO_OS` … `:809` `#endif` 段内,模拟器(定义 `NET_NO_OS`)看不到它们。所以在 netTask 内写非阻塞代码时,凡 `net_*` 都要先问它内部是不是 `osWaitForever`。
**源码定位与 netTask 内调用边界**(板端割接实测)。这一小节回答"在 netTask 内部写代码时哪些 `net_*` 能直接调、哪些会自等死锁"——判断依据是函数在什么层,不是记行号;下面所有定位都用 `文件路径 + 函数名`。
- **两段式等待**:`Drivers/BSP/NET/net_socket.c` 的 `net_wait_result()` 先做一次零等待拾取(防"入队 → 等待入口"间隙丢通知),第二段 `xTaskNotifyWait(0xFFFFFFFFU, 0xFFFFFFFFU, &v, portMAX_DELAY)` 才是真正阻塞点;两段不可互换,且判据必须用 `pdTRUE`/`pdFALSE`,不能判值 ≠ 0(`0 = EOF` 是合法通知)。
- **公开 API 一律无上界入队**:同一文件 `osMessageQueuePut(..., osWaitForever)` 共 12 处,分布在 `net_bind()` / `net_listen()` / `net_accept()` / `net_connect()` / `net_send()` / `net_recv()` / `net_recv_to()` / `net_close()` / `net_drop_conn()`(两处)/ `net_udp_set_peer()` / `net_udp_get_mode()`。其中 `net_send()` 本体入队后紧接着调 `net_wait_result("snd")`。这些入口在 netTask 内调用就是等自己的回执而死锁。
- **netTask 内该用什么**:关单个 socket 用 `net_close_sock(net_sock_t *)`;拆会话保留监听用 `net_drop_conn_locked(net_sock_t *)`;`net_close_locked` 只是 `net_close()` 内部的 static 实现,不存在同名对外接口。
- **owner-only 入口(4 个,均在 `Drivers/BSP/NET/net_socket.h` 的 `#ifndef NET_NO_OS` … `#endif` 段内)**:`net_drop_conn_locked` / `net_accept_locked` / `net_pending_bytes` / `net_send_try`——不经过 `netMsgQueue`,调用即执行、绝不等待;模拟器定义 `NET_NO_OS`,看不到这些声明。原先另有一个单调毫秒入口挂在 net 栈上,现已从 net 栈删除并**迁出**:现由 `App/util/sys_clock.h` 的 `sys_clock_mono_ms()` 提供,不再是 net 栈声明面。
- **owner 约束已有机器表达**:`net_accept_locked()` 与 `net_drop_conn_locked()` 的函数体开头都有 `if (net_ctx_is_owner_task() == 0U) { return NET_ERR_RETURN_1(NET_ERR_INVAL); }`,位于任何 SPI 事务之前。非 owner 任务误调立即拿到 `NET_ERR_INVAL`,不再只是文档里"必须在 netTask 上下文调用"的约定。
**13. 发送有界自旋**(`net_send_locked`):两个等待循环都在 `net_poll()` 之后判预算,
**判定顺序不可交换**: