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

一、概述

xt_hal_adc 是 XTINY HAL ADC 驱动模块，提供两种采样模式：单次采样和连续采样。单次模式适合按需读取电压；连续模式适合以固定频率采集数据流，通过回调分批交付数据。

设计原则 ：

双模式 ：单次采样简洁直接；连续采样适合高频数据采集
原始值与电压值分离 ：xt_hal_adc_get_raw 返回原始 ADC 读数，xt_hal_adc_get_mv 返回转换后的电压值（mV）
连续模式回调驱动 ：每次半缓冲区填满时触发回调，用户通过 xt_hal_adc_get_result 获取数据

1.1 依赖

依赖	用途
xt_hal_internal.h	错误码类型 xt_err_t 及平台内部定义

二、核心概念

2.1 单次采样 vs 连续采样

特性	单次采样	连续采样
初始化	xt_hal_adc_setup	xt_hal_adc_setup_continuous
关闭	xt_hal_adc_close	xt_hal_adc_close_continuous
触发方式	每次调用 get_raw / get_mv	启动后持续采样
数据获取	同步函数返回	回调中调用 get_result
数据内容	原始值或 mV	仅原始值
启动/停止	无需	xt_hal_adc_rx_continuous / xt_hal_adc_stop_continuous

两种模式互斥，不能同时使用同一个 adc_id。通常先关闭当前模式再切换到另一种。

2.2 缓冲机制

连续采样采用双缓冲区（ping-pong）模型：整个 rx_buffer 被分为前后两半。当一半填满时触发回调，同时硬件继续写入另一半。用户在回调中处理刚填满的这半段数据。

回调中应尽快处理数据，避免下一段数据溢出。

2.3 ADC 索引（adc_id）

adc_id 代表 ADC 通道编号，不是 ADC 外设编号。不同 adc_id 可以同时工作（取决于平台支持的通道数）。

三、API 参考

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

3.1 单次采样

函数签名	说明
xt_err_t xt_hal_adc_setup(uint8_t adc_id, uint8_t res_bits, uint16_t vref_mv)	初始化单次采样模式
xt_err_t xt_hal_adc_close(uint8_t adc_id)	关闭单次采样模式
int32_t xt_hal_adc_get_verf_mv(uint8_t adc_id)	获取参考电压（mV）
int32_t xt_hal_adc_get_raw(uint8_t adc_id)	获取原始采样值
int32_t xt_hal_adc_get_mv(uint8_t adc_id)	获取转换后的电压值（mV）

3.2 连续采样

函数签名	说明
xt_err_t xt_hal_adc_setup_continuous(uint8_t adc_id, uint8_t res_bits, uint16_t vref_mv, uint32_t sample_freq_hz)	初始化连续采样模式
xt_err_t xt_hal_adc_close_continuous(uint8_t adc_id)	关闭连续采样模式
xt_err_t xt_hal_adc_rx_continuous(uint8_t adc_id, void *rx_buffer, size_t size)	启动连续接收，绑定缓冲区
xt_err_t xt_hal_adc_stop_continuous(uint8_t adc_id)	停止连续采样
xt_err_t xt_hal_adc_get_result(uint8_t adc_id, struct xt_hal_adc_result *result)	获取连续采样结果（仅回调中调用）

3.3 回调

函数签名	说明
xt_err_t xt_hal_adc_set_cb(uint8_t adc_id, xt_hal_adc_cb_t cb)	设置连续采样回调

3.4 类型

类型签名	说明
xt_hal_adc_cb_t	回调函数类型： void (*)(uint8_t adc_id, uint32_t event_id)
enum xt_hal_adc_event_id	事件 ID 枚举（ XT_HAL_ADC_EVENT_BATCH_DONE / XT_HAL_ADC_EVENT_ERROR ）
struct xt_hal_adc_result	连续传输结果结构体（ rx_buffer + size ）
XT_HAL_ADC_INVALID_ID	无效 ADC ID 宏： (0xFF)

四、编译配置

无编译配置项。

五、常见模式

5.1 单次采样读取电压

#include "xt_hal_adc.h"
 
void measure_battery(uint8_t adc_id) {
    xt_hal_adc_setup(adc_id, 12, 3300);
 
    int32_t mv = xt_hal_adc_get_mv(adc_id);
    if (mv < 0) {
        /* 读取失败 */
        return;
    }
    /* 使用电压值 mv */
 
    xt_hal_adc_close(adc_id);
}

5.2 连续采样音频数据

#include "xt_hal_adc.h"
 
#define BUF_SIZE  2048
 
static uint16_t s_adc_buf[BUF_SIZE];
 
static void adc_callback(uint8_t adc_id, uint32_t event_id) {
    if (event_id == XT_HAL_ADC_EVENT_BATCH_DONE) {
        struct xt_hal_adc_result res;
        xt_hal_adc_get_result(adc_id, &res);
        /* 处理 res.rx_buffer 中的数据，长度 res.size */
        /* 注意：res.rx_buffer 指向 s_adc_buf 的某一半 */
    }
}
 
void start_audio_sampling(uint8_t adc_id) {
    xt_hal_adc_set_cb(adc_id, adc_callback);
    xt_hal_adc_setup_continuous(adc_id, 12, 3300, 16000);
    xt_hal_adc_rx_continuous(adc_id, s_adc_buf, sizeof(s_adc_buf));
}
 
void stop_audio_sampling(uint8_t adc_id) {
    xt_hal_adc_stop_continuous(adc_id);
    xt_hal_adc_close_continuous(adc_id);
}

六、已知行为与限制

行为	说明
连续采样仅填原始值	连续模式下缓冲区只填充原始 ADC 读数，不会自动转换为 mV
get_result 仅回调中有效	只在连续模式回调函数中调用有效，其他位置行为未定义
单次与连续模式互斥	不能同时对同一 adc_id 同时使用两种模式
连续采样功能平台依赖	部分平台未实现连续采样相关函数
通道数由平台定义	adc_id 有效范围取决于具体平台的 ADC 通道数