Files
STM32F4-Base/App/util/sys_clock.h
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

105 lines
4.3 KiB
C
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.
/*
* 模块名称:System Clock — Wall Clock Time Maintenance
* 模块功能:基于 HAL Tick + SD2506 RTC 的系统墙钟时间维护
* 启动时从 SD2506 RTC 读取初始时间,运行期间以 HAL Tick 计数维持
* 适用平台:STM32F407ZGTx (Cortex-M4 FPU, 168MHz)
* 作者:王建锋
* 创建日期:2026-07-19
* 修改记录:
* v1.0 2026-07-19 王建锋 创建初始版本
* v1.1 2026-09-13 王建锋 新增 sys_clock_get_time()(日历时间获取器,供 FatFs 时间钩子等使用)
* v1.2 2026-09-13 王建锋 文件移入 App/util/(改归 ④中间件层:通用平台时间服务,多服务共用)
*/
#ifndef SYS_CLOCK_H
#define SYS_CLOCK_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
#include "sd2506.h"
/*
* 函数功能:系统时钟初始化(从 SD2506 RTC 读取初始时间)
* 入口参数:无
* 返回值:0 - 成功, -1 - 失败
* 限定条件:sd2506_init() 已调用
* 函数说明:读取 SD2506 RTC 当前值转换为 Unix timestamp,设为系统墙钟初始时间
*/
int sys_clock_init(void);
/*
* 函数功能:获取当前系统墙钟时间(Unix epoch seconds)
* 入口参数:无
* 返回值:Unix time (秒),失败返回 UINT32_MAX
* 限定条件:sys_clock_init() 已调用
* 函数说明:基于 HAL Tick 计数 + 上次校准时刻的 Unix 秒数计算当前时间,
* 精度为毫秒级
*/
uint32_t sys_clock_get(void);
/*
* 函数功能:64 位单调毫秒(32 位 HAL_GetTick 的宽扩展)
* 入口参数:无
* 返回值:64 位单调毫秒,跨 HAL_GetTick 的 0xFFFFFFFF -> 0 回绕不回退
* 限定条件:**禁止在中断上下文调用**——内部用 taskENTER_CRITICAL() 保护
* 读-改-写,该临界区 API 在 ISR 内不成立;任意任务上下文可安全调用。
* 回绕前提:HAL_GetTick 是 32 位毫秒,回绕周期约 49.7 天;本函数靠"两次调用
* 间隔不足一整圈"识别回绕(cur < s_prev_lo 即高位 +1),故调用方须
* 保证至少每 49.7 天调用一次。本仓调用者是 netTask 的 1 ms 主循环
* (104 tick),IWDG 兜底;若两次调用间隔真超过 49.7 天,那是
* netTask 停摆,IWDG 早已复位,计时基线本就归零。
* 函数说明:纯时间读取,不依赖任何网络/上下文身份;内部 static 状态由临界区
* 整体保护,高低 32 位由同一次计算得出,不会撕裂。
*/
uint64_t sys_clock_mono_ms(void);
/*
* 函数功能:格式化系统墙钟时间为字符串
* 入口参数:buf - 输出缓冲区(至少 20 字节)
* buf_size - 缓冲区大小
* 返回值:buf 指针,失败返回 NULL
* 限定条件:sys_clock_init() 已调用
* 函数说明:格式 "YYYY-MM-DD HH:MM:SS"
*/
char *sys_clock_get_str(char *buf, size_t buf_size);
/*
* 函数功能:获取当前系统墙钟时间(日历时间)
* 入口参数:p_time - 输出时间结构指针(非 NULL)
* 出口参数:p_time - 填充年/月/日/时/分/秒/星期
* 返回值:0 - 成功, -1 - 失败(墙钟未初始化或参数无效)
* 限定条件:sys_clock_init() 已调用
* 函数说明:等价于 "sys_clock_get() + 内部日历换算",为需要日历字段的
* 使用方(如 FatFs 时间钩子)提供类型化接口
*/
int sys_clock_get_time(sd2506_time_t *p_time);
/*
* 函数功能:设置系统墙钟时间
* 入口参数:unix_secs - Unix epoch time (秒)
* sd_time - SD2506 RTC 时间结构体(可选,非 NULL 时同时写入 RTC)
* 返回值:0 - 成功, -1 - 失败
* 限定条件:sys_clock_init() 已调用
* 函数说明:更新系统墙钟基准 + 写回 SD2506 RTC 保持长期准确性
*/
int sys_clock_set(uint32_t unix_secs, const sd2506_time_t *sd_time);
/*
* 函数功能:以 Unix 时间戳设置系统墙钟并写回 SD2506 RTC
* 入口参数:unix_secs - Unix epoch time (秒,本地时间) uint32_t 0~0x7FFFFFFF
* 返回值:0 - 成功
* 限定条件:sys_clock_init() 已调用
* 函数说明:内部将 Unix 秒数转换为 sd2506_time_t 后调用 sys_clock_set(),
* 便于时间同步模块(如 PC 推送)直接以时间戳校时
*/
int sys_clock_set_unix(uint32_t unix_secs);
#ifdef __cplusplus
}
#endif
#endif /* SYS_CLOCK_H */