跳转至
项目
版本
全文检索

ADC

ADC（Analog-to-Digital Converter）提供模拟信号到数字信号的转换能力。输入时钟 32MHz，12bit 分辨率，单通道采样率最大为 1Msps。共 6 个通道，支持软件配置 0～5 任意通道使能，逻辑按通道编号先低后高发起切换，完成单通道采样并完成平均值滤波后自动进行通道切换。支持 128×17bit FIFO 用于数据缓存，数据存储格式：高 3bit 为通道编号，低 14bit 为有效数据。支持对 ADC 采样数据进行平均滤波处理，平均次数支持 1（不进行平均）、2、4、8；多通道时，每个通道接收 N 个数据（平均滤波个数）再切换通道。支持 FIFO 水线中断、满中断上报，ADC 忙状态、控制器 FIFO 空满状态查询。

模块公共头文件

#include "include/driver/adc.h"

接口清单

接口名称 功能简述
uapi_adc_init 初始化 ADC
uapi_adc_deinit 去初始化 ADC
uapi_adc_power_en ADC 上电/下电并使能/关闭
uapi_adc_is_using 查询 ADC 是否正在使用
uapi_adc_open_channel 打开一个 ADC 通道
uapi_adc_close_channel 关闭一个 ADC 通道
uapi_adc_auto_scan_ch_enable 启用单通道自动扫描
uapi_adc_auto_scan_ch_disable 禁用单通道自动扫描
uapi_adc_auto_scan_disable 禁用全部自动扫描并下电 ADC
uapi_adc_auto_scan_is_enabled 查询自动扫描是否已使能
uapi_adc_manual_sample 触发 ADC 手动采样

Functions

uapi_adc_init 

errcode_t uapi_adc_init(adc_clock_t clock)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 初始化 ADC 模块。
  • ADC 已完成初始化时再次调用直接返回成功。
  • 成功初始化后本模块其他接口方可使用。

前置条件

  • 调用时序约束：当前接口为 ADC 模块入口接口，须在其他 ADC 接口之前调用。
  • 依赖关系：当前接口依赖 ADC 时钟与复位资源已就绪。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
clock adc_clock_t 采样时钟参数。当前芯片版本上此参数不影响实际采样时钟配置 adc_clock_t 全体成员

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 操作成功，或 ADC 已完成初始化
Other 其他错误码，参考errcode_t HAL 初始化失败

参考案例

  • src/application/samples/peripheral/adc/adc_demo.c
  • src/application/samples/peripheral/adc/adc_demo_inc.c

uapi_adc_deinit 

errcode_t uapi_adc_deinit(void)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 去初始化 ADC。
  • 关闭 ADC 时钟。
  • ADC 尚未初始化时直接返回成功。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 操作成功，或 ADC 尚未初始化
Other 其他错误码，参考errcode_t HAL 去初始化失败

参考案例

  • src/application/samples/peripheral/adc/adc_demo_inc.c

uapi_adc_power_en 

void uapi_adc_power_en(afe_scan_mode_t afe_scan_mode, bool en)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 对 ADC 执行上电或下电。
  • 选择 AFE 模拟前端精度模式（常规精度/高精度/麦克风/生物测量）。
  • 在启用高精度模式（CONFIG_ADC_SUPPORT_AFE 且 CONFIG_ADC_SUPPORT_HAFE）时管理各 AFE 模式的电源状态。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化且 HAL 函数指针表已注册。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
afe_scan_mode afe_scan_mode_t AFE 模拟前端精度模式 afe_scan_mode_t 全体成员
en bool 上电或下电标志，true 表示上电，false 表示下电 true；
false。

参考案例

  • src/application/samples/peripheral/adc/adc_demo.c

uapi_adc_is_using 

bool uapi_adc_is_using(void)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 查询 ADC 是否处于使用（已上电）状态。
  • 在启用高精度模式（CONFIG_ADC_SUPPORT_AFE 且 CONFIG_ADC_SUPPORT_HAFE）时综合判断常规精度与高精度两种 AFE 模式的电源状态。
  • 返回当前 ADC 电源占用情况。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化。
  • 上下文限制：当前接口可在中断或主线程调用。

返回值

返回类型：bool

返回值 文字含义 触发场景
true 使用中 ADC 已上电
false 未使用 ADC 未上电

uapi_adc_open_channel 

errcode_t uapi_adc_open_channel(uint8_t channel)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 打开指定的 ADC 通道。
  • 在自动扫描已使能时拒绝打开通道。
  • 记录当前正在工作的通道号。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 与 uapi_adc_power_en 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已上电、自动扫描未使能。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
channel uint8_t ADC 通道号 0 ~ 7（实现中以 ADC_CHANNEL_MAX_NUM(8) 为上界校验，channel < 8）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 通道打开成功
ERRCODE_ADC_INVALID_PARAMETER：0x80001141 参数无效 channel 大于等于 ADC_CHANNEL_MAX_NUM
ERRCODE_ADC_SCAN_NOT_DISABLE：0x80001142 自动扫描未禁用 自动扫描已使能时调用（CONFIG_ADC_SUPPORT_AUTO_SCAN 启用时）
Other 其他错误码，参考errcode_t HAL 通道设置失败

uapi_adc_close_channel 

errcode_t uapi_adc_close_channel(uint8_t channel)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 关闭指定的 ADC 通道。
  • 校验入参通道与当前工作通道一致性。
  • 在自动扫描已使能时拒绝关闭通道。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_open_channel 成功打开通道后调用。
  • 依赖关系：当前接口依赖 ADC 已上电、自动扫描未使能、入参通道与当前工作通道一致。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
channel uint8_t ADC 通道号，须与当前工作通道一致 0 ~ 7（须等于已打开的工作通道）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 通道关闭成功
ERRCODE_ADC_INVALID_PARAMETER：0x80001141 参数无效 channel 与当前工作通道不一致
ERRCODE_ADC_SCAN_NOT_DISABLE：0x80001142 自动扫描未禁用 自动扫描已使能时调用（CONFIG_ADC_SUPPORT_AUTO_SCAN 启用时）
Other 其他错误码，参考errcode_t HAL 通道设置失败

uapi_adc_auto_scan_ch_enable 

errcode_t uapi_adc_auto_scan_ch_enable(uint8_t channel, adc_scan_config_t config, adc_callback_t callback)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 启用指定 ADC 通道的自动扫描（FIFO 全扫描或阈值扫描）。
  • 配置扫描类型、扫描频率、阈值上下限等扫描参数。
  • 注册自动扫描中断回调函数。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 与 uapi_adc_power_en 成功返回后调用，且 ADC 已上电。
  • 依赖关系：当前接口依赖 ADC 已上电、CONFIG_ADC_SUPPORT_AUTO_SCAN 已启用、callback 不为 NULL。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
channel uint8_t ADC 通道号 0 ~ 7（实现中以 ADC_CHANNEL_MAX_NUM(8) 为上界校验，channel < 8）
config adc_scan_config_t 自动扫描配置（FIFO 全扫描或阈值扫描），含扫描类型、频率、阈值 config.type ≤ 1；config.freq < 8（0 ~ 7）
callback adc_callback_t 自动扫描中断回调函数指针 不为 NULL

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 自动扫描通道启用成功
ERRCODE_ADC_INVALID_PARAMETER：0x80001141 参数无效 channel、config.type、config.freq 非法或 callback 为 NULL
ERRCODE_PWM_NOT_POWER_ON：0x80001084 ADC 未上电 ADC 未上电（adc_is_power_on 为 false）时调用
Other 其他错误码，参考errcode_t HAL 通道扫描配置失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_ADC_SUPPORT_AUTO_SCAN 特性宏 支持自动扫描接口功能（接口级，头文件中包裹函数声明） y
CONFIG_ADC_SUPPORT_LONG_SAMPLE 特性宏 支持长采样上报周期特性（分支级，控制 config.long_sample_time 成员存在性） n

uapi_adc_auto_scan_ch_disable 

errcode_t uapi_adc_auto_scan_ch_disable(uint8_t channel)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 禁用指定 ADC 通道的自动扫描。
  • 校验入参通道号有效性。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_auto_scan_ch_enable 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化、CONFIG_ADC_SUPPORT_AUTO_SCAN 已启用。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
channel uint8_t ADC 通道号 0 ~ 7（实现中以 ADC_CHANNEL_MAX_NUM(8) 为上界校验，channel < 8）

返回值

返回类型：errcode_t

返回值 文字含义 触发场景
ERRCODE_SUCC：0 成功执行 自动扫描通道禁用成功
ERRCODE_ADC_INVALID_PARAMETER：0x80001141 参数无效 channel 大于等于 ADC_CHANNEL_MAX_NUM
Other 其他错误码，参考errcode_t HAL 通道禁用失败

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_ADC_SUPPORT_AUTO_SCAN 特性宏 支持自动扫描接口功能（接口级，头文件中包裹函数声明） y

uapi_adc_auto_scan_disable 

void uapi_adc_auto_scan_disable(void)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 禁用 ADC 自动扫描总控制。
  • 关闭所有扫描通道。
  • 关闭 ADC 电源。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_auto_scan_ch_enable 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化、CONFIG_ADC_SUPPORT_AUTO_SCAN 已启用。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_ADC_SUPPORT_AUTO_SCAN 特性宏 支持自动扫描接口功能（接口级，头文件中包裹函数声明） y

uapi_adc_auto_scan_is_enabled 

bool uapi_adc_auto_scan_is_enabled(void)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 查询 ADC 自动扫描总控制是否已使能。
  • 返回当前自动扫描使能状态。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化、CONFIG_ADC_SUPPORT_AUTO_SCAN 已启用。
  • 上下文限制：当前接口可在中断或主线程调用。

返回值

返回类型：bool

返回值 文字含义 触发场景
true 已使能 自动扫描总控制已使能
false 未使能 自动扫描总控制未使能

Kconfig配置

配置项 宏类型 说明 默认值
CONFIG_ADC_SUPPORT_AUTO_SCAN 特性宏 支持自动扫描接口功能（接口级，头文件中包裹函数声明） y

uapi_adc_manual_sample 

int32_t uapi_adc_manual_sample(uint8_t channel)

声明头文件

#include "include/driver/adc.h"

功能说明

  • 触发 ADC 手动采样。
  • 校验入参通道号有效性。
  • 返回 ADC 采样值。

前置条件

  • 调用时序约束：当前接口必须在 uapi_adc_init 与 uapi_adc_open_channel 成功返回后调用。
  • 依赖关系：当前接口依赖 ADC 已初始化、目标通道已打开。
  • 上下文限制：当前接口需在主线程调用，禁止在中断上下文调用。

入参

名称 参数类型 说明 约束取值范围
channel uint8_t ADC 通道号 0 ~ 7（实现中以 ADC_CHANNEL_MAX_NUM(8) 为上界校验，channel < 8）

返回值

返回类型：int32_t

返回值 文字含义 触发场景
采样值 ADC 采样值 通道号有效，采样成功
0 采样失败 channel 大于等于 ADC_CHANNEL_MAX_NUM

Type definitions

typedef_adc_callback_t 

typedef void (*adc_callback_t)(uint8_t channel, uint32_t *buffer, uint32_t length, bool *next);

使用说明

  • 用于 uapi_adc_auto_scan_ch_enable 的入参 callback，作为 ADC 自动扫描中断回调函数指针类型。
  • 参数 channel：自动扫描通道号（入参）。
  • 参数 buffer：自动扫描采样结果存放缓冲区（出参）。
  • 参数 length：扫描失败时长度为 0；FIFO 全扫描时长度为 128；阈值扫描时长度为 1（入参）。
  • 参数 next：继续自动扫描或停止自动扫描（出参）。

typedef_errcode_t 

// 源码原始定义
typedef uint32_t errcode_t;

使用说明

  • 本模块返回类型为 errcode_t 的对外接口的返回值类型。

Enumerations

enum_adc_clock 

// 源码原始定义，无修改、无补充
typedef enum adc_clock {
    ADC_CLOCK_500KHZ = 0,               /*!< ADC时钟频率： 500KHZ。  */
    ADC_CLOCK_250KHZ = 1,               /*!< ADC时钟频率： 250KHZ。  */
    ADC_CLOCK_125KHZ = 2,               /*!< ADC时钟频率： 125KHZ。  */
    ADC_CLOCK_015KHZ = 3,               /*!< ADC时钟频率： 015KHZ。  */
    ADC_CLOCK_MAX,
    ADC_CLOCK_NONE = ADC_CLOCK_MAX
} adc_clock_t;
枚举成员 取值 描述
ADC_CLOCK_500KHZ 0 ADC 时钟频率：500KHZ
ADC_CLOCK_250KHZ 1 ADC 时钟频率：250KHZ
ADC_CLOCK_125KHZ 2 ADC 时钟频率：125KHZ
ADC_CLOCK_015KHZ 3 ADC 时钟频率：015KHZ
ADC_CLOCK_MAX 4 ADC 时钟枚举上限
ADC_CLOCK_NONE 4 ADC 时钟未指定（等同 ADC_CLOCK_MAX）

enum_afe_scan_mode 

// 源码原始定义，无修改、无补充
typedef enum afe_scan_mode {
    AFE_GADC_MODE = 0,                  /*!< 模拟前端ADC常规精度模式。 */
#if defined (CONFIG_ADC_SUPPORT_HAFE)
    AFE_HADC_MODE,                      /*!< 模拟前端ADC高精度模式。 */
#elif (defined CONFIG_ADC_SUPPORT_AMIC)
    AFE_AMIC_MODE,                      /*!< 模拟前端ADC麦克风模式。 */
    AFE_BIO_MODE,                      /*!< 模拟前端ADC生物测量模式。 */
#endif
    AFE_SCAN_MODE_MAX_NUM
} afe_scan_mode_t;
枚举成员 取值 描述
AFE_GADC_MODE 0 模拟前端 ADC 常规精度模式
AFE_HADC_MODE 1 模拟前端 ADC 高精度模式（CONFIG_ADC_SUPPORT_HAFE 启用时存在）
AFE_AMIC_MODE 1 模拟前端 ADC 麦克风模式（CONFIG_ADC_SUPPORT_AMIC 启用且 CONFIG_ADC_SUPPORT_HAFE 未启用时存在）
AFE_BIO_MODE 2 模拟前端 ADC 生物测量模式（CONFIG_ADC_SUPPORT_AMIC 启用且 CONFIG_ADC_SUPPORT_HAFE 未启用时存在）
AFE_SCAN_MODE_MAX_NUM 1 / 2 / 3 模拟前端扫描模式枚举上限（取值随条件编译配置而定：仅 GADC 时为 1；HAFE 启用时为 2；AMIC 启用时为 3）

Structures

struct_adc_scan_config 

// 源码原始定义，保留注释
typedef struct adc_scan_config {
    uint8_t type;                       /*!< FIFO全扫描或阈值扫描。 */
    float threshold_l;                  /*!< 阈值扫描电压（v）下限。 */
    float threshold_h;                  /*!< 阈值扫描电压（v）上限。 */
    uint8_t freq;                       /*!< ADC扫描频率，用于所有频道。 */
#if defined(CONFIG_ADC_SUPPORT_LONG_SAMPLE)
    uint32_t long_sample_time;           /*!< ADC长采样上报周期（单位：毫秒）。 */
#endif
} adc_scan_config_t;

成员说明

成员名称 数据类型 描述
type uint8_t FIFO 全扫描或阈值扫描（0：FIFO 全扫描；1：阈值扫描）
threshold_l float 阈值扫描电压（v）下限
threshold_h float 阈值扫描电压（v）上限
freq uint8_t ADC 扫描频率，用于所有通道（取值范围 0 ~ 7）
long_sample_time uint32_t ADC 长采样上报周期（单位 ms），仅在 CONFIG_ADC_SUPPORT_LONG_SAMPLE 启用时存在

Macros

ERRCODE_ADC_INVALID_PARAMETER 

#define ERRCODE_ADC_INVALID_PARAMETER                       0x80001141

ERRCODE_ADC_SCAN_NOT_DISABLE 

#define ERRCODE_ADC_SCAN_NOT_DISABLE                        0x80001142

ERRCODE_PWM_NOT_POWER_ON 

#define ERRCODE_PWM_NOT_POWER_ON                            0x80001084

ERRCODE_SUCC 

#define ERRCODE_SUCC                                        0UL