G32S10 ADC Middleware 接口

5. 接口规范

5.1 初始化与默认值

5.1.1 im_adc_config_struct_init

void im_adc_config_struct_init(im_adc_config_t *config);

功能说明： 把设备配置结构体填充为默认值，不访问硬件。

参数表：

返回值表：

补充说明：

• 只允许在线程上下文调用，不访问硬件，也不修改 im_adc_t 对象。
• 默认值：instance = IM_ADC_INSTANCE_0、run_mode = IM_ADC_RUN_MODE_POLLING、adc_clock_div = HAL_ADC_DEFAULT_CLK_DIV、sample_time = IM_ADC_SAMPLE_TIME_EXTRA_0、event_callback = NULL、user_ctx = NULL。
• 应先调用本接口再覆盖所需字段，以兼容后续新增字段。

5.1.2 im_adc_request_struct_init

void im_adc_request_struct_init(im_adc_request_t *request);

功能说明： 把采样请求填充为默认值，不访问硬件。

参数表：

返回值表：

补充说明：

• 只允许在线程上下文调用，不修改 im_adc_t 对象。
• 默认值：mode = IM_ADC_ACQUISITION_SINGLE、trigger = IM_ADC_TRIGGER_SOFTWARE、channel_count = 1、channels[0] = 0、sample_buffer_out = NULL、sample_capacity = 0。
• 默认请求不能直接启动；调用方必须提供输出缓冲区与容量。每次提交请求前建议重新初始化，避免复用上一次的缓冲区或采集模式。

5.1.3 im_adc_monitor_config_struct_init

void im_adc_monitor_config_struct_init(im_adc_monitor_config_t *config);

功能说明： 把模拟看门狗监测配置填充为默认值，不访问硬件。

参数表：

返回值表：

补充说明：

• 只允许在线程上下文调用。
• 默认值：channel = 0、low_threshold = 0、high_threshold = HAL_ADC_THRESHOLD_MAX（0x0FFF）、low_threshold_enable、high_threshold_enable、fail_enable 均为 false。
• 默认配置等价于关闭该通道监测，不会产生 monitor 事件。

5.1.4 im_adc_init

error_code_t im_adc_init(im_adc_t *dev,
                         const im_adc_config_t *config);

功能说明： 初始化一个 ADC MID 对象并绑定逻辑 ADC 实例，使状态从 IM_ADC_STATE_RESET 进入 IM_ADC_STATE_READY。

参数表：

返回值表：

补充说明：

• 只能在线程上下文调用，会初始化同步资源和 ADC 硬件，禁止在 ISR 中调用。
• 初始化顺序：初始化 waiter → hal_adc_handle_init()（内部已调用 hal_adc_init_config_default() 填充默认配置）→ 覆盖 adc_clk_div 与 soc_extra_cycle → 写入 hal_handle.user_data = dev → hal_adc_init() → 注册 SEQ0/SEQ1/SEQ2 完成、SEQ1/SEQ2 DMA 完成、错误和 AWD 回调。
• adc_clock_div 的类型是 uint8_t，其全部取值都在 HAL 的 HAL_ADC_CLK_DIV_MAX（0xFF）范围内，因此 MID 不对该字段做额外范围校验；sample_time 必须是 im_adc_sample_time_t 中列出的枚举值。
• IRQ 与 DMA 资源不在初始化阶段申请，而是在采样请求需要时申请。
• 任一步失败时，MID 会反初始化已初始化的 HAL、释放实例占用、清零对象并恢复 RESET，返回第一个失败码。因此 im_adc_init() 返回失败后不需要再调用 im_adc_deinit()。
• 同一对象重复调用不会隐式 deinit，而是返回 IM_ERR_ALREADY_EXISTS；修改配置必须通过 deinit 后再 init。

5.2 模拟看门狗监测

5.2.1 im_adc_monitor_config

error_code_t im_adc_monitor_config(
    im_adc_t *dev,
    const im_adc_monitor_config_t *config);

功能说明： 为一个 ADC 通道配置低/高阈值比较和可选的硬件 fail 输出。该接口可重复调用以配置多个通道；寄存器访问由 HAL 完成。

参数表：

返回值表：

补充说明：

• 配置了 MID event_callback 且启用低/高比较时，MID 会在 HAL 配置中使能 AWD 中断；event_callback 为空时只允许关闭监测或使用 fail 输出配置，否则返回 IM_ERR_INVALID_PARAM。
• 低/高比较全部关闭且 fail_enable == false 时，HAL 会关闭该通道的阈值监测和中断，不会产生 monitor 事件。
• HAL 的 AWD 回调在 ADC 中断上下文执行。MID 分别以 IM_ADC_EVENT_MONITOR_LOW 和 IM_ADC_EVENT_MONITOR_HIGH 通知非零的低/高标志；两类标志同时出现时会回调两次，事件快照中的 monitor_low_flags / monitor_high_flags 都携带本次的完整标志。
• monitor 事件不改变 READY/BUSY 状态，也不写入 error_flags，可以在采样前后配置。
• monitor 事件的交付依赖 ADC 中断通路，MID 只在 IRQ/DMA 采样启动时打开该通路（见 6.3）。只用 Polling 采样的对象不会收到 monitor 回调。

5.3 采样启动与等待

5.3.1 im_adc_start

error_code_t im_adc_start(im_adc_t *dev,
                          const im_adc_request_t *request);

功能说明： 启动一次 MID 采样请求。Polling 模式在调用线程内完成；IRQ/DMA 模式在成功启动后返回，结果由回调以及后续 im_adc_wait() / getter 接口交付。

参数表：

返回值表：

补充说明：

• 请求校验在修改对象之前完成，校验失败不会改写上一次请求的结果、样本计数或错误标志。
• 请求被接受后，MID 清零 sample_count 与 error_flags，把 last_status 置为 IM_ERR_NOT_READY 作为“请求进行中”的初始值，复制请求，并使对象进入 IM_ADC_STATE_BUSY。
• 公共接口不接受 sequence 参数，序列由运行模式与采集模式决定，见 6.1。
• 输出缓冲区必须持续有效，直到收到 COMPLETE / ERROR / STOPPED 终结事件或 im_adc_wait() 返回。
• Polling 路径：按帧调用 hal_adc_start() → hal_adc_poll_for_conversion()（每帧超时为 IM_ADC_DEFAULT_POLL_TIMEOUT_US）→ hal_adc_data_get() 并按 12-bit 值写入输出缓冲区，全部完成后发布 IM_ADC_EVENT_COMPLETE 并回到 READY。
• IRQ 路径：申请并使能 ADC IRQ 后调用 hal_adc_start_it()；SINGLE 在一帧完成后终结，FINITE 需要逐帧重启直到填满 sample_capacity。FINITE 的重启由 MID 的中断尾部服务在 HAL 完成本次中断清理之后执行，避免丢失紧随其后的帧完成事件。
• DMA 的 SINGLE/FINITE 路径：使用 SEQ2 与单 descriptor 循环 DMA。每帧完成后停止该 descriptor，FINITE 再按 sample_count 偏移重新配置并启动下一帧。HAL 按 packed 形式把帧数据写入输出缓冲区，MID 在回调中剥离通道号并保留 12-bit 采样值。DMA 启动与停止路径的 cache 维护由 HAL 负责。
• DMA CONTINUOUS 路径：使用 SEQ1 连续组与一个覆盖整个调用方缓冲区的循环 descriptor，保持 BUSY，按完整缓冲区发布 IM_ADC_EVENT_FRAME_READY（详见 6.4）。启动期间 MID 会短暂关闭 ADC 的中断入口，待 hal_adc_start_it() 返回后再打开，避免启动阶段重入中断。
• 启动失败时，MID 停止已启动的 HAL 序列、关闭本次申请的 ADC IRQ、记录 last_status、置对象为 ERROR，并按是否注册了回调决定是否发布 IM_ADC_EVENT_ERROR，同时唤醒可能存在的等待者。

5.3.2 im_adc_wait

error_code_t im_adc_wait(im_adc_t *dev, uint32_t timeout_ms);

功能说明： 等待当前 IRQ/DMA 采样结束，并返回当前或最近一次请求的最终状态。

参数表：

返回值表：

补充说明：

• 仅在线程上下文调用，禁止在 ISR 或 event callback 中调用。
• 对象处于 READY 或 ERROR 时不阻塞，直接返回 last_status；Polling 请求通常在 im_adc_start() 返回前已经完成，因此再次 wait 会立即返回 IM_OK。
• 同一设备同时只允许一个等待者；第二个等待线程返回 IM_ERR_BUSY。
• 超时返回前会再次检查完成竞态：只有成功领取终结权的一方才会停止序列、锁存超时标志、发布 IM_ADC_EVENT_ERROR 并进入 ERROR；领取失败的一方返回赢家已经发布的最终状态。

5.3.3 im_adc_read

error_code_t im_adc_read(im_adc_t *dev,
                         const im_adc_request_t *request,
                         uint32_t timeout_ms);

功能说明： 同步便利接口。Polling 模式直接执行 im_adc_start() 并同步完成；IRQ/DMA 模式在成功启动后调用 im_adc_wait()，成功返回时输出缓冲区已填充。

参数表：

返回值表：

补充说明：

• 仅在线程上下文调用，禁止在 ISR 或 ADC event callback 中调用。
• 该接口不支持连续采样：没有单一终结结果时调用方应改用 im_adc_start()、FRAME_READY 和 im_adc_stop()。
• IRQ/DMA 模式下 timeout_ms 直接传给 im_adc_wait()，当前实现不扣减启动阶段已经消耗的时间。
• 同步调用不会抑制 COMPLETE、ERROR 或 monitor 事件回调。

5.4 停止与释放

5.4.1 请求终结、主动停止与对象释放的区别

MID 内部的 im_adc_finish() 不是公开 API，它与公开的 im_adc_stop()、im_adc_deinit() 处于不同层次：

im_adc_finish() 通过 finish_claimed 的原子 compare-and-exchange 领取一次请求的终结权。这样 ADC 中断的完成/错误回调与线程 im_adc_wait() 超时竞争时，只有成功把该标志从 0 改为 1 的上下文能够停止硬件、写入最终状态并发布终结事件；失败方读取赢家已经发布的最终状态，避免重复事件或用 TIMEOUT 覆盖已完成结果。

5.4.2 im_adc_stop

error_code_t im_adc_stop(im_adc_t *dev);

功能说明： 停止当前采样，关闭 ADC 中断，释放调用方缓冲区的所有权，并尝试把对象恢复到 READY。

参数表：

返回值表：

补充说明：

• 仅在线程上下文调用，禁止从 event callback 中调用。
• BUSY 时先原子领取终结权（避免已挂起的 DMA 进度回调再发布 FRAME_READY），再按启动路径选择 hal_adc_stop_it()（异步）或 hal_adc_stop()（Polling）停止序列，随后释放 ADC IRQ；成功后 last_status 置为 IM_ERR_NOT_READY、状态回到 READY、发布 IM_ADC_EVENT_STOPPED 并唤醒等待者，等待线程据此识别“被取消”而不是“已完成”。
• READY 时接口幂等，不访问硬件也不产生 STOPPED 事件。
• ERROR 时尝试停止可能残留的序列；成功则清理 MID 运行态并回到 READY，失败则记录 IM_ADC_ERROR_INTERNAL 并保持 ERROR。
• 停止路径不会修改初始化配置和已配置的模拟看门狗阈值，之后可以再次 start。
• im_adc_stop() 不解除 ADC 实例占用，也不反初始化 HAL；这些工作只由 im_adc_deinit() 完成。
• 在 BUSY 状态下停止 CONTINUOUS 请求是结束循环采样的正式方式。

5.4.3 im_adc_deinit

error_code_t im_adc_deinit(im_adc_t *dev);

功能说明： 结束 MID 对象生命周期。活动采样先按 stop 语义终止，再释放 IRQ/等待者资源、反初始化 HAL 并解除逻辑 ADC 实例占用。

参数表：

返回值表：

补充说明：

• 仅在线程上下文调用，不得在 ISR 或 event callback 中调用。
• READY、BUSY 和 ERROR 均可调用。BUSY/ERROR 先按 stop 语义停止；即使该步骤失败，MID 仍会继续关闭 IRQ、以 IM_ERR_NOT_READY 唤醒等待者并执行 hal_adc_deinit()，最终返回第一个错误。
• HAL deinit 成功后，MID 解除 ADC0/ADC1 占用并清零整个 im_adc_t；对象可立即重新调用 im_adc_init()。
• 若 HAL deinit 失败，MID 保留最小 ERROR 标记和实例占用，禁止把该内存当作 RESET 对象直接重新初始化；应用必须先处理底层失败。
• 只要 im_adc_init() 曾成功返回，应用就应在离开使用范围前调用 im_adc_deinit()；后续 start/read/wait/stop 失败不改变这一要求。

5.5 状态读取与诊断

5.5.1 im_adc_get_state

im_adc_state_t im_adc_get_state(const im_adc_t *dev);

功能说明： 以无锁原子快照读取当前 MID 状态。

参数表：

返回值表：

补充说明：

• 可在任意线程上下文使用；不获取可能阻塞的锁。
• ISR 中仅在平台保证对象字段原子读取时使用。

5.5.2 im_adc_get_last_status

error_code_t im_adc_get_last_status(const im_adc_t *dev);

功能说明： 读取最近一次 init、monitor_config、start/read/wait/stop 等操作记录的最终公共错误码。

参数表：

返回值表：

补充说明：

• last_status 只用于判断最近一次操作是否成功，不代替 im_adc_get_error() 提供的硬件原因位。
• 请求刚被接受、尚未终结时 last_status 为 IM_ERR_NOT_READY；因此不能仅凭该值判定失败，应结合 im_adc_get_state()。
• im_adc_deinit() 成功后会清零对象，此后本接口（以及 5.5.3 和 5.5.4）按无效对象返回 IM_ERR_INVALID_PARAM / IM_ADC_ERROR_INTERNAL / 0。
• 只读、不访问硬件，也不构成跨线程同步屏障。

5.5.3 im_adc_get_error

uint32_t im_adc_get_error(const im_adc_t *dev);

功能说明： 读取本次采样锁存的 IM_ADC_ERROR_* 运行期错误位。

参数表：

返回值表：

补充说明：

• 多个错误位可按位组合，例如 DMA 错误和 data overrun 可以同时存在。
• 标志在请求被接受时清零，参数校验失败不会覆盖上一笔运行期错误；请求成功后标志保持到下一次被接受的 start。
• 只读、不访问硬件，也不构成跨线程同步屏障。可在错误回调中读取，但事件回调的 info 快照更直接。

5.5.4 im_adc_get_sample_count

uint32_t im_adc_get_sample_count(const im_adc_t *dev);

功能说明： 读取自最近一次被接受的 im_adc_start() 请求起，已经交付到调用方缓冲区的有效样本数。

参数表：

返回值表：

补充说明：

• SINGLE/FINITE 完成时不超过 sample_capacity；出错时表示缓冲区中已确认有效的前缀长度。
• CONTINUOUS 按完整缓冲区累计（每发布一个 FRAME_READY 增加 sample_capacity），可以超过单个缓冲区容量；被丢弃的帧不计入，计数在 UINT32_MAX 饱和。
• dev 无效或尚未接受过采样请求时返回 0；参数校验失败不会覆盖上一笔计数。
• 只读、不访问硬件；返回值为原子快照，可与事件回调并发读取，但不构成跨线程同步屏障。

5.5.5 im_adc_get_dropped_frame_count

uint32_t im_adc_get_dropped_frame_count(const im_adc_t *dev);

功能说明： 读取自最近一次被接受的 im_adc_start() 请求起，因内部连续 DMA 积压上限而未能发布的完整缓冲区数量。

参数表：

返回值表：

补充说明：

• 只对 CONTINUOUS DMA 请求有意义；其它模式（以及没有发生积压的情况）保持为 0，每次被接受的 start 会清零。
• 连续采样默认把完成的缓冲区按序顺延发布；只有一次服务期间累计完成的缓冲区超过内部积压上限（当前为 8 个完整缓冲区）时，超出部分才会被计入该计数。
• 该计数反映 MID 的发布能力，不代表样本丢失：循环 DMA 仍在持续覆盖调用方缓冲区，缓冲区内容始终是最近写入的采样数据。
• 只读、不访问硬件；返回值为原子快照。

5.5.6 im_adc_regs_dump

error_code_t im_adc_regs_dump(im_adc_instance_t instance);

功能说明： 请求指定 ADC 实例执行 HAL 寄存器 dump。MID 把 instance 映射为 ADC0 或 ADC1，仅创建一个临时 HAL 软件 handle 后调用 hal_adc_regs_dump()；详细寄存器内容由 HAL 通过 SDK 日志后端输出。

参数表：

返回值表：

补充说明：

• 这是线程上下文诊断接口；它不调用 im_adc_init()，不获取 MID 实例所有权，也不调用 hal_adc_init()，因此不会重新配置、停止或抢占正在被其它业务使用的 ADC。
• HAL 只读取寄存器快照，默认不读取 SEQ1_FIFO / SEQ2_FIFO，避免 FIFO 读操作消耗待处理采样数据；如确需该破坏性读取，需按 HAL 的 HAL_ADC_DUMP_READ_FIFO 配置处理。
• dump 输出走 SDK 日志后端而非函数返回缓冲区，调用方应确保 INFO 级日志可见。
• 该快照不对正在运行的 ADC 加锁：硬件持续采样时，多个寄存器值可能来自不同时间点。

6. 行为约束与实现说明

6.1 序列选择规则

序列由运行模式和采集模式共同决定，应用不能直接指定：

6.3 中断与 DMA 资源的申请和释放

• MID 使用 ADC 自身的 IRQ（IRQ_SADC0 / IRQ_SADC1）作为唯一中断入口，im_adc_irq_entry() 调用 hal_adc_irq_handler() 处理 ADC 中断状态与回调分发。
• IRQ 与 DMA 资源在采样请求需要时申请：Polling 请求不申请 IRQ；IRQ/DMA 请求在 im_adc_start() 中申请并使能 ADC IRQ，DMA 通道由 HAL 在序列配置时绑定。
• MID 不注册也不接管 PDMA 中断。连续 DMA 的 ADC DMA_FIN 是 ADC 级中断（HAL 在 hal_adc_irq_handler() 中处理并调用 DMA 完成回调），因此不需要 PDMA IRQ，也不依赖 MIDDLEWARE_DMA。
• ADC IRQ 在以下路径释放：im_adc_stop()、im_adc_deinit()，以及启动失败清理。IRQ/DMA 模式的 SINGLE/FINITE 成功完成后 IRQ 仍保持打开，直到应用调用 stop 或 deinit。
• 由于 monitor 事件依赖 ADC IRQ 通路，只用 Polling 采样的对象即使已按配置使能 AWD 中断，也不会收到 monitor 回调。

6.4 连续 DMA 的交付语义

连续采样（IM_ADC_ACQUISITION_CONTINUOUS + IM_ADC_RUN_MODE_DMA）的交付规则：

• MID 用 SEQ1 连续组配置 ADC，使用一个覆盖调用方整个缓冲区的循环 descriptor（dma_len = sample_capacity * 4）。
• ADC 的 DMA_FIN 只是 FIFO/DMA 进度通知，不是一帧完成的标志。MID 在每次进度回调中用 HAL 提供的 SEQ1_DMA_RCNT 字节计数计算本次增量并累计，只有累计到整个调用方缓冲区长度时才：
  1. 把 sample_count 增加一个 sample_capacity（饱和于 UINT32_MAX）；
  2. 发布一次 IM_ADC_EVENT_FRAME_READY；
  3. 保持 BUSY 并继续循环采样。
• 每次进度服务最多发布 4 个 FRAME_READY；未能发布的部分保留为积压并顺延到后续服务，积压上限为 8 个完整缓冲区，超出该上限的完成量会失去发布机会并计入 im_adc_get_dropped_frame_count()。
• MID 关心的是 DMA 字节计数的增量，因此两次进度服务之间不能跨过 64 KiB 的 DMA 进度（内部按计数宽度做掩码处理，见 6.7）。只要 ADC 中断能及时得到服务，单次增量远小于该上限。
• 若某次进度增量不是 4 字节（HAL_ADC_DMA_UNIT_SIZE）的整数倍，MID 认为 DMA 搬运异常，以 IM_ADC_ERROR_DMA 终结请求并进入 ERROR。
• 连续采样没有自然终结点：不产生 COMPLETE，im_adc_wait() 在 BUSY 时返回 IM_ERR_UNSUPPORTED，im_adc_read() 直接拒绝该模式。结束方式是在线程上下文调用 im_adc_stop()（随后可再次 start）或 im_adc_deinit()。
• FRAME_READY 回调触发时循环 DMA 可能已经覆盖同一缓冲区，因此回调内应尽快复制数据或向线程投递任务，不应假定缓冲区停留在回调那一刻的内容。

6.6 超时、错误与恢复

• 运行期错误映射：IM_ADC_ERROR_TIMEOUT（im_adc_wait() 超时或 HAL HAL_ADC_ERROR_EOC_TIMEOUT）、IM_ADC_ERROR_DATA_OVERRUN（HAL 数据/ FIFO 溢出）、IM_ADC_ERROR_EVENT_OVERRUN（HAL 事件溢出）、IM_ADC_ERROR_PHY（HAL PHY EOC 异常）、IM_ADC_ERROR_DMA（HAL DMA 错误或连续 DMA 进度统计异常）、IM_ADC_ERROR_INTERNAL（MID 内部路径失败，例如样本搬运/重启失败、HAL 停止失败、启动阶段的 HAL 硬件或 IO 错误）。
• 进入 ERROR 的方式：采样过程中的硬件/内部错误、im_adc_wait() 超时、以及启动阶段 HAL 调用失败。参数或状态校验失败（IM_ERR_INVALID_PARAM、IM_ERR_NOT_READY、IM_ERR_BUSY、IM_ERR_UNSUPPORTED）不改变对象状态，也不产生错误标志或事件。
• 恢复方式：im_adc_stop() 成功可从 ERROR 回到 READY 并保留初始化配置和实例占用；im_adc_deinit() 用于彻底结束对象。ERROR 状态下 im_adc_start() 返回 IM_ERR_NOT_READY，im_adc_monitor_config() 同样返回 IM_ERR_NOT_READY。
• error_flags 在请求被接受时清零，之后累加本次请求遇到的运行期错误；last_status 记录最近一次操作的最终公共状态。

6.7 已知限制与注意事项

• 触发源：当前 im_adc_start() 只接受 IM_ADC_TRIGGER_SOFTWARE。HAL 可以写入 TCU/PWM 触发选择，但没有公开的“仅 arm 外部触发”接口，因此 TCU/PWM 枚举被拒绝并返回 IM_ERR_UNSUPPORTED。
• 连续采样：仅支持 DMA 运行模式、单 descriptor 循环 DMA，且 sample_capacity 必须是 channel_count 的整数倍；其它组合在请求校验阶段返回 IM_ERR_INVALID_PARAM。
• 采样率与组间隔：MID 不提供公开的采样率、连续组间隔或 FIFO 水位配置，连续路径使用固定的内部常量（当前为 FIFO 水位 HAL_ADC_DRT_FIFO_GE_16 与组间隔 0x800，即 im_adc.c 中的 IM_ADC_SEQ1_CONTINUOUS_INTERVAL，均为源码内部实现，不是公开配置项）。
• DMA 进度统计：内部按 16 位计数宽度处理 SEQ1_DMA_RCNT 增量，因此两次进度服务之间的 DMA 进度差不能达到或超过 64 KiB，否则该次进度会被误判为没有推进。该约束要求 ADC 中断能被及时服务。
• monitor 事件：阈值比较由硬件在采样转换时完成；MID 只在启用 event_callback、且 ADC IRQ 通路已打开（IRQ/DMA 采样期间或之后未 stop）时才能上报事件。仅使用 Polling 采样时不会收到 monitor 回调。
• 引脚复用：ADC 模拟输入引脚必须由板级 BSP/pinmux 预先配置，MID 与 HAL 都不处理 GPIO。
• 未在本文档中承诺的行为：im_adc_t 内部字段布局、上述内部常量取值、以及一次设备服务内可发布的事件次数上限，都属于实现细节，后续版本可能调整。