# RTC / GNSS / WSS 诊断日志

所有新增输出以 `[TIME-DIAG]` 开头，仅采集状态，不主动设置时间、清除 NVM 或修改校时重试策略。

## 构建与采集

完整诊断需要在支持的 Windows 编译环境依次执行 `build.bat kernel`、`build.bat app`、`build.bat firmware`，并更新匹配的内核和 APP。普通 APP OTA 不代表内核已更新。保留设备原有 RTC/NVM 状态，以免丢失异常现场。

APP 兼容旧内核：缺少新增接口时打印 `kernel_diag=unavailable need_matching_diagnostic_kernel=1`，仍可输出 WSS 的 APP 时间，但无法取得内核偏移和跟随标志。

采集从上电至 WSS 首次失败、随后恢复的完整串口日志，并记录烧录包版本。启动日志包含 APP 版本、编译信息和固件版本；内核事件日志包含自身编译日期。重点比较异常设备与正常设备的下列阶段：

- `boot-before-nitz`：启动且尚未开启 NITZ。
- `nitz-enabled`、`pdp-active`：开启运营商校时、数据连接成功。
- `gnss_ntp_dns`、`gnss_ntp_trigger`、`ntp_request/result`、`ntp_rtc_written`：GNSS 发起的 NTP 路径。
- `gnss-time-state`、`ntp-finished`：内核校时状态变化和 NTP 完成。
- `wss-before-time-read`、`wss-precheck`、`wss-after-time-read`：WSS 读取 APP 时间前后。

## 字段

`counter` 是原始 RTC 计数，`sys_offset/app_offset` 是两套偏移；`sys_raw/app_raw` 是无符号 32 位相加后的原始秒数，不直接视为 UTC。`follows_sys` 是 APP 跟随 SYS 标志；`app_ever` 表示持久化的 APP RTC 设置标记；`storage` 是 SDK 的偏移存储枚举。

`net_tz_min` 单位为分钟，`rtc_tz_hour` 单位为小时；`source` 对应 SDK 的 NITZ=0、NTP=1、APP=2、UNKNOWN=3。`ntp_status` 对应原有状态 0/1/2（初始/成功/失败），日志忠实输出现有状态，不能仅凭这个标志判定实际校时成功。`ntp_type` 是 SDK 的校时类型状态，`ntp_ready` 表示任务和事件句柄已创建；`gnss_rtc` 是 GNSS 网络模块的校时状态，`cid` 为该模块记录的数据上下文。未编入的可选功能字段为 -1。

`time_null` 是 WSS 原来使用的 `time(NULL)` 样本，门槛仍为 `1704067200`；返回这个原始样本用于判断。`time_ptr_return/value` 用于对比 `time(&value)` 的返回值和指针写回，未写回时 value 保持哨兵值 1。`app_calendar` 来自额外的 `ql_rtc_get_time`，只在 `rtc_rc` 成功时有意义。

内核快照直接读计数、偏移和标记，避开可能开启 APP 跟随行为的 RTC 取时接口。WSS 额外读取发生在原来的首次 `time(NULL)` 之后。多字段采样并非原子快照，允许跨秒或并发校时造成的短暂差异，需结合连续日志判读。

## 本机检查

`python3 tools/test_time_diag.py` 使用本机 C 编译器及模拟 SDK，编译实际新增模块，验证可选接口缺失、ABI 不匹配、未初始化 RTC、SYS/APP 偏移差异、32 位溢出及 WSS 保留原始门槛样本。它不替代 Windows 目标固件编译、链接或实机复现。