Files
STM32F4-Base/App/util/README.md
T
wandering1 1f51e8fa2f 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 条断言。
2026-11-19 00:38:09 +08:00

41 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# App/util/ — 通用工具函数
> 平台无关的纯工具模块(无 FreeRTOS 依赖、无硬件依赖),可在 MCU 与 PC 模拟器中共用。
## 文件一览
| 文件 | 作用 |
|---|---|
| `sys_clock.c/h` | **墙钟时间管理**:RTC 基准、tick 回绕防护、每 30 天惰性再基准化 |
| `task_watchdog.c/h` | **独立看门狗(IWDG)判定状态机**:任务心跳位图 + defaultTask 单一喂狗者 |
> **已删除(2026-10-02)**:`crc.c/h`(CRC-16 Modbus / CRC-8)与 `ringbuf.c/h`(SPSC 环形缓冲)
> 两模块**零调用者**且未编入任何构建——CRC 从未被链接使用:名义上的关联点 `net_cfg_legacy.c`
> (旧档迁移,**该文件亦已于 2026-10-10 删除**)自带静态 `s_crc16_modbus()`,
> 从不调用本模块;环形缓冲由 `App/log/console_log.c` 内联实现(`s_con_ring`)。
> 保留只会造成"有统一实现"的误导,故整体移除。
## 设计要点
### sys_clock
- 以 SD2506 RTC 为基准,HAL tick 计数补齐亚秒精度
- **49.7 天 tick 回绕防护**:每 30 天惰性再基准化(`sys_clock_get` 内部触发)
- **64 位单调毫秒**:`sys_clock_mono_ms()` 把 32 位 `HAL_GetTick()` 扩成跨 `0xFFFFFFFF` 不回退的 64 位单调时钟,临界区保护、任意任务上下文可调(**禁 ISR**),无网络层依赖;自 2026-11-18 起取代 net 栈上的旧 `net_mono_now_ms`
- RTC 故障时降级到默认时间基准并返回 -1,触发"时钟芯片异常"自检上报
- 设计详见 `docs/子系统设计/系统墙钟时间维护说明.md`
### task_watchdog
- **任务心跳位图**:各任务只置位(`task_wd_beat`),校验者取走并清零(单字原子,无锁)
- **单一喂狗者**:`defaultTask` 每 100 ms 抽样判定,仅当位图等于必需掩码时才喂狗
- **硬件访问收敛**:`IWDG` 寄存器与 `HAL_GetTick()` 经 `wd_platform_*` 弱钩子访问
(声明在 `task_watchdog.h` 末段),MCU 端为 `__weak` 默认实现,主机侧单测以同名强符号覆盖 → 可在 PC 上跑纯逻辑回归
- 设计详见 `docs/子系统设计/看门狗设计说明.md`;单测见 `docs/测试说明/单元测试/看门狗单元测试说明.md`
## 相关文档
- `docs/子系统设计/系统墙钟时间维护说明.md`
- `docs/子系统设计/看门狗设计说明.md`
- `docs/测试说明/单元测试/看门狗单元测试说明.md`