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.hMID 公开宏、类型、设备对象定义与接口声明
code/middleware/adc/src/im_adc.cMID 初始化、序列/DMA 编排、轮询/中断/连续 DMA 路径、状态与诊断实现
code/middleware/adc/KconfigMIDDLEWARE_ADC 选项
code/middleware/adc/example/main/main.c示例入口:选择 ADC 实例和一个示例
code/middleware/adc/example/main/im_adc_example_*.cPolling/IRQ/DMA 的 SINGLE、FINITE、CONTINUOUS 独立示例
code/middleware/adc/example/main/im_adc_example_functional_test.cMID API 与硬件路径回归测试

code/middleware/adc/CMakeLists.txt 在 CONFIG_MIDDLEWARE_ADC 生效时编译 src/im_adc.c,并把 include/ 加入包含路径。

2. 资源模型与公开类型

2.1 实例与基地址

MID 以逻辑实例号选择 ADC 硬件:

逻辑实例硬件实例基地址宏基地址
IM_ADC_INSTANCE_0ADC0SADC0_IOBASE0x13720000UL
IM_ADC_INSTANCE_1ADC1SADC1_IOBASE0x13730000UL

说明:

  • 实例基地址和寄存器布局由 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_TCUTCU 外部触发;保留编码,当前 im_adc_start() 返回 IM_ERR_UNSUPPORTED。
IM_ADC_TRIGGER_PWM0PWM0 外部触发;保留编码,当前 im_adc_start() 返回 IM_ERR_UNSUPPORTED。
IM_ADC_TRIGGER_PWM1PWM1 外部触发;保留编码,当前 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_00
IM_ADC_SAMPLE_TIME_EXTRA_55
IM_ADC_SAMPLE_TIME_EXTRA_1010
IM_ADC_SAMPLE_TIME_EXTRA_1515
IM_ADC_SAMPLE_TIME_EXTRA_3030
IM_ADC_SAMPLE_TIME_EXTRA_4545
IM_ADC_SAMPLE_TIME_EXTRA_6060
IM_ADC_SAMPLE_TIME_EXTRA_210210

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_COMPLETESINGLE 或 FINITE 请求成功完成。
IM_ADC_EVENT_FRAME_READYCONTINUOUS 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_OVERRUNADC 数据存储或 FIFO 溢出。
IM_ADC_ERROR_EVENT_OVERRUN转换事件溢出。
IM_ADC_ERROR_PHYADC PHY 转换结束异常。
IM_ADC_ERROR_DMAADC DMA 传输或进度统计异常。
IM_ADC_ERROR_INTERNALMID 检测到活动请求执行失败。

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_flagsIM_ADC_ERROR_* 标志快照,对 ERROR 事件有效。
monitor_low_flagsbit n 对应通道 n 低于低阈值,对 MONITOR_LOW 事件有效。
monitor_high_flagsbit 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_countchannels[] 中有效项数,取值范围 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 运行模式与采集模式组合

采集模式运行模式转换序列说明
SINGLEPolling / IRQchannel_count <= 4 时 SEQ0,否则 SEQ1在调用线程或中断中采一帧后完成
SINGLEDMASEQ2单 descriptor 循环 DMA 搬运一帧,DMA 完成后停止
FINITEPolling / IRQ / DMASEQ2采满 sample_capacity 个样本后完成;IRQ 逐帧重启,DMA 逐帧停止并按偏移重配
CONTINUOUSDMASEQ1(连续组,1 组)一个覆盖整缓冲区的循环 descriptor;保持 BUSY 直到 stop、deinit 或错误
CONTINUOUSPolling / 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。

应用输入与可选配置

NODE  im_adc_t: 零初始化  地址在 init 到 deinit 之间保持固定
NODE  im_adc_config_t: instance, run_mode  adc_clock_div, sample_time
可选 event_callback 与 user_ctx
NODE  im_adc_request_t: mode, 软件触发  通道列表与 channel_count
输出缓冲区与容量
NODE  DMA 请求: 输出缓冲区 4 字节对齐  FINITE/CONTINUOUS 容量为通道数整数倍
NODE  可选监测配置:  channel, 阈值, fail 输出
NODE  线程接口: start 或 read, wait,  stop, deinit, 只读查询

MID 对象生命周期与所有权

NODE  RESET  不占用 HAL 资源或 ADC 实例
NODE  im_adc_init
NODE  init 是否成功?
NODE  清理 HAL; 释放 ADC 占用;  清零对象; 返回错误
NODE  READY  HAL 已初始化; 回调已注册;
占用一个 ADC 实例
NODE  可选 im_adc_monitor_config  仅 READY
NODE  im_adc_deinit  BUSY/ERROR 先 stop; 关闭 IRQ; 唤醒 waiter;
HAL deinit; 释放占用; 清零对象

请求执行

NODE  im_adc_start
NODE  im_adc_read  启动请求; 仅 IRQ/DMA 才等待
CONTINUOUS 被拒绝
NODE  状态为 READY; 请求合法;  触发源受支持?
NODE  复制请求; 清零样本计数与错误;  选择序列; 进入 BUSY
NODE  运行模式与采集模式
NODE  Polling SINGLE/FINITE  逐帧 start, poll, 读取
NODE  IRQ 或 DMA 的 SINGLE/FINITE  申请 ADC IRQ; start_it
NODE  仅 DMA CONTINUOUS  SEQ1 连续组 + 循环 DMA;
ADC IRQ 承载 DMA_FIN 进度与错误
NODE  BUSY  采样请求活动
NODE  im_adc_wait  同时只允许一个等待者
NODE  返回参数、状态或能力错误  已接受的请求不受影响
NODE  启动或配置失败

完成、错误与终结路径

NODE  ADC DMA_FIN  FIFO/DMA 进度通知
NODE  用 DMA 字节计数累计进度;  满一个完整缓冲区才计入样本
NODE  发布 FRAME_READY;  保持 BUSY 并继续循环 DMA
NODE  ADC 序列完成或 DMA 完成  帧数据已交付
NODE  FINITE 仍有剩余容量
NODE  重配下一帧 DMA  或重启下一帧 IRQ
NODE  wait 超时
NODE  ADC PHY、data/event overrun、  DMA 或内部失败
NODE  im_adc_finish 成功  原子领取终结权; 停止序列;
发布 COMPLETE; 唤醒 waiter; 释放请求字段
NODE  im_adc_finish 错误或超时  原子领取终结权; 停止序列;
发布 ERROR; 唤醒 waiter; 释放请求字段
NODE  ERROR  保留已初始化对象以便恢复

应用侧的恢复与释放

NODE  应用调用 im_adc_stop
NODE  停止序列; 关闭 ADC IRQ; 释放请求字段  BUSY: 发布 STOPPED 并回到 READY
ERROR: stop 成功时恢复到 READY
NODE  stop 是否成功?
NODE  HAL deinit 是否成功?
NODE  get_state, get_last_status,  get_error, get_sample_count,
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_TIMEOUTPolling 轮询或 im_adc_wait() 等待超时
IM_ERR_HARDWARE / IM_ERR_IOADC 运行期硬件或数据路径错误,以及 HAL 停止、HAL AWD 配置失败
运行期错误位说明
IM_ADC_ERROR_TIMEOUT采样超时(im_adc_wait() 超时或 HAL EOC 超时)
IM_ADC_ERROR_DATA_OVERRUNADC 数据存储或 FIFO 溢出
IM_ADC_ERROR_EVENT_OVERRUN转换事件溢出
IM_ADC_ERROR_PHYADC PHY 转换结束异常
IM_ADC_ERROR_DMAADC DMA 错误,或连续 DMA 字节进度增量异常
IM_ADC_ERROR_INTERNALMID 内部路径失败(样本搬运/重启失败、HAL 停止失败、启动阶段硬件或 IO 失败)