1. ADC v2

1.1. 概述

ADC v2 组件在 HPMicro ADC12 与 ADC16 外设之上提供统一 HAL，应用层无需再按 IP 分别调用 adc12_* / adc16_*。通过 HPM_ADC_V2_HANDLE(base) 创建句柄， hpm_adc_v2_get_ip_type 根据基地址在运行时识别 ADC12 或 ADC16。

在 sample 或应用的 CMakeLists.txt 中启用组件：

set(CONFIG_HPM_ADC_V2 1)

典型场景包括电机 FOC 抢占采样、序列 DMA 采集以及周期/单次转换。完整抢占 DMA 示例见 samples/motor_ctrl/bldc_foc。

1.2. 功能特性

统一实例句柄
- HPM_ADC_V2_HANDLE(base) 创建无状态的 adc_v2_handle_t
- hpm_adc_v2_get_ip_type 将 base 与 SoC HPM_ADCx_BASE 宏比对；非法地址返回 adc_v2_ip_unknown
- 双 IP SoC（HPM_ADC_V2_HAS_DUAL_IP）上 HPM_ADC3_BASE 对应 ADC16，其余合法 ADC 基地址对应 ADC12
转换模式（adc_v2_conv_mode_t）
- 单次：hpm_adc_v2_get_oneshot_result
- 周期：hpm_adc_v2_set_period_config 与 hpm_adc_v2_get_prd_result
- 序列：hpm_adc_v2_set_sequence_config、序列 DMA、软/硬件触发
- 抢占：hpm_adc_v2_set_preempt_config、抢占 DMA、电机 FOC 路径
编译期能力宏

在应用代码中按需开关可选特性：
- HPM_ADC_V2_HAS_ADC12 / HPM_ADC_V2_HAS_ADC16：SoC 是否包含对应 IP
- HPM_ADC_V2_HAS_DUAL_IP：同一 SoC 同时存在 ADC12 与 ADC16
- HPM_ADC_V2_HAS_SIGNAL_MODE：ADC12 单端/差分（signal_mode）
- HPM_ADC_V2_HAS_DIFF_MODE：ADC16 差分模式（通过 hpm_adc16_drv.h 配置）
- HPM_ADC_V2_HAS_ADC_LOOP：ADC16 通道过采样 loop
- HPM_ADC_V2_HAS_DMA_SEQ16BIT：ADC16 序列 DMA 仅 16 位输出
- HPM_ADC_V2_HAS_SEQ_STOP_POS_INT：ADC16 STOP_POS 中断位
- HPM_ADC_V2_HAS_MOTOR_MODE：ADC16 电机控制数据路径
中断与 DMA 辅助
- 统一的 adc_v2_event_t 事件掩码，用于状态查询、使能与清除
- hpm_adc_v2_parse_pmt_dma_word / hpm_adc_v2_parse_seq_dma_word 解析打包 DMA 字（ADC16 布局随 SoC IP 版本变化，勿在应用层写死位域）

1.3. 数据结构

主要结构体（定义于 hpm_adc_v2.h）：

adc_v2_handle_t
- base：外设基地址
adc_v2_config_t

实例配置：分辨率、转换模式、时钟分频及 IP 相关字段（ADC12 的 signal_mode， ADC16 的 port3_realtime / dma_seq16bit 等）。
adc_v2_channel_config_t

单通道采样时间、看门狗阈值及可选过采样（ADC16）。
adc_v2_pmt_config_t``（别名 ``adc_v2_preempt_config_t）

抢占触发槽位、通道映射及中断使能。
adc_v2_seq_config_t / adc_v2_dma_config_t

序列队列与 DMA 缓冲区配置（含 stop_pos / stop_en）。
adc_v2_dma_sample_t

DMA 解析 API 返回的语义化采样字段。

1.4. API 说明

1.4.1. 初始化

hpm_adc_v2_get_ip_type：根据句柄基地址识别 ADC12 / ADC16
hpm_adc_v2_get_default_config / hpm_adc_v2_get_channel_default_config：填充默认值
hpm_adc_v2_init / hpm_adc_v2_deinit：应用或撤销实例配置
hpm_adc_v2_init_channel：配置单个通道

1.4.2. 模式配置

hpm_adc_v2_set_period_config：周期模式时序
hpm_adc_v2_set_sequence_config：序列队列与触发
hpm_adc_v2_set_preempt_config：抢占（电机）触发映射
hpm_adc_v2_set_seq_stop_pos：序列 DMA 停止位置

1.4.3. DMA 与触发

hpm_adc_v2_init_pmt_dma / hpm_adc_v2_init_seq_dma：启动抢占或序列 DMA
hpm_adc_v2_is_seq_dma_16bit_enabled：查询 ADC16 16 位序列 DMA 模式
hpm_adc_v2_trigger_seq_by_sw / hpm_adc_v2_trigger_pmt_by_sw：软件触发
hpm_adc_v2_enable_pmt_queue / hpm_adc_v2_disable_pmt_queue：ADC16 队列控制

1.4.4. 结果与状态

hpm_adc_v2_get_oneshot_result / hpm_adc_v2_get_prd_result：读取转换结果
hpm_adc_v2_get_conv_valid_status：通道有效标志
hpm_adc_v2_get_status_flags / hpm_adc_v2_clear_status_flags
hpm_adc_v2_enable_interrupts / hpm_adc_v2_disable_interrupts
hpm_adc_v2_set_nonblocking_read / hpm_adc_v2_set_blocking_read

1.4.5. 电机控制（可选）

当 HPM_ADC_V2_HAS_MOTOR_MODE 为 1 时，在电机 FOC sample 中于抢占 DMA 配置完成后调用 hpm_adc_v2_enable_motor_mode。

1.5. 使用示例

抢占（电机 FOC）典型流程：

adc_v2_handle_t adc = HPM_ADC_V2_HANDLE(BOARD_BLDC_ADC_U_BASE);
adc_v2_config_t cfg;
adc_v2_channel_config_t ch_cfg;
adc_v2_pmt_config_t pmt_cfg;

hpm_adc_v2_get_default_config(adc, &cfg);
cfg.conv_mode = adc_v2_conv_mode_preemption;
hpm_adc_v2_init(adc, &cfg);

hpm_adc_v2_get_channel_default_config(adc, &ch_cfg);
ch_cfg.ch = BOARD_BLDC_ADC_CH_U;
ch_cfg.signal_mode = adc_v2_signal_mode_single_ended;
hpm_adc_v2_init_channel(adc, &ch_cfg);

hpm_adc_v2_set_preempt_config(adc, &pmt_cfg);
hpm_adc_v2_enable_pmt_queue(adc, BOARD_BLDC_ADC_TRG);
hpm_adc_v2_init_pmt_dma(adc, dma_buffer_sys_addr);
#if HPM_ADC_V2_HAS_MOTOR_MODE
hpm_adc_v2_enable_motor_mode(adc);
#endif
hpm_adc_v2_enable_interrupts(adc, HPM_ADC_V2_EVENT_TRIG_COMPLETE);

1.6. 相关 Sample

samples/motor_ctrl/bldc_foc：抢占 DMA 与 FOC 控制环
samples/motor_ctrl/ 下其他设置 CONFIG_HPM_ADC_V2 的电机 sample

1.7. 说明

新代码请使用 hpm_adc_v2.h，勿再依赖已弃用的 hpm_adc_interface 组件。
ADC12 差分输入通过 adc_v2_config_t 或 adc_v2_channel_config_t 中的 signal_mode 配置。
当 HPM_ADC_V2_HAS_DIFF_MODE 为 1 时，ADC16 差分请使用 hpm_adc16_drv.h 中的 API（参考 samples/drivers/adc/adc16_differential）。