89 lines
3.3 KiB
C
89 lines
3.3 KiB
C
/*
|
||
* 模块名称：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);
|
||
|
||
/*
|
||
* 函数功能：格式化系统墙钟时间为字符串
|
||
* 入口参数：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 */
|