/*
 * 模块名称：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  王建锋  创建初始版本
 */

#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);

/*
 * 函数功能：设置系统墙钟时间
 * 入口参数：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 */