版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

一、概述

xt_hal_core 是 XTINY HAL 层的核心系统模块，提供系统初始化、时间获取、CPU 频率管理、系统重启、芯片唯一标识和版本信息查询等基础能力。所有平台都必须实现此模块。

1.1 设计原则

平台无关接口 ：所有函数只定义行为契约，不暴露寄存器、OS 调用等平台细节
弱函数覆盖 ： xt_hal_core_get_tick 和 xt_hal_core_get_us 声明为 __weak ，平台可提供更精确的实现覆盖默认版本
最小初始化 ： xt_hal_core_setup 只完成 HAL 层自身必要的初始化，不涉及外设

1.2 依赖

依赖	用途
xt_hal_internal.h	HAL 内部类型与工具宏

二、核心概念

2.1 tick 计数

xt_hal_core_get_tick 返回系统启动以来的毫秒级 tick 计数，用于简单的定时和超时判断。便捷宏 xt_tick_get() 等效调用此函数。

tick 值可能溢出回绕（ uint32_t ），比较时建议使用差值比较而非直接大小比较。

2.2 微秒时间戳

xt_hal_core_get_us 返回系统启动以来的微秒级时间戳（ uint64_t ），精度高于 tick，适用于性能测量等需要细粒度计时的场景。

2.3 CPU 频率

xt_hal_core_set_cpu_freq 返回实际设置的频率而非请求值，因为硬件可能不支持所有频率档位。调用方应检查返回值确认实际档位。

2.4 版本信息

xt_version 返回 32 位打包版本号（ [31:24] 保留， [23:16] 主版本， [15:8] 次版本， [7:0] 修订版本）。 xt_build_info 返回编译信息字符串（编译时间、编译器版本等）。

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_core（核心驱动）。

3.1 初始化

函数签名	说明
void xt_hal_core_setup(void)	初始化 HAL 核心模块

3.2 时间

函数签名	说明
uint32_t xt_hal_core_get_tick(void)	获取系统毫秒级 tick 计数（ __weak ）
uint64_t xt_hal_core_get_us(void)	获取系统微秒级时间戳（ __weak ）
xt_tick_get()	xt_hal_core_get_tick 的便捷宏

3.3 CPU 频率

函数签名	说明
uint32_t xt_hal_core_set_cpu_freq(uint32_t freq_hz)	设置 CPU 频率，返回实际频率（Hz）
uint32_t xt_hal_core_get_cpu_freq(void)	获取当前 CPU 频率（Hz）

3.4 系统控制

函数签名	说明
void xt_hal_core_reboot(void)	系统重启
uint32_t xt_hal_core_uid(void)	获取芯片唯一标识

3.5 版本

函数签名	说明
uint32_t xt_version(void)	获取 XT 核心版本号
const char *xt_build_info(void)	获取编译信息字符串

四、常见模式

4.1 基本初始化与时基使用

#include "xt_hal_core.h"
 
void app_init(void) {
    xt_hal_core_setup();
}
 
void app_run(void) {
    uint32_t start = xt_tick_get();
    do_long_operation();
    uint32_t elapsed = xt_tick_get() - start;
    if (elapsed > 5000) {
        /* 操作超过 5 秒 */
    }
}

4.2 微秒级性能测量

#include "xt_hal_core.h"
 
void measure_perf(void) {
    uint64_t t0 = xt_hal_core_get_us();
    function_under_test();
    uint64_t t1 = xt_hal_core_get_us();
    uint64_t delta_us = t1 - t0;  /* 耗时（微秒） */
}

4.3 调整 CPU 频率

#include "xt_hal_core.h"
 
void set_performance_mode(void) {
    uint32_t actual = xt_hal_core_set_cpu_freq(160000000);
    if (actual != 160000000) {
        /* 目标频率不可用， actual 为实际档位 */
    }
}

五、已知行为与限制

行为	说明
set_cpu_freq 返回实际值	请求频率可能不被硬件支持，必须用返回值确认
tick 为 uint32_t	约 49.7 天后溢出回绕，差值比较可规避
get_tick / get_us 为 __weak	默认实现可能精度有限，平台应覆盖
core_setup 不涉及外设	外设初始化由各子模块独立完成