API GUIDE / ADC / Middleware
G32S10 ADC Middleware 接口
Middleware 层接口:code/middleware/adc/CMakeLists.txt 在 CONFIG_MIDDLEWARE_ADC 生效时编译 src/im_adc.c,并把 include/ 加入包含路径。
1. 构建配置与文件组织
1.1 文件职责
| 文件 | 说明 |
|---|---|
code/middleware/adc/include/im_adc.h | MID 公开宏、类型、设备对象定义与接口声明 |
code/middleware/adc/src/im_adc.c | MID 初始化、序列/DMA 编排、轮询/中断/连续 DMA 路径、状态与诊断实现 |
code/middleware/adc/Kconfig | MIDDLEWARE_ADC 选项 |
code/middleware/adc/example/main/main.c | 示例入口:选择 ADC 实例和一个示例 |
code/middleware/adc/example/main/im_adc_example_*.c | Polling/IRQ/DMA 的 SINGLE、FINITE、CONTINUOUS 独立示例 |
code/middleware/adc/example/main/im_adc_example_functional_test.c | MID API 与硬件路径回归测试 |
code/middleware/adc/CMakeLists.txt 在 CONFIG_MIDDLEWARE_ADC 生效时编译 src/im_adc.c,并把 include/ 加入包含路径。
2. 资源模型与公开类型
2.1 实例与基地址
MID 以逻辑实例号选择 ADC 硬件:
| 逻辑实例 | 硬件实例 | 基地址宏 | 基地址 |
|---|---|---|---|
IM_ADC_INSTANCE_0 | ADC0 | SADC0_IOBASE | 0x13720000UL |
IM_ADC_INSTANCE_1 | ADC1 | SADC1_IOBASE | 0x13730000UL |
说明:
实例基地址和寄存器布局由
base.h/adc_regs.h定义,MID 只做逻辑实例到ADC0/ADC1的映射。一个逻辑实例在同一时刻只能被一个已初始化的 MID 对象绑定,重复绑定返回
IM_ERR_ALREADY_EXISTS。
2.2 MID 公开类型
本节按照 HAL/LL 文档“每个公开类型独立小节、类型定义与约束相邻”的组织方式说明 MID 类型。完整定义以 code/middleware/adc/include/im_adc.h 为准。
2.2.1 im_adc_t
typedef struct im_adc im_adc_t;
im_adc_t 是调用方持有的 MID 设备对象。对象必须零初始化,并在 im_adc_init() 到 im_adc_deinit() 期间保持地址不变;其内部字段由 MID 管理,应用不得读取、写入或复制活动对象。同一 ADC 实例同一时刻只能绑定一个已初始化的 MID 对象。
2.2.2 im_adc_instance_t
typedef enum {
IM_ADC_INSTANCE_0 = 0,
IM_ADC_INSTANCE_1,
} im_adc_instance_t;| 值 | 说明 |
|---|---|
IM_ADC_INSTANCE_0 | 逻辑 ADC0。 |
IM_ADC_INSTANCE_1 | 逻辑 ADC1。 |
2.2.3 im_adc_run_mode_t
typedef enum {
IM_ADC_RUN_MODE_POLLING = 0,
IM_ADC_RUN_MODE_IRQ,
IM_ADC_RUN_MODE_DMA,
} im_adc_run_mode_t;| 值 | 说明 |
|---|---|
IM_ADC_RUN_MODE_POLLING | 在调用线程内完成采样。 |
IM_ADC_RUN_MODE_IRQ | 通过 ADC 中断推进采样。 |
IM_ADC_RUN_MODE_DMA | 通过 DMA 把样本写入调用方缓冲区。 |
2.2.4 im_adc_acquisition_mode_t
typedef enum {
IM_ADC_ACQUISITION_SINGLE = 0,
IM_ADC_ACQUISITION_FINITE,
IM_ADC_ACQUISITION_CONTINUOUS,
} im_adc_acquisition_mode_t;| 值 | 说明 |
|---|---|
IM_ADC_ACQUISITION_SINGLE | 单帧;Polling/IRQ 在 channel_count <= 4 时使用 SEQ0,否则使用 SEQ1;DMA 使用 SEQ2。 |
IM_ADC_ACQUISITION_FINITE | 采满 sample_capacity 后结束;各运行模式均使用 SEQ2。 |
IM_ADC_ACQUISITION_CONTINUOUS | 循环覆盖调用方缓冲区;仅支持 DMA + SEQ1。 |
具体运行模式组合见 4.5 运行模式与采集模式组合。
2.2.5 im_adc_trigger_t
typedef enum {
IM_ADC_TRIGGER_SOFTWARE = 0,
IM_ADC_TRIGGER_TCU,
IM_ADC_TRIGGER_PWM0,
IM_ADC_TRIGGER_PWM1,
} im_adc_trigger_t;| 值 | 说明 |
|---|---|
IM_ADC_TRIGGER_SOFTWARE | 软件/寄存器触发,当前 MID 唯一支持的触发源。 |
IM_ADC_TRIGGER_TCU | TCU 外部触发;保留编码,当前 im_adc_start() 返回 IM_ERR_UNSUPPORTED。 |
IM_ADC_TRIGGER_PWM0 | PWM0 外部触发;保留编码,当前 im_adc_start() 返回 IM_ERR_UNSUPPORTED。 |
IM_ADC_TRIGGER_PWM1 | PWM1 外部触发;保留编码,当前 im_adc_start() 返回 IM_ERR_UNSUPPORTED。 |
2.2.6 im_adc_sample_time_t
typedef enum {
IM_ADC_SAMPLE_TIME_EXTRA_0 = 0,
IM_ADC_SAMPLE_TIME_EXTRA_5,
IM_ADC_SAMPLE_TIME_EXTRA_10,
IM_ADC_SAMPLE_TIME_EXTRA_15,
IM_ADC_SAMPLE_TIME_EXTRA_30,
IM_ADC_SAMPLE_TIME_EXTRA_45,
IM_ADC_SAMPLE_TIME_EXTRA_60,
IM_ADC_SAMPLE_TIME_EXTRA_210,
} im_adc_sample_time_t;| 值 | 增加的采样窗口周期 |
|---|---|
IM_ADC_SAMPLE_TIME_EXTRA_0 | 0 |
IM_ADC_SAMPLE_TIME_EXTRA_5 | 5 |
IM_ADC_SAMPLE_TIME_EXTRA_10 | 10 |
IM_ADC_SAMPLE_TIME_EXTRA_15 | 15 |
IM_ADC_SAMPLE_TIME_EXTRA_30 | 30 |
IM_ADC_SAMPLE_TIME_EXTRA_45 | 45 |
IM_ADC_SAMPLE_TIME_EXTRA_60 | 60 |
IM_ADC_SAMPLE_TIME_EXTRA_210 | 210 |
2.2.7 im_adc_state_t
typedef enum {
IM_ADC_STATE_RESET = 0,
IM_ADC_STATE_READY,
IM_ADC_STATE_BUSY,
IM_ADC_STATE_ERROR,
} im_adc_state_t;| 值 | 说明 |
|---|---|
IM_ADC_STATE_RESET | 未初始化、已 deinit 或对象无效。 |
IM_ADC_STATE_READY | 已初始化且空闲,可以接受请求。 |
IM_ADC_STATE_BUSY | 有采样请求正在进行。 |
IM_ADC_STATE_ERROR | 运行期失败,需要通过 stop 或 deinit 恢复。 |
状态迁移和恢复流程见 6.6 超时、错误与恢复。
2.2.8 im_adc_event_t
typedef enum {
IM_ADC_EVENT_COMPLETE = 0,
IM_ADC_EVENT_FRAME_READY,
IM_ADC_EVENT_STOPPED,
IM_ADC_EVENT_MONITOR_LOW,
IM_ADC_EVENT_MONITOR_HIGH,
IM_ADC_EVENT_ERROR,
} im_adc_event_t;| 值 | 说明 |
|---|---|
IM_ADC_EVENT_COMPLETE | SINGLE 或 FINITE 请求成功完成。 |
IM_ADC_EVENT_FRAME_READY | CONTINUOUS DMA 已写满一个完整缓冲区;缓冲区仍可能被循环 DMA 覆盖。仅 DMA 进度通知不会单独产生该事件。 |
IM_ADC_EVENT_STOPPED | 活动请求被应用提前停止。 |
IM_ADC_EVENT_MONITOR_LOW | 模拟看门狗检测到一个或多个低阈值越限。 |
IM_ADC_EVENT_MONITOR_HIGH | 模拟看门狗检测到一个或多个高阈值越限。 |
IM_ADC_EVENT_ERROR | 活动请求因运行期失败而终结。 |
2.2.9 im_adc_error_t
typedef enum {
IM_ADC_ERROR_NONE = 0U,
IM_ADC_ERROR_TIMEOUT = (1UL << 0U),
IM_ADC_ERROR_DATA_OVERRUN = (1UL << 1U),
IM_ADC_ERROR_EVENT_OVERRUN = (1UL << 2U),
IM_ADC_ERROR_PHY = (1UL << 3U),
IM_ADC_ERROR_DMA = (1UL << 4U),
IM_ADC_ERROR_INTERNAL = (1UL << 5U),
} im_adc_error_t;| 值 | 说明 |
|---|---|
IM_ADC_ERROR_NONE | 无运行期错误。 |
IM_ADC_ERROR_TIMEOUT | 采样超时。 |
IM_ADC_ERROR_DATA_OVERRUN | ADC 数据存储或 FIFO 溢出。 |
IM_ADC_ERROR_EVENT_OVERRUN | 转换事件溢出。 |
IM_ADC_ERROR_PHY | ADC PHY 转换结束异常。 |
IM_ADC_ERROR_DMA | ADC DMA 传输或进度统计异常。 |
IM_ADC_ERROR_INTERNAL | MID 检测到活动请求执行失败。 |
IM_ADC_ERROR_* 为可按位或的运行期错误标志。IM_ERR_INVALID_PARAM、IM_ERR_NOT_READY、IM_ERR_BUSY、IM_ERR_UNSUPPORTED 等参数或状态错误只通过 error_code_t 返回,不写入 error_flags;只有请求已被 MID 接受后的运行期异常才锁存错误位。
2.2.10 im_adc_event_info_t
typedef struct {
uint32_t sample_count;
uint32_t error_flags;
uint32_t monitor_low_flags;
uint32_t monitor_high_flags;
} im_adc_event_info_t;| 字段 | 说明 |
|---|---|
sample_count | 本次请求已交付的有效样本数;对 COMPLETE、FRAME_READY 和 ERROR 事件有效。CONTINUOUS 按完整缓冲区累计,可超过单个缓冲区容量。 |
error_flags | IM_ADC_ERROR_* 标志快照,对 ERROR 事件有效。 |
monitor_low_flags | bit n 对应通道 n 低于低阈值,对 MONITOR_LOW 事件有效。 |
monitor_high_flags | bit n 对应通道 n 高于高阈值,对 MONITOR_HIGH 事件有效。 |
im_adc_event_info_t 只在当前回调调用期间有效。应用需要在其它上下文使用这些字段时必须先复制;MID 在每次回调中重新构造快照,不保存历史事件。
2.2.11 im_adc_event_callback_t
typedef void (*im_adc_event_callback_t)(im_adc_t *dev, im_adc_event_t event, const im_adc_event_info_t *info, void *user_ctx);
Polling 完成回调在调用 im_adc_start() 或 im_adc_read() 的线程上下文执行;IRQ、DMA 和 monitor 回调在 ADC 中断上下文执行。回调必须满足 ISR 安全约束,不得阻塞、睡眠、等待锁、执行大块解码或输出大量日志,也不得在回调内调用 im_adc_start()、im_adc_read()、im_adc_wait()、im_adc_stop() 或 im_adc_deinit()。详见 6.5 回调上下文约束。
2.2.12 im_adc_config_t
typedef struct {
im_adc_instance_t instance;
im_adc_run_mode_t run_mode;
uint8_t adc_clock_div;
im_adc_sample_time_t sample_time;
im_adc_event_callback_t event_callback;
void *user_ctx;
} im_adc_config_t;| 字段 | 说明 |
|---|---|
instance | 绑定的逻辑 ADC 实例;同一实例同时只能被一个已初始化对象绑定。 |
run_mode | 结果交付方式;CONTINUOUS 请求要求 IM_ADC_RUN_MODE_DMA。 |
adc_clock_div | 初始化时传给 HAL 的 ADC 时钟分频值。 |
sample_time | 应用于每次转换的额外采样窗口周期。 |
event_callback | 可选事件回调;启用阈值比较时必须有回调,除非只使用 fail 输出。 |
user_ctx | 原样传给 event_callback 的应用上下文。 |
2.2.13 im_adc_request_t
typedef struct {
im_adc_acquisition_mode_t mode;
im_adc_trigger_t trigger;
uint8_t channel_count;
uint8_t channels[IM_ADC_MAX_CHANNELS_PER_REQUEST];
uint32_t *sample_buffer_out;
uint32_t sample_capacity;
} im_adc_request_t;| 字段 | 说明 |
|---|---|
mode | 请求生命周期:SINGLE 写一帧,FINITE 填满容量,CONTINUOUS 循环覆盖缓冲区直到 stop。 |
trigger | 转换触发源;im_adc_start() 当前只接受 IM_ADC_TRIGGER_SOFTWARE。 |
channel_count | channels[] 中有效项数,取值范围 1~8。 |
channels[] | 通道序列,channels[0..channel_count-1] 每项取值 0~7;允许重复但建议避免。 |
sample_buffer_out | 调用方提供的输出数组,必须保持有效且不被改写直到采样结束或 im_adc_stop() 返回;DMA 模式要求 4 字节对齐,cache 维护由 HAL 完成。 |
sample_capacity | 输出容量,单位是 uint32_t 样本项而不是字节;至少为 channel_count。SINGLE 只写 channel_count 项;FINITE 与 CONTINUOUS 要求为 channel_count 的整数倍,且 CONTINUOUS 还要求 DMA 运行模式。 |
sample_buffer_out 中每项只包含 12-bit ADC 值,对应通道为 channels[index % channel_count]。
2.2.14 im_adc_monitor_config_t
typedef struct {
uint8_t channel;
uint16_t low_threshold;
uint16_t high_threshold;
bool low_threshold_enable;
bool high_threshold_enable;
bool fail_enable;
} im_adc_monitor_config_t;| 字段 | 说明 |
|---|---|
channel | 被监测的 ADC 输入通道,取值 0~7。 |
low_threshold | 包含在内的低阈值,取值 0~4095,且不大于 high_threshold。 |
high_threshold | 包含在内的高阈值,取值 0~4095,且不小于 low_threshold。 |
low_threshold_enable | 使能低阈值比较和 MONITOR_LOW 通知。 |
high_threshold_enable | 使能高阈值比较和 MONITOR_HIGH 通知。 |
fail_enable | 使能硬件模拟看门狗 fail 输出。 |
2.3 运行模式与采集模式组合
| 采集模式 | 运行模式 | 转换序列 | 说明 |
|---|---|---|---|
SINGLE | Polling / IRQ | channel_count <= 4 时 SEQ0,否则 SEQ1 | 在调用线程或中断中采一帧后完成 |
SINGLE | DMA | SEQ2 | 单 descriptor 循环 DMA 搬运一帧,DMA 完成后停止 |
FINITE | Polling / IRQ / DMA | SEQ2 | 采满 sample_capacity 个样本后完成;IRQ 逐帧重启,DMA 逐帧停止并按偏移重配 |
CONTINUOUS | DMA | SEQ1(连续组,1 组) | 一个覆盖整缓冲区的循环 descriptor;保持 BUSY 直到 stop、deinit 或错误 |
CONTINUOUS | Polling / IRQ | — | 非法组合,im_adc_start() 返回 IM_ERR_INVALID_PARAM |
上表中 SINGLE 之外的采集模式都要求 sample_capacity 是 channel_count 的整数倍。
2.4 全生命周期与资源流程
下图描述 im_adc.c / im_adc.h 的对象生命周期。左侧是应用需要准备或可选择的输入,中间是 MID 的状态与请求执行,右侧是 ADC/线程事件。图中的 im_adc_finish() 是 MID 内部 helper,不是应用可直接调用的 API。
应用输入与可选配置
可选 event_callback 与 user_ctx
输出缓冲区与容量
MID 对象生命周期与所有权
占用一个 ADC 实例
HAL deinit; 释放占用; 清零对象
请求执行
CONTINUOUS 被拒绝
ADC IRQ 承载 DMA_FIN 进度与错误
完成、错误与终结路径
发布 COMPLETE; 唤醒 waiter; 释放请求字段
发布 ERROR; 唤醒 waiter; 释放请求字段
应用侧的恢复与释放
ERROR: stop 成功时恢复到 READY
get_dropped_frame_count
只读, 不改变状态
im_adc_t: 零初始化 → im_adc_init
im_adc_config_t: instance, run_mode → im_adc_init
im_adc_init → init 是否成功?
init 是否成功? → 清理 HAL; 释放 ADC 占用; · 否
init 是否成功? → READY · 是
可选监测配置: → 可选 im_adc_monitor_config
READY → 可选 im_adc_monitor_config
im_adc_request_t: mode, 软件触发 → im_adc_start
DMA 请求: 输出缓冲区 4 字节对齐 → im_adc_start
线程接口: start 或 read, wait, → im_adc_read
READY → im_adc_start
im_adc_read → im_adc_start
im_adc_start → 状态为 READY; 请求合法;
状态为 READY; 请求合法; → 返回参数、状态或能力错误 · 否
状态为 READY; 请求合法; → 复制请求; 清零样本计数与错误; · 是
启动或配置失败 → im_adc_finish 错误或超时
运行模式与采集模式 → Polling SINGLE/FINITE · Polling SINGLE/FINITE
Polling SINGLE/FINITE → ADC 序列完成或 DMA 完成
Polling SINGLE/FINITE → 启动或配置失败 · 轮询或读取失败
运行模式与采集模式 → IRQ 或 DMA 的 SINGLE/FINITE · IRQ 或 DMA SINGLE/FINITE
IRQ 或 DMA 的 SINGLE/FINITE → BUSY
IRQ 或 DMA 的 SINGLE/FINITE → 启动或配置失败 · 序列、IRQ、DMA 或启动失败
运行模式与采集模式 → 仅 DMA CONTINUOUS · DMA CONTINUOUS
仅 DMA CONTINUOUS → BUSY
仅 DMA CONTINUOUS → 启动或配置失败 · 配置或启动失败
BUSY → im_adc_wait
im_adc_wait → wait 超时 · 超时
IRQ 或 DMA 的 SINGLE/FINITE → ADC 序列完成或 DMA 完成
ADC 序列完成或 DMA 完成 → im_adc_finish 成功 · SINGLE 完成或 FINITE 已满
ADC 序列完成或 DMA 完成 → FINITE 仍有剩余容量 · FINITE 仍有剩余
重配下一帧 DMA → IRQ 或 DMA 的 SINGLE/FINITE
仅 DMA CONTINUOUS → ADC DMA_FIN
ADC DMA_FIN → 用 DMA 字节计数累计进度;
发布 FRAME_READY; → BUSY
BUSY → ADC PHY、data/event overrun、
ADC PHY、data/event overrun、 → im_adc_finish 错误或超时
im_adc_finish 成功 → READY
im_adc_finish 错误或超时 → ERROR
BUSY → 应用调用 im_adc_stop
ERROR → 应用调用 im_adc_stop
READY → 应用调用 im_adc_stop
应用调用 im_adc_stop → 停止序列; 关闭 ADC IRQ; 释放请求字段
stop 是否成功? → READY · 是
stop 是否成功? → ERROR · 否
READY → im_adc_deinit
BUSY → im_adc_deinit
ERROR → im_adc_deinit
im_adc_deinit → HAL deinit 是否成功?
HAL deinit 是否成功? → RESET · 是
HAL deinit 是否成功? → ERROR · 否
READY → get_state, get_last_status,
BUSY → get_state, get_last_status,
ERROR → get_state, get_last_status,
阅读约定:
READY表示对象已初始化并仍占有对应 ADC 实例;只有im_adc_deinit()成功才会解除占用并回到RESET。FRAME_READY不是终结事件。CONTINUOUS 每发布一帧仍保持BUSY,并且不会唤醒im_adc_wait()的等待者;应用必须在线程上下文调用im_adc_stop()或im_adc_deinit()。im_adc_finish()使用原子终结权解决 ISR 完成/错误回调与线程im_adc_wait()超时之间的竞争:只有领取成功的一方会停止硬件、写入最终状态并发终结事件。im_adc_stop()用于应用主动取消或从ERROR恢复;它不释放 HAL handle,也不解除实例占用。get_state、get_last_status、get_error、get_sample_count、get_dropped_frame_count都是只读查询,不改变状态,也不构成跨线程同步屏障。
3. 行为约束与实现说明
3.1 输出缓冲区格式与对齐
sample_buffer_out的每个uint32_t项只包含一个 12-bit 采样值(有效位[11:0],取值 0~4095);第index项对应的通道是channels[index % channel_count]。应用读取时应按 12-bit 有效位解释(例如value & 0x0FFF),不要依赖高位内容。MID 不向应用暴露 HAL 的 packed word:Polling/IRQ 路径直接取解包后的
value;DMA 的 SINGLE/FINITE 路径由 HAL 写入带通道号的 packed 数据,MID 在完成回调中剥离通道号并只保留 12-bit 值;CONTINUOUS 路径在 HAL 配置中关闭通道号嵌入,DMA 直接把值写入调用方缓冲区,MID 不做二次处理。样本顺序按帧重复:每帧依次写入
channels[0..channel_count-1](允许重复通道,重复时对应多项采样值)。DMA 模式要求缓冲区地址 4 字节对齐,并要求
sample_capacity * 4不超过UINT32_MAX;其它模式没有额外的对齐要求。缓冲区必须保持有效,直到收到
COMPLETE/ERROR/STOPPED事件或im_adc_wait()返回;CONTINUOUS 模式下必须保持到im_adc_stop()返回。cache 维护由 HAL 负责:启动前清理,DMA 完成时失效,停止/重配时再维护一次,因此 stop 返回后调用方可以直接读取缓冲区。
3.2 回调上下文约束
Polling 的完成回调在调用
im_adc_start()/im_adc_read()的线程上下文执行;IRQ、DMA 和 monitor 回调在 ADC 中断上下文执行。所有回调都必须满足 ISR 约束:不得阻塞、sleep、等待锁、执行大块解码或输出大量日志。
不得从回调中调用
im_adc_start()、im_adc_read()、im_adc_wait()、im_adc_stop()或im_adc_deinit();应向线程投递消息后再操作。info只在本次回调期间有效;需要跨上下文使用时必须复制字段。event_callback为空时 MID 不发布任何事件,但状态、last_status、error_flags和sample_count仍会正常更新。
4. 典型用法
4.1 轮询单帧同步采样
error_code_t ret;
im_adc_t adc = {0};
im_adc_config_t config;
im_adc_request_t request;
uint32_t samples[3];
im_adc_config_struct_init(&config);
config.instance = IM_ADC_INSTANCE_0;
config.run_mode = IM_ADC_RUN_MODE_POLLING;
im_adc_request_struct_init(&request);
request.mode = IM_ADC_ACQUISITION_SINGLE;
request.trigger = IM_ADC_TRIGGER_SOFTWARE;
request.channel_count = 3U;
request.channels[0] = 0U;
request.channels[1] = 3U;
request.channels[2] = 7U;
request.sample_buffer_out = samples;
request.sample_capacity = 3U;
ret = im_adc_init(&adc, &config);
if (ret == IM_OK) {
ret = im_adc_read(&adc, &request, 10U);
}
(void)im_adc_deinit(&adc);samples[0]、samples[1]、samples[2] 分别对应通道 0、3、7,每项只有 12-bit 采样值。
4.2 中断有限采样
static im_adc_t adc = {0};
static uint32_t samples[8] __attribute__((aligned(4)));
static void adc_event_callback(im_adc_t *dev,
im_adc_event_t event,
const im_adc_event_info_t *info,
void *user_ctx)
{
if (event == IM_ADC_EVENT_ERROR) {
/* 只记录快照,不在 ISR 中阻塞或调用 MID 控制接口。 */
volatile uint32_t flags = info->error_flags;
(void)flags;
}
}
error_code_t adc_irq_finite_sample(void)
{
error_code_t ret;
im_adc_config_t config;
im_adc_request_t request;
im_adc_config_struct_init(&config);
config.instance = IM_ADC_INSTANCE_0;
config.run_mode = IM_ADC_RUN_MODE_IRQ;
config.event_callback = adc_event_callback;
ret = im_adc_init(&adc, &config);
if (ret != IM_OK) {
return ret;
}
im_adc_request_struct_init(&request);
request.mode = IM_ADC_ACQUISITION_FINITE;
request.channel_count = 2U;
request.channels[0] = 0U;
request.channels[1] = 1U;
request.sample_buffer_out = samples;
request.sample_capacity = 8U; /* 4 帧 × 2 通道 */
ret = im_adc_start(&adc, &request);
if (ret == IM_OK) {
ret = im_adc_wait(&adc, 1000U);
}
return ret; /* 成功时 samples[] 已按 [CH0, CH1] 交错填充 8 项 */
}im_adc_wait() 返回 IM_OK 时输出缓冲区已填满;返回 IM_ERR_TIMEOUT、IM_ERR_HARDWARE 或其它错误时,应根据 im_adc_get_error() 与 im_adc_get_state() 判断是否需要 stop 或 deinit 恢复。
4.3 DMA 连续采样
static im_adc_t adc = {0};
static uint32_t sample_buffer[256] __attribute__((aligned(4)));
error_code_t ret;
im_adc_config_t config;
im_adc_request_t request;
im_adc_config_struct_init(&config);
config.instance = IM_ADC_INSTANCE_0;
config.run_mode = IM_ADC_RUN_MODE_DMA;
config.event_callback = adc_event_callback; /* 只记录 FRAME_READY/ERROR 快照 */
config.user_ctx = &application_context;
im_adc_request_struct_init(&request);
request.mode = IM_ADC_ACQUISITION_CONTINUOUS;
request.channel_count = 2U;
request.channels[0] = 1U;
request.channels[1] = 2U;
request.sample_buffer_out = sample_buffer;
request.sample_capacity = 256U;
ret = im_adc_init(&adc, &config);
if (ret == IM_OK) {
ret = im_adc_start(&adc, &request);
}
/* 线程等待 FRAME_READY 通知后再复制或处理完整缓冲区;
* 结束时在同一个线程中调用 im_adc_stop() 和 im_adc_deinit()。 */sample_buffer 必须 4 字节对齐,并保持有效直到 im_adc_stop() 返回。每个完整缓冲区对应 128 帧 [通道 1, 通道 2] 样本;IM_ADC_EVENT_FRAME_READY 只表示一整轮缓冲区已经写入,DMA 会继续循环覆盖该缓冲区。
4.4 模拟看门狗监测
im_adc_monitor_config_t monitor; im_adc_monitor_config_struct_init(&monitor); monitor.channel = 0U; monitor.low_threshold = 0x100U; monitor.high_threshold = 0xE00U; monitor.low_threshold_enable = true; monitor.high_threshold_enable = true; monitor.fail_enable = false; (void)im_adc_monitor_config(&adc, &monitor);
该配置要求设备已初始化且处于 READY,且 im_adc_config_t.event_callback 非空;越限时应用会收到 IM_ADC_EVENT_MONITOR_LOW / IM_ADC_EVENT_MONITOR_HIGH,事件快照的 monitor_low_flags / monitor_high_flags 给出对应的通道位。
5. MID 错误码与错误标志
MID 接口使用 SDK 公共错误码类型 error_code_t,并通过 im_adc_event_info_t.error_flags / im_adc_get_error() 提供运行期错误位。
| 公共错误码 | 出现场景 |
|---|---|
IM_OK | 操作成功 |
IM_ERR_INVALID_PARAM | 空指针、枚举非法、通道/阈值越界、缓冲区或容量不合法、非法的模式组合 |
IM_ERR_NOT_READY | 对象未初始化、处于 ERROR、请求被 stop 取消,或 last_status 记录到的初始状态 |
IM_ERR_BUSY | 已有采样请求在执行,或已有另一个线程在等待同一设备 |
IM_ERR_ALREADY_EXISTS | 对象不是 RESET,或所选 ADC 实例已被占用 |
IM_ERR_NO_DEVICE | 所选逻辑实例未映射到可用 ADC 外设 |
IM_ERR_UNSUPPORTED | 非软件触发;im_adc_read() 收到 CONTINUOUS 请求;BUSY 的 CONTINUOUS 请求调用 im_adc_wait();HAL dump 未编译 |
IM_ERR_TIMEOUT | Polling 轮询或 im_adc_wait() 等待超时 |
IM_ERR_HARDWARE / IM_ERR_IO | ADC 运行期硬件或数据路径错误,以及 HAL 停止、HAL AWD 配置失败 |
| 运行期错误位 | 说明 |
|---|---|
IM_ADC_ERROR_TIMEOUT | 采样超时(im_adc_wait() 超时或 HAL EOC 超时) |
IM_ADC_ERROR_DATA_OVERRUN | ADC 数据存储或 FIFO 溢出 |
IM_ADC_ERROR_EVENT_OVERRUN | 转换事件溢出 |
IM_ADC_ERROR_PHY | ADC PHY 转换结束异常 |
IM_ADC_ERROR_DMA | ADC DMA 错误,或连续 DMA 字节进度增量异常 |
IM_ADC_ERROR_INTERNAL | MID 内部路径失败(样本搬运/重启失败、HAL 停止失败、启动阶段硬件或 IO 失败) |