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"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化 ADC |
|
去初始化 ADC |
|
ADC 上电/下电并使能/关闭 |
|
查询 ADC 是否正在使用 |
|
打开一个 ADC 通道 |
|
关闭一个 ADC 通道 |
|
启用单通道自动扫描 |
|
禁用单通道自动扫描 |
|
禁用全部自动扫描并下电 ADC |
|
查询自动扫描是否已使能 |
|
触发 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 全体成员 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
操作成功,或 ADC 已完成初始化 |
|
Other |
其他错误码,参考errcode_t |
HAL 初始化失败 |
参考案例
src/application/samples/peripheral/adc/adc_demo.csrc/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
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
操作成功,或 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 模拟前端精度模式 |
afe_scan_mode_t 全体成员 |
|
en |
bool |
上电或下电标志,true 表示上电,false 表示下电 |
true; |
参考案例
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_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_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 |
自动扫描配置(FIFO 全扫描或阈值扫描),含扫描类型、频率、阈值 |
config.type ≤ 1;config.freq < 8(0 ~ 7) |
|
callback |
自动扫描中断回调函数指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
成功执行 |
自动扫描通道启用成功 |
|
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_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