G32S10 ADC API 概述

1. 文档范围

本文档定义 G32S10 SDK ADC 模块的正式接口，覆盖以下两层：

• HAL ADC：面向应用、BSP和驱动上层的功能级接口

• LL ADC：面向寄存器与位操作的低层接口

补充说明：

• LL层不返回状态码；需要返回寄存器值或数据时返回 uint32_t。

• HAL层负责参数校验、状态管理、中断/DMA编排和超时处理。

本文档以当前 SDK 源码为准，主要核对文件如下：

当文档描述与头文件、实现或 Kconfig 不一致时，以当前源码为准；硬件能力中未能在 SDK 源码内直接确认的数值，应结合芯片 SPEC 阅读。

2. 分层关系

分层职责如下：

• HAL ADC

• 封装初始化、序列配置、启动停止、轮询、中断、DMA侧控制、AWD和寄存器dump

• 维护参数合法性、模块级状态、活跃序列mask和统一返回码

• 提供便于上层使用的解包数据结构、回调注册和错误查询接口

• LL ADC

• 提供寄存器位级访问入口

• 不维护软件状态，不做复杂业务语义判断

• 公开接口均为 static inline，首参数为 adc_regs_t *adcx

• adc_regs.h

• 定义ADC基地址、寄存器结构体布局、通道数量、序列长度和位域mask

2.1 编译与运行前置条件

ADC HAL/LL 不负责板级时钟、引脚复用和 SoC 中断资源。直接使用本模块前，应用、BSP 或板级代码需要完成以下准备：

轮询模式下可不使用 ADC IRQ；DMA 模式是否使用完成中断取决于应用选择普通 start 还是 *_it() 接口。

3. 资源模型与公开类型

3.1 ADC 硬件能力摘要

3.2 HAL 返回状态约定

HAL层普通可失败接口统一返回SDK公共错误码类型：

error_code_t

常用返回值如下：

3.3 数据准备条件

typedef enum {
    HAL_ADC_DRT_SEQUENCE_END = 0,
    HAL_ADC_DRT_GROUP_END = 1,
    HAL_ADC_DRT_FIFO_GE_1 = 2,
    HAL_ADC_DRT_FIFO_GE_4 = 3,
    HAL_ADC_DRT_FIFO_GE_8 = 4,
    HAL_ADC_DRT_FIFO_GE_16 = 5,
    HAL_ADC_DRT_CUSTOM = 7,
} hal_adc_drt_t;

说明：

• SEQ0 只支持 HAL_ADC_DRT_SEQUENCE_END 和 HAL_ADC_DRT_CUSTOM。

• HAL_ADC_DRT_GROUP_END 仅对 SEQ1 连续组模式有效。

• FIFO阈值触发仅对 SEQ1、SEQ2 有效。

HAL 枚举值与 LL 写寄存器时使用的编码并不完全相同，调用 LL 接口时不要直接套用 HAL 数值：

LL函数只负责写入编码，不校验sequence与模式的组合是否有效；例如编码值1可由SEQ2的LL接口写入，但HAL不支持SEQ2组结束模式。

3.4 HAL 错误标志

typedef enum {
    HAL_ADC_ERROR_NONE = 0U,
    HAL_ADC_ERROR_INVALID_PARAM = (1UL << 0U),
    HAL_ADC_ERROR_EOC_TIMEOUT = (1UL << 1U),
    HAL_ADC_ERROR_DATA_OVERRUN = (1UL << 2U),
    HAL_ADC_ERROR_EVENT_OVERRUN = (1UL << 3U),
    HAL_ADC_ERROR_PHY_EOC = (1UL << 4U),
    HAL_ADC_ERROR_DMA = (1UL << 5U),
} hal_adc_error_t;

说明：

• 错误枚举值是bit flag，可按位或写入 hal_adc_handle_t.error_code。

• 统一start路径中的DMA handle打开或传输启动失败时，HAL会记录 HAL_ADC_ERROR_DMA。

• 普通HAL参数检查失败时直接返回 IM_ERR_INVALID_PARAM，当前实现不会因该次调用把 HAL_ADC_ERROR_INVALID_PARAM 锁存到 error_code。

• hal_adc_error_get() 在 hadc 或其 instance 无效时返回 HAL_ADC_ERROR_INVALID_PARAM，这一返回值是无效handle的结果，不代表发生了已锁存的参数错误。

4. 当前实现约束与行为说明

4.1 通道和序列长度

4.2 模式组合

4.3 AWD 阈值

4.4 配置修改时机与资源所有权

HAL 不会在所有配置接口中统一检查“所有序列均已停止”。调用方必须根据下表保证时序：

5. 示例程序与使用方式

5.1 示例程序索引与接入方式

ADC示例只位于 code/examples。这些文件不会自动编译进主固件，应用需要将选定的 .c 文件显式加入自身构建目标；示例用于说明调用方式，不属于与HAL/LL同等级的稳定二进制接口。

接入方式：

1. HAL示例需要包含 hal_adc.h 并启用 CONFIG_DRIVER_ADC；再按示例实际使用的功能启用GPIO、TCU、IRQ等驱动。CONFIG_DRIVER_ADC 会自动选择 CONFIG_DRIVER_DMA；示例本身不调用CPM HAL，SADC时钟由调用方准备。

2. LL示例需要包含 ll_adc.h，不需要链接ADC HAL。

3. 示例未提供独立公共头文件时，应用应显式把示例 .c 加入构建目标，并在应用侧声明需要调用的入口函数；不要同时编译和包含同一个 .c 文件，避免重复定义。

4. 调用示例前完成2.1节中的时钟、引脚、IRQ、systick和模拟信号准备。不同示例覆盖的前置条件不同，以各文件头部说明为准。

本文列出的 ADC HAL/LL 示例都不配置CPM，SADC源时钟和门控由板级代码或调用方预先建立；示例中的GPIO配置只负责把目标GPIOC引脚切到function 0。

5.2 单通道轮询采样

hal_adc_handle_t hadc0;
uint32_t value;
error_code_t ret;

ret = hal_adc_handle_init(&hadc0, ADC0);
if (ret != IM_OK) {
    return ret;
}

hadc0.init.adc_clk_div = 2U;
hadc0.init.soc_extra_cycle = (uint8_t)HAL_ADC_SOC_EXTRA_CYCLE_0;
ret = hal_adc_init(&hadc0);
if (ret != IM_OK) {
    return ret;
}

ret = hal_adc_channel_value_get(&hadc0, 0U, &value, 1000000U);