G32S10 ADC LL 接口

1. 文档范围

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

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

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

补充说明：

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

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

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

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

目录

• 1. 文档范围

• 2. 分层关系

• 2.1 编译与运行前置条件

• 3. 资源模型与公开类型

• 3.1 模块基地址与实例

• 3.2 ADC 硬件能力摘要

• 3.3 HAL 公开宏

• 3.4 HAL 返回状态约定

• 3.5 HAL 运行状态

• 3.6 ADC 序列类型

• 3.7 ADC 触发类型

• 3.8 ADC 序列优先级

• 3.9 ADC SOC 额外周期

• 3.10 数据准备条件

• 3.11 ADC DMA 传输模式

• 3.12 HAL 错误标志

• 3.13 回调 ID

• 3.14 ADC 采样数据

• 3.15 ADC 初始化配置

• 3.16 ADC 序列配置

• 3.17 ADC 模拟看门狗配置

• 3.18 ADC 回调类型

• 3.19 ADC 句柄

• 4. HAL 接口规范

• 4.1 HAL 层实现边界

• 4.2 初始化和反初始化

• 4.3 基础配置

• 4.4 序列配置

• 4.5 启动、停止和轮询

• 4.6 数据读取

• 4.7 中断模式

• 4.8 DMA 配置和状态

• 4.9 模拟看门狗

• 4.10 调试、状态和错误查询

• 5. LL 与基础辅助接口规范

• 5.1 LL 层实现边界

• 5.2 LL 层公开宏

• 5.3 基础辅助与寄存器访问

• 5.4 PHY 和全局控制

• 5.5 时钟控制

• 5.6 状态和中断

• 5.7 序列公共控制

• 5.8 SEQ0 接口

• 5.9 SEQ1 接口

• 5.10 SEQ2 接口

• 5.11 模拟看门狗接口

• 6. 寄存器映射与位域约定

• 6.1 寄存器映射

• 6.2 寄存器和位域宏

• 6.3 寄存器访问约束

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

• 7.1 通道和序列长度

• 7.2 模式组合

• 7.3 SOC 额外周期

• 7.4 AWD 阈值

• 7.5 DMA 注意事项

• 7.6 实现约束

• 7.7 状态迁移、错误锁存与恢复

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

• 7.9 回调与中断上下文

• 8. 示例程序与使用方式

• 8.1 示例程序索引与接入方式

• 8.2 单通道轮询采样

• 8.3 SEQ1 多通道扫描中断模式

• 8.4 SEQ1 连续组与 TCU 外部触发

• 8.5 SEQ2 DMA 采样

• 8.6 AWD 高低阈值检测

• 8.7 LL 寄存器级序列采样

• 9. HAL 错误码与错误标志

2. 分层关系

Application / BSP / Example
           |
           v
        HAL ADC
           |
           v
        LL ADC
           |
           v
      ADC Registers

分层职责如下：

• 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() 接口。

5. LL 与基础辅助接口规范

说明：完整函数原型以 ll_adc.h 为准。

5.1 LL 层实现边界

• 当前LL实现文件为 code/include/drivers/g32s10/adc/ll_adc.h，寄存器映射和寄存器位定义文件为 code/include/drivers/g32s10/adc/adc_regs.h。

• 所有公开 ll_adc_* 接口均为 static inline，首参数统一为 adc_regs_t *adcx。

• LL层不做参数合法性判断，不返回状态码；调用者必须保证 adcx、数组指针、序列号、通道号、rank、mask等参数合法。

• 写寄存器、置位、清位类接口返回 void；读寄存器、读状态、读数据类接口返回 uint32_t。

• SEQ1当前LL接口只开放rank 07，高位rank 815暂不开放；后续如SPEC更新再扩展。

• SEQ1_CR / SEQ2_CR 只提供触发源 EXTSEL 配置，不提供TCU通道选择参数。

• ll_adc_seq_start() / ll_adc_seq_multi_start() 仅适用于软件触发序列；外部触发序列由外部触发源启动。

• AWD总中断清除使用 ll_adc_interrupt_status_clear(adcx, ADC_IR_AWD)。

• Debug寄存器接口不对外提供，dbg_cr / dbg_fsm 仅保留在寄存器映射中。

5.2 LL 层公开宏

当前SDK中LL层使用的ADC寄存器宏集中在 adc_regs.h，前缀为 ADC_。

5.3 基础辅助与寄存器访问

5.3.1 ll_adc_is_instance

static inline bool ll_adc_is_instance(const adc_regs_t *adcx);

功能说明： 判断传入的ADC寄存器基地址是否为当前SDK支持的ADC实例。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 可为任意地址，接口只做地址比较。

5.3.2 ll_adc_reg_write

static inline void ll_adc_reg_write(adc_regs_t *adcx, uint32_t offset, uint32_t value);

功能说明： 按ADC基地址偏移写一个32位寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：offset 为32位对齐的寄存器字节偏移；value 为写入值。

5.3.3 ll_adc_reg_read

static inline uint32_t ll_adc_reg_read(adc_regs_t *adcx, uint32_t offset);

功能说明： 按ADC基地址偏移读一个32位寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：offset 为32位对齐的寄存器字节偏移。

5.4 PHY 和全局控制

5.4.1 ll_adc_phy_enable

static inline void ll_adc_phy_enable(adc_regs_t *adcx);

功能说明： ADC PHY上电。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.2 ll_adc_phy_disable

static inline void ll_adc_phy_disable(adc_regs_t *adcx);

功能说明： ADC PHY下电。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.3 ll_adc_phy_pad_enable

static inline void ll_adc_phy_pad_enable(adc_regs_t *adcx);

功能说明： 使能模拟pad输入选择。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.4 ll_adc_phy_pad_disable

static inline void ll_adc_phy_pad_disable(adc_regs_t *adcx);

功能说明： 关闭模拟pad输入选择。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.5 ll_adc_phy_reset_enable

static inline void ll_adc_phy_reset_enable(adc_regs_t *adcx);

功能说明： 置位PHY reset。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.6 ll_adc_phy_reset_disable

static inline void ll_adc_phy_reset_disable(adc_regs_t *adcx);

功能说明： 释放PHY reset。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.7 ll_adc_phy_eoc_select

static inline void ll_adc_phy_eoc_select(adc_regs_t *adcx, uint8_t eoc_source);

功能说明： 选择EOC来源。

参数表：

返回值表：

补充说明：

• 参数约束：eoc_source 为0表示控制器EOC，为1表示PHY EOC。

5.4.8 ll_adc_break_enable

static inline void ll_adc_break_enable(adc_regs_t *adcx);

功能说明： 允许高优先级序列打断低优先级序列。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.9 ll_adc_break_disable

static inline void ll_adc_break_disable(adc_regs_t *adcx);

功能说明： 禁止冲突处理打断正在运行的序列。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.4.10 ll_adc_soc_extra_cycle_set

static inline void ll_adc_soc_extra_cycle_set(adc_regs_t *adcx, uint8_t cycle);

功能说明： 配置SOC额外高电平周期。

参数表：

返回值表：

补充说明：

• 参数约束：cycle 使用 ADC_SOC_EXTRA_CYCLE_* 离散值；禁止在任一序列工作期间修改该字段。

5.5 时钟控制

5.5.1 ll_adc_clk_div_set

static inline void ll_adc_clk_div_set(adc_regs_t *adcx, uint8_t adc_clk_div);

功能说明： 配置ADC转换时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：adc_clk_div 为 ADC_CLKR0.ADCCLK_DIV 字段值，范围0~0xFF。

5.5.2 ll_adc_clk_div_get

static inline uint32_t ll_adc_clk_div_get(adc_regs_t *adcx);

功能说明： 读取ADC转换时钟分频字段。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.5.3 ll_adc_seq1_cont_clk_div_set

static inline void ll_adc_seq1_cont_clk_div_set(adc_regs_t *adcx, uint32_t div);

功能说明： 配置SEQ1连续转换间隔时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：div 为 ADC_CLKR0.SEQ1_CONTCLK_DIV 字段值，范围0~0x00FFFFFF。

5.5.4 ll_adc_seq1_delay_clk_div_set

static inline void ll_adc_seq1_delay_clk_div_set(adc_regs_t *adcx, uint32_t div);

功能说明： 配置SEQ1延时计数时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：div 为 ADC_CLKR1.SEQ1_DLYCLK_DIV 字段值，范围0~0x00FFFFFF。

5.5.5 ll_adc_seq2_delay_clk_div_set

static inline void ll_adc_seq2_delay_clk_div_set(adc_regs_t *adcx, uint32_t div);

功能说明： 配置SEQ2延时计数时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：div 为 ADC_CLKR2.SEQ2_DLYCLK_DIV 字段值，范围0~0x00FFFFFF。

5.6 状态和中断

5.6.1 ll_adc_status_get

static inline uint32_t ll_adc_status_get(adc_regs_t *adcx);

功能说明： 读取ADC状态寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.6.2 ll_adc_status_clear

static inline void ll_adc_status_clear(adc_regs_t *adcx, uint32_t flag_mask);

功能说明： 清除写1清零的ADC状态位。

参数表：

返回值表：

补充说明：

• 参数约束：flag_mask 使用 ADC_SR_* 掩码；全清可用 ADC_MASK_ALL。

5.6.3 ll_adc_interrupt_enable

static inline void ll_adc_interrupt_enable(adc_regs_t *adcx, uint32_t interrupt_mask);

功能说明： 使能ADC中断源。

参数表：

返回值表：

补充说明：

• 参数约束：interrupt_mask 使用 ADC_IE_* 掩码。

5.6.4 ll_adc_interrupt_disable

static inline void ll_adc_interrupt_disable(adc_regs_t *adcx, uint32_t interrupt_mask);

功能说明： 关闭ADC中断源。

参数表：

返回值表：

补充说明：

• 参数约束：interrupt_mask 使用 ADC_IE_* 掩码；全关可用 ADC_MASK_ALL。

5.6.5 ll_adc_interrupt_status_get

static inline uint32_t ll_adc_interrupt_status_get(adc_regs_t *adcx);

功能说明： 读取ADC中断状态寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.6.6 ll_adc_interrupt_status_clear

static inline void ll_adc_interrupt_status_clear(adc_regs_t *adcx, uint32_t interrupt_mask);

功能说明： 清除ADC中断状态位。

参数表：

返回值表：

补充说明：

• 参数约束：interrupt_mask 使用 ADC_IR_* 掩码；AWD总中断清除使用 ADC_IR_AWD。

5.7 序列公共控制

5.7.1 ll_adc_seq_priority_set

static inline void ll_adc_seq_priority_set(adc_regs_t *adcx,
                                           uint8_t adc_seq,
                                           uint8_t priority);

功能说明： 配置单个序列优先级。

参数表：

返回值表：

补充说明：

• 参数约束：adc_seq 使用 ADC_SEQ_0/1/2；priority 范围0~3，0最低、3最高。

5.7.2 ll_adc_seq_priority_get

static inline uint32_t ll_adc_seq_priority_get(adc_regs_t *adcx, uint8_t adc_seq);

功能说明： 读取单个序列优先级。

参数表：

返回值表：

补充说明：

• 参数约束：adc_seq 使用 ADC_SEQ_0/1/2。

5.7.3 ll_adc_seq_start

static inline void ll_adc_seq_start(adc_regs_t *adcx, uint8_t adc_seq);

功能说明： 软件触发启动单个ADC转换序列。

参数表：

返回值表：

补充说明：

• 参数约束：adc_seq 使用 ADC_SEQ_0/1/2；仅在序列配置为软件触发时使用。

• 该接口仅适用于已配置为软件触发的序列。

• 启动位兼作“待处理触发事件”标志，硬件消费后自清。接口写入时先清除全部启动位，再只置位本次请求的位，不会把读到的旧 1 回写。

• 连续调用本接口启动不同序列时，先前序列的启动事件不会被重复投递，因此不会产生该序列的 EVTn_EVT_OVR。

5.7.4 ll_adc_seq_multi_start

static inline void ll_adc_seq_multi_start(adc_regs_t *adcx, uint32_t seq_mask);

功能说明： 软件触发启动一个或多个ADC转换序列。

参数表：

返回值表：

补充说明：

• 参数约束：seq_mask 使用bit0/1/2选择SEQ0/SEQ1/SEQ2；被选序列均应配置为软件触发。

• seq_mask 保持32位，便于直接承载寄存器mask表达。

• 仅置位 seq_mask 选中的启动位；其他启动位写 0，避免把仍处于待处理状态的事件重复写回而触发 EVTn_EVT_OVR。

• 需要多个序列同时启动时应一次调用本接口，而不是连续多次调用单序列启动接口。

5.7.5 ll_adc_seq_reset

static inline void ll_adc_seq_reset(adc_regs_t *adcx, uint8_t adc_seq);

功能说明： 复位单个序列状态机。

参数表：

返回值表：

补充说明：

• 参数约束：adc_seq 使用 ADC_SEQ_0/1/2。

5.7.6 ll_adc_seq_busy_get

static inline uint32_t ll_adc_seq_busy_get(adc_regs_t *adcx, uint8_t adc_seq);

功能说明： 读取单个序列FSM状态。

参数表：

返回值表：

补充说明：

• 参数约束：adc_seq 使用 ADC_SEQ_0/1/2。

5.8 SEQ0 接口

5.8.1 ll_adc_seq0_channels_set

static inline void ll_adc_seq0_channels_set(adc_regs_t *adcx,
                                            const uint8_t *channel,
                                            uint8_t channel_count);

功能说明： 配置SEQ0转换通道列表。

参数表：

返回值表：

补充说明：

• 参数约束：channel 指向通道数组；channel_count 范围1~4；LL默认参数合法。

5.8.2 ll_adc_seq0_length_set

static inline void ll_adc_seq0_length_set(adc_regs_t *adcx, uint8_t channel_count);

功能说明： 配置SEQ0转换次数。

参数表：

返回值表：

补充说明：

• 参数约束：channel_count 范围1~4，接口内部写入 channel_count - 1。

5.8.3 ll_adc_seq0_channel_number_enable

static inline void ll_adc_seq0_channel_number_enable(adc_regs_t *adcx);

功能说明： 使能SEQ0结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.8.4 ll_adc_seq0_channel_number_disable

static inline void ll_adc_seq0_channel_number_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ0结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.8.5 ll_adc_seq0_data_ready_type_set

static inline void ll_adc_seq0_data_ready_type_set(adc_regs_t *adcx,
                                                   uint8_t data_ready_type,
                                                   uint8_t custom_mask);

功能说明： 配置SEQ0数据就绪方式。

参数表：

返回值表：

补充说明：

• 参数约束：data_ready_type 为0表示序列结束，为1表示自定义rank；custom_mask 仅bit3:0有效。

5.8.6 ll_adc_seq0_data_count_get

static inline uint32_t ll_adc_seq0_data_count_get(adc_regs_t *adcx);

功能说明： 读取SEQ0已采样数据数量。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.8.7 ll_adc_seq0_data_reg_get

static inline uint32_t ll_adc_seq0_data_reg_get(adc_regs_t *adcx, uint8_t reg_index);

功能说明： 读取SEQ0原始数据寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：reg_index 范围0~1。

5.8.8 ll_adc_seq0_data_get

static inline uint32_t ll_adc_seq0_data_get(adc_regs_t *adcx, uint8_t rank);

功能说明： 读取SEQ0指定rank的packed结果。

参数表：

返回值表：

补充说明：

• 参数约束：rank 范围0~3。

5.9 SEQ1 接口

5.9.1 ll_adc_seq1_channels_set

static inline void ll_adc_seq1_channels_set(adc_regs_t *adcx,
                                            const uint8_t *channel,
                                            uint8_t channel_count);

功能说明： 配置SEQ1转换通道列表。

参数表：

返回值表：

补充说明：

• 参数约束：channel 指向通道数组；channel_count 范围18；高位rank 815暂不开放。

• 当前LL只开放rank0rank7，高位rank8rank15暂不开放。

5.9.2 ll_adc_seq1_length_set

static inline void ll_adc_seq1_length_set(adc_regs_t *adcx, uint8_t channel_count);

功能说明： 配置SEQ1转换次数。

参数表：

返回值表：

补充说明：

• 参数约束：channel_count 范围1~8，接口内部写入 channel_count - 1。

5.9.3 ll_adc_seq1_trigger_set

static inline void ll_adc_seq1_trigger_set(adc_regs_t *adcx, uint8_t trigger);

功能说明： 配置SEQ1触发源。

参数表：

返回值表：

补充说明：

• 参数约束：trigger 使用 ADC_TRIGGER_SOFTWARE/TCU/PWM0/PWM1；不配置TCU通道。

• SEQ1_CR 只选择触发源，不包含TCU通道选择字段。

5.9.4 ll_adc_seq1_channel_number_enable

static inline void ll_adc_seq1_channel_number_enable(adc_regs_t *adcx);

功能说明： 使能SEQ1结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.5 ll_adc_seq1_channel_number_disable

static inline void ll_adc_seq1_channel_number_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ1结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.6 ll_adc_seq1_storage_mask_set

static inline void ll_adc_seq1_storage_mask_set(adc_regs_t *adcx, uint8_t storage_mask);

功能说明： 配置SEQ1 CPU数据存储rank mask。

参数表：

返回值表：

补充说明：

• 参数约束：storage_mask 仅bit7:0有效，bit为1表示存储对应rank。

5.9.7 ll_adc_seq1_data_ready_type_set

static inline void ll_adc_seq1_data_ready_type_set(adc_regs_t *adcx,
                                                   uint8_t data_ready_type,
                                                   uint8_t custom_mask);

功能说明： 配置SEQ1数据就绪触发方式。

参数表：

返回值表：

补充说明：

• 参数约束：data_ready_type 使用SEQ1支持的 ADC_DRT_*；custom_mask 仅bit7:0有效。

5.9.8 ll_adc_seq1_dma_enable

static inline void ll_adc_seq1_dma_enable(adc_regs_t *adcx);

功能说明： 使能SEQ1 DMA模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.9 ll_adc_seq1_dma_disable

static inline void ll_adc_seq1_dma_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ1 DMA模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.10 ll_adc_seq1_fifo_count_get

static inline uint32_t ll_adc_seq1_fifo_count_get(adc_regs_t *adcx);

功能说明： 读取SEQ1 FIFO数据数量。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.11 ll_adc_seq1_fifo_read

static inline uint32_t ll_adc_seq1_fifo_read(adc_regs_t *adcx);

功能说明： 读取SEQ1 FIFO数据寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：读取可能弹出FIFO数据或改变FIFO状态。

5.9.12 ll_adc_seq1_delay_set

static inline void ll_adc_seq1_delay_set(adc_regs_t *adcx,
                                         uint8_t rank,
                                         uint16_t delay_count);

功能说明： 配置SEQ1指定rank延时。

参数表：

返回值表：

补充说明：

• 参数约束：rank 范围07；delay_count 范围00xFFFF。

5.9.13 ll_adc_seq1_continuous_enable

static inline void ll_adc_seq1_continuous_enable(adc_regs_t *adcx);

功能说明： 使能SEQ1连续转换模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.14 ll_adc_seq1_continuous_disable

static inline void ll_adc_seq1_continuous_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ1连续转换模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.15 ll_adc_seq1_group_count_set

static inline void ll_adc_seq1_group_count_set(adc_regs_t *adcx, uint8_t group_count);

功能说明： 配置SEQ1连续组数量。

参数表：

返回值表：

补充说明：

• 参数约束：group_count 范围1~8，接口内部写入 group_count - 1。

5.9.16 ll_adc_seq1_group_config_set

static inline void ll_adc_seq1_group_config_set(adc_regs_t *adcx,
                                                uint8_t group_index,
                                                uint8_t group_length,
                                                uint16_t group_interval);

功能说明： 配置SEQ1连续组长度和间隔。

参数表：

返回值表：

补充说明：

• 参数约束：group_index 范围07；group_length 范围18；group_interval 范围0~0xFFFF。

5.9.17 ll_adc_seq1_read_counter_set

static inline void ll_adc_seq1_read_counter_set(adc_regs_t *adcx, uint16_t max, uint16_t cnt);

功能说明： 配置SEQ1读计数器最大值和当前值。

参数表：

返回值表：

补充说明：

• 参数约束：max、cnt 范围0~0xFFFF。

5.9.18 ll_adc_seq1_read_counter_get

static inline uint32_t ll_adc_seq1_read_counter_get(adc_regs_t *adcx);

功能说明： 读取SEQ1读计数器寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.19 ll_adc_seq1_dma_read_counter_get

static inline uint32_t ll_adc_seq1_dma_read_counter_get(adc_regs_t *adcx);

功能说明： 读取SEQ1 DMA读计数器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.9.20 ll_adc_seq1_data_reg_get

static inline uint32_t ll_adc_seq1_data_reg_get(adc_regs_t *adcx, uint8_t reg_index);

功能说明： 读取SEQ1原始CPU数据寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：reg_index 范围0~3。

5.9.21 ll_adc_seq1_data_get

static inline uint32_t ll_adc_seq1_data_get(adc_regs_t *adcx, uint8_t rank);

功能说明： 读取SEQ1指定rank的packed结果。

参数表：

返回值表：

补充说明：

• 参数约束：rank 范围0~7。

5.10 SEQ2 接口

5.10.1 ll_adc_seq2_channels_set

static inline void ll_adc_seq2_channels_set(adc_regs_t *adcx,
                                            const uint8_t *channel,
                                            uint8_t channel_count);

功能说明： 配置SEQ2转换通道列表。

参数表：

返回值表：

补充说明：

• 参数约束：channel 指向通道数组；channel_count 范围1~8。

5.10.2 ll_adc_seq2_length_set

static inline void ll_adc_seq2_length_set(adc_regs_t *adcx, uint8_t channel_count);

功能说明： 配置SEQ2转换次数。

参数表：

返回值表：

补充说明：

• 参数约束：channel_count 范围1~8，接口内部写入 channel_count - 1。

5.10.3 ll_adc_seq2_trigger_set

static inline void ll_adc_seq2_trigger_set(adc_regs_t *adcx, uint8_t trigger);

功能说明： 配置SEQ2触发源。

参数表：

返回值表：

补充说明：

• 参数约束：trigger 使用 ADC_TRIGGER_SOFTWARE/TCU/PWM0/PWM1；不配置TCU通道。

• SEQ2_CR 只选择触发源，不包含TCU通道选择字段。

5.10.4 ll_adc_seq2_channel_number_enable

static inline void ll_adc_seq2_channel_number_enable(adc_regs_t *adcx);

功能说明： 使能SEQ2结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.5 ll_adc_seq2_channel_number_disable

static inline void ll_adc_seq2_channel_number_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ2结果携带通道号。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.6 ll_adc_seq2_storage_mask_set

static inline void ll_adc_seq2_storage_mask_set(adc_regs_t *adcx, uint8_t storage_mask);

功能说明： 配置SEQ2 CPU数据存储rank mask。

参数表：

返回值表：

补充说明：

• 参数约束：storage_mask 仅bit7:0有效，bit为1表示存储对应rank。

5.10.7 ll_adc_seq2_data_ready_type_set

static inline void ll_adc_seq2_data_ready_type_set(adc_regs_t *adcx,
                                                   uint8_t data_ready_type,
                                                   uint8_t custom_mask);

功能说明： 配置SEQ2数据就绪触发方式。

参数表：

返回值表：

补充说明：

• 参数约束：data_ready_type 使用SEQ2支持的 ADC_DRT_*；custom_mask 仅bit7:0有效。

5.10.8 ll_adc_seq2_dma_enable

static inline void ll_adc_seq2_dma_enable(adc_regs_t *adcx);

功能说明： 使能SEQ2 DMA模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.9 ll_adc_seq2_dma_disable

static inline void ll_adc_seq2_dma_disable(adc_regs_t *adcx);

功能说明： 关闭SEQ2 DMA模式。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.10 ll_adc_seq2_fifo_count_get

static inline uint32_t ll_adc_seq2_fifo_count_get(adc_regs_t *adcx);

功能说明： 读取SEQ2 FIFO数据数量。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.11 ll_adc_seq2_fifo_read

static inline uint32_t ll_adc_seq2_fifo_read(adc_regs_t *adcx);

功能说明： 读取SEQ2 FIFO数据寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：读取可能弹出FIFO数据或改变FIFO状态。

5.10.12 ll_adc_seq2_delay_set

static inline void ll_adc_seq2_delay_set(adc_regs_t *adcx,
                                         uint8_t rank,
                                         uint8_t delay_count);

功能说明： 配置SEQ2指定rank延时。

参数表：

返回值表：

补充说明：

• 参数约束：rank 范围07；delay_count 范围00xFF。

5.10.13 ll_adc_seq2_read_counter_set

static inline void ll_adc_seq2_read_counter_set(adc_regs_t *adcx, uint16_t max, uint16_t cnt);

功能说明： 配置SEQ2读计数器最大值和当前值。

参数表：

返回值表：

补充说明：

• 参数约束：max、cnt 范围0~0xFFFF。

5.10.14 ll_adc_seq2_read_counter_get

static inline uint32_t ll_adc_seq2_read_counter_get(adc_regs_t *adcx);

功能说明： 读取SEQ2读计数器寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.15 ll_adc_seq2_dma_read_counter_get

static inline uint32_t ll_adc_seq2_dma_read_counter_get(adc_regs_t *adcx);

功能说明： 读取SEQ2 DMA读计数器。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.10.16 ll_adc_seq2_data_reg_get

static inline uint32_t ll_adc_seq2_data_reg_get(adc_regs_t *adcx, uint8_t reg_index);

功能说明： 读取SEQ2原始CPU数据寄存器。

参数表：

返回值表：

补充说明：

• 参数约束：reg_index 范围0~3。

5.10.17 ll_adc_seq2_data_get

static inline uint32_t ll_adc_seq2_data_get(adc_regs_t *adcx, uint8_t rank);

功能说明： 读取SEQ2指定rank的packed结果。

参数表：

返回值表：

补充说明：

• 参数约束：rank 范围0~7。

5.11 模拟看门狗接口

5.11.1 ll_adc_awd_threshold_set

static inline void ll_adc_awd_threshold_set(adc_regs_t *adcx,
                                            uint8_t channel,
                                            uint16_t low_threshold,
                                            uint16_t high_threshold);

功能说明： 配置单通道AWD低/高阈值。

参数表：

返回值表：

补充说明：

• 参数约束：channel 范围07；low_threshold、high_threshold 范围00x0FFF。

5.11.2 ll_adc_awd_low_threshold_enable

static inline void ll_adc_awd_low_threshold_enable(adc_regs_t *adcx, uint8_t channel);

功能说明： 使能指定通道低阈值检测。

参数表：

返回值表：

补充说明：

• 参数约束：channel 范围0~7。

5.11.3 ll_adc_awd_low_threshold_disable

static inline void ll_adc_awd_low_threshold_disable(adc_regs_t *adcx, uint8_t channel);

功能说明： 关闭指定通道低阈值检测。

参数表：

返回值表：

补充说明：

• 参数约束：channel 范围0~7。

5.11.4 ll_adc_awd_high_threshold_enable

static inline void ll_adc_awd_high_threshold_enable(adc_regs_t *adcx, uint8_t channel);

功能说明： 使能指定通道高阈值检测。

参数表：

返回值表：

补充说明：

• 参数约束：channel 范围0~7。

5.11.5 ll_adc_awd_high_threshold_disable

static inline void ll_adc_awd_high_threshold_disable(adc_regs_t *adcx, uint8_t channel);

功能说明： 关闭指定通道高阈值检测。

参数表：

返回值表：

补充说明：

• 参数约束：channel 范围0~7。

5.11.6 ll_adc_awd_status_get

static inline uint32_t ll_adc_awd_status_get(adc_regs_t *adcx);

功能说明： 读取AWD状态flag。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.11.7 ll_adc_awd_status_clear

static inline void ll_adc_awd_status_clear(adc_regs_t *adcx, uint32_t awd_flag_mask);

功能说明： 清除AWD状态flag。

参数表：

返回值表：

补充说明：

• 参数约束：awd_flag_mask 使用 ADC_AWD_LOW_FLAG(channel) 或 ADC_AWD_HIGH_FLAG(channel)，channel范围0~7。

5.11.8 ll_adc_awd_interrupt_enable

static inline void ll_adc_awd_interrupt_enable(adc_regs_t *adcx, uint32_t awd_flag_mask);

功能说明： 使能AWD中断flag。

参数表：

返回值表：

补充说明：

• 参数约束：awd_flag_mask 使用AWD flag宏；AWD_IM 中0表示不屏蔽，接口内部清除对应bit。

5.11.9 ll_adc_awd_interrupt_disable

static inline void ll_adc_awd_interrupt_disable(adc_regs_t *adcx, uint32_t awd_flag_mask);

功能说明： 屏蔽AWD中断flag。

参数表：

返回值表：

补充说明：

• 参数约束：awd_flag_mask 使用AWD flag宏；AWD_IM 中1表示屏蔽，接口内部置位对应bit。

5.11.10 ll_adc_awd_interrupt_status_get

static inline uint32_t ll_adc_awd_interrupt_status_get(adc_regs_t *adcx);

功能说明： 读取AWD中断状态flag。

参数表：

返回值表：

补充说明：

• 参数约束：adcx 为ADC实例。

5.11.11 ll_adc_awd_fail_enable

static inline void ll_adc_awd_fail_enable(adc_regs_t *adcx, uint32_t awd_flag_mask);

功能说明： 使能AWD fail输出flag。

参数表：

返回值表：

补充说明：

• 参数约束：awd_flag_mask 使用AWD flag宏；AWD_FAIL 中0表示使能，接口内部清除对应bit。

5.11.12 ll_adc_awd_fail_disable

static inline void ll_adc_awd_fail_disable(adc_regs_t *adcx, uint32_t awd_flag_mask);

功能说明： 屏蔽AWD fail输出flag。

参数表：

返回值表：

补充说明：

• 参数约束：awd_flag_mask 使用AWD flag宏；AWD_FAIL 中1表示屏蔽，接口内部置位对应bit。

6. 寄存器映射与位域约定

6.1 寄存器映射

adc_regs_t 的唯一定义位于 code/include/drivers/g32s10/adc/adc_regs.h。为避免文档副本与头文件字段声明漂移，本手册只维护寄存器偏移和用途：

说明：

• AWD_CR[16] 按寄存器空间保留16个槽位；HAL当前只开放通道0~7。

• dbg_cr / dbg_fsm 仅保留在寄存器映射中，LL/HAL当前不对外提供debug控制接口。

• 结构体字段的精确类型、reserved数组维度和volatile属性以头文件为准。

6.2 寄存器和位域宏

6.3 寄存器访问约束

• 结构体成员使用 __IO / __I 保留volatile语义，直接访问如 ADC0->sr 不会被编译器优化成普通内存访问。

• FIFO寄存器 seq1_fifo / seq2_fifo 为读敏感寄存器，dump默认不读取，避免改变硬件FIFO状态；如需读取，由 HAL_ADC_DUMP_READ_FIFO 宏控制。

• AWD中断总状态清除通过 ADC_IR_AWD 操作ADC总中断状态，AWD各通道flag通过 awd_sr / awd_ir 相关接口处理。

• 当前SDK宏和结构体命名以 code/include/drivers/g32s10/adc/adc_regs.h 为准。

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

7.1 通道和序列长度

7.2 模式组合

7.3 SOC 额外周期

7.4 AWD 阈值

7.5 DMA 注意事项

• DMA模式只支持 SEQ1 和 SEQ2。

• ADC HAL已接入DMA控制器，DMA request使用 ADCx_SEQy_RX，bus width为32-bit，unit size为4字节。

• HAL_ADC_DMA_MODE_SINGLE 使用非descriptor DMA；HAL_ADC_DMA_MODE_CYCLIC 使用调用方提供的descriptor存储。

• DMA参数统一通过 hal_adc_sequence_config() 的 dma_enable/dma_buffer/dma_len/dma_mode/dma_desc/dma_desc_count 配置，不再提供独立的ADC DMA start/stop接口。

• 软件触发DMA统一使用 hal_adc_start() / hal_adc_start_multi()；需要ADC DMA完成/错误中断时使用对应的 *_it 接口。

• 当前DMA传输只能由统一start路径激活，因此DMA-enabled sequence必须使用软件触发；外部触发DMA当前没有公开的prepare-only启动入口。

• cyclic模式下 dma_desc 和 dma_desc_count 必须有效，descriptor存储必须保持有效直到该sequence重新配置或ADC deinit。

• hal_adc_stop() / hal_adc_stop_multi() 只停止当前DMA并保留配置，可直接再次start；重新配置同一sequence或deinit才释放DMA配置。

• DMA启动前HAL维护目标buffer cache，DMA完成中断中再次维护一次，停止路径（stop/deinit/重新配置）再维护一次，因此 stop 返回后可直接读取目标 buffer；DMA active 期间调用方不得写入该buffer，读取也可能读到部分更新的数据。

• SEQn_DMA_RCNT 可通过 hal_adc_dma_read_counter_get() 读取，软件可比较前后两次计数值判断进度；有效长度换算需要结合硬件计数单位并处理回绕。

7.6 实现约束

• LL层只做寄存器访问封装，公开接口均为 static inline，不依赖RTOS、不申请内存、不调用DMA驱动。

• HAL层当前依赖公共错误码、参数检查、日志组件、微秒时间基准、cache维护接口和DMA HAL；IRQ入口由BSP ISR调用。

• hal_adc_irq_handler() 先读取一次 ADC_IR 快照并处理错误；DMA完成flag在cache处理和回调前单独清除，其余已处理flag在本次IRQ末尾统一清除。

• 高频采样场景应优先使用 SEQ1/SEQ2 + DMA，避免CPU读取FIFO过慢导致 DATA_OVR；或者CPU模式下直接读取对应序列的数据寄存器。

7.7 状态迁移、错误锁存与恢复

HAL 运行状态是软件状态，活动序列则由 active_sequence_mask 单独跟踪。主要变化如下：

恢复说明：

• TIMEOUT 后应停止或重新配置目标序列；此后可以再次启动，但 HAL_ADC_ERROR_EOC_TIMEOUT 会保留在 error_code 中。

• 硬件错误进入 ERROR 后，当前公开接口没有单独清除错误状态的 API。完整恢复路径为 hal_adc_deinit()、hal_adc_handle_init()、重新设置配置并调用 hal_adc_init()。

• hal_adc_start*() 当前不会单独拒绝 ERROR 状态；应用不应依赖start接口完成错误恢复，必须先执行上述恢复流程。

• hal_adc_error_get() 只读取锁存值，不清除错误历史。

• DMA-enabled sequence 应通过DMA完成回调或相应等待逻辑判断传输结束。hal_adc_poll_for_conversion() 只观察sequence数据就绪状态，不替代DMA停止或完成处理。

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

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

7.9 回调与中断上下文

• hal_adc_irq_handler() 由BSP ISR调用，注册的sequence完成、DMA完成、AWD和error回调可能运行在ADC IRQ 上下文。

• 回调不得阻塞、睡眠、等待互斥锁或执行重日志；耗时处理应转交任务上下文。

• DMA完成flag在回调前清除，目标buffer在回调前执行cache invalidate；single DMA完成后HAL清除对应active状态，cyclic DMA保持active直到显式stop。

• AWD回调中的 low_flags / high_flags 已解码到bit7:0，分别对应通道0~7。

• 调用方需要通过 hadc->user_data 传递业务上下文，HAL不会解释该指针。

8. 示例程序与使用方式

8.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。

8.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);

8.3 SEQ1 多通道扫描中断模式

static void adc_seq1_done(hal_adc_handle_t *hadc)
{
    hal_adc_data_t data[8];

    (void)hal_adc_data_get(hadc, HAL_ADC_SEQUENCE_1, data, 8U);
}

hal_adc_sequence_config_t config = {0};

config.sequence = HAL_ADC_SEQUENCE_1;
config.trigger = HAL_ADC_TRIGGER_SOFTWARE;
config.data_ready_type = HAL_ADC_DRT_SEQUENCE_END;
config.channel_number_enable = 1U;
config.channel_count = 4U;
config.channel[0] = 0U;
config.channel[1] = 2U;
config.channel[2] = 5U;
config.channel[3] = 6U;
config.storage_mask = 0x0FU;
config.dma_enable = 0U;
config.continuous_enable = 0U;

hal_adc_sequence_config(&hadc0, &config);
hal_adc_callback_register(&hadc0, HAL_ADC_CALLBACK_SEQ1_COMPLETE, adc_seq1_done);
hal_adc_start_it(&hadc0, HAL_ADC_SEQUENCE_1);

8.4 SEQ1 连续组与 TCU 外部触发

hal_adc_sequence_config_t config = {0};

config.sequence = HAL_ADC_SEQUENCE_1;
config.trigger = HAL_ADC_TRIGGER_TCU;
config.data_ready_type = HAL_ADC_DRT_GROUP_END;
config.channel_number_enable = 1U;
config.channel_count = 8U;
config.continuous_enable = 1U;
config.group_count = 2U;
config.group_length[0] = 4U;
config.group_interval[0] = 100U;
config.group_length[1] = 4U;
config.group_interval[1] = 100U;

hal_adc_sequence_config(&hadc0, &config);

/* TCU/PWM外部触发模式不调用 hal_adc_start()；由外部触发源启动转换。 */

该片段省略了 channel[0..7] 的有效通道填充；实际配置必须为每个转换rank提供合法通道号。

本段只展示ADC侧配置。完整的TCU时钟、比较值和 HAL_ADC_TRIGGER_TCU 路由见tcu_trig_adc_example.c。

8.5 SEQ2 DMA 采样

static uint32_t adc_dma_buffer[256];
hal_adc_sequence_config_t config = {0};

static void adc_seq2_dma_done(hal_adc_handle_t *hadc)
{
    (void)hadc;
    /* adc_dma_buffer中保存本次DMA采样结果。 */
}

config.sequence = HAL_ADC_SEQUENCE_2;
config.trigger = HAL_ADC_TRIGGER_SOFTWARE;
config.data_ready_type = HAL_ADC_DRT_SEQUENCE_END;
config.channel_number_enable = 1U;
config.channel_count = 4U;
config.channel[0] = 0U;
config.channel[1] = 1U;
config.channel[2] = 2U;
config.channel[3] = 3U;
config.storage_mask = 0x0FU;
config.dma_enable = 1U;
config.dma_buffer = adc_dma_buffer;
config.dma_len = sizeof(adc_dma_buffer);
config.dma_mode = HAL_ADC_DMA_MODE_SINGLE;
config.dma_desc = NULL;
config.dma_desc_count = 0U;

hal_adc_sequence_config(&hadc0, &config);
hal_adc_callback_register(&hadc0,
                          HAL_ADC_CALLBACK_SEQ2_DMA_COMPLETE,
                          adc_seq2_dma_done);

/* start_it先配置DMA完成/错误中断，再由统一start路径启动DMA和ADC。 */
hal_adc_start_it(&hadc0, HAL_ADC_SEQUENCE_2);

单次SEQ1/SEQ2 DMA及中断流程见hal_adc_dma_example.c，多轮停止再启动和CPM时钟配置见hal_adc_dma_loop_example.c。

8.6 AWD 高低阈值检测

hal_adc_awd_config_t awd_config = {0};
uint32_t low_flags;
uint32_t high_flags;

awd_config.channel = 0U;
awd_config.low_threshold = 0x100U;
awd_config.high_threshold = 0xE00U;
awd_config.low_threshold_enable = 1U;
awd_config.high_threshold_enable = 1U;
awd_config.interrupt_enable = 1U;
awd_config.fail_enable = 1U;

hal_adc_awd_config(&hadc0, &awd_config);
hal_adc_awd_status_get(&hadc0, &low_flags, &high_flags);
hal_adc_awd_status_clear(&hadc0,
                         HAL_ADC_AWD_CHANNEL_FLAG(0U),
                         HAL_ADC_AWD_CHANNEL_FLAG(0U));

8.7 LL 寄存器级序列采样

adc_seq_example.c 的入口为example_adc_seq_sample_run()。该示例不链接ADC HAL，直接完成GPIO功能配置、PHY初始化、 时钟/优先级配置、SEQ0/SEQ1/SEQ2软件触发、状态轮询、packed数据解析和寄存器dump，适合用于确认 “HAL问题还是寄存器配置问题”。