ADC

概述

RTL8721F 提供一个 16 位、11 通道的 ADC。Rust 驱动 ameba_hal::adc 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 11 个常规通道 AdcChannel::Ch0–Ch10,外加一个专用的空闲周期通道 AdcChannel::DummyCycle

  • 16 位转换分辨率,4 MHz 核心时钟

  • 通过 AdcOpMode 选择四种工作模式:软件触发、自动、定时器触发、比较器辅助

  • 通过 AdcInitParams 配置通道转换列表、每通道采样周期以及 FIFO 满中断阈值

  • 通过 Adc::get_voltage 实现 EFuse 校准的原始值到毫伏转换,首次使用时从 OTP 读取每片校准的 Vref trim 和电压曲线

  • 具备可配置比率、右移位数及交错/规则排序的过采样引擎,通过 OsRatio / OsShift / OsMode 设置

  • 通过 Adc::set_comp 实现每通道阈值比较,可通过 CompDetMode 选择电平或边沿中断检测方式

  • 通过 Adc::readable / Adc::read / Adc::read_raw 实现基于 FIFO 的采样读取,自动模式下还可通过 Adc::receive_buf 批量采集

  • 单一外设实例,通过零大小的 Adc 句柄访问,调用 unsafe { Adc::steal() } 获取

备注

Adc 驱动未实现任何 embedded-hal trait,其公开 API 完全是自定义的,也不提供异步或 DMA 传输路径。

工作模式

ADC 支持四种工作模式,通过 AdcInitParams::op_mode 选择:软件触发模式、自动模式、定时器触发模式、比较器辅助模式。

软件触发模式

每次转换需显式调用 Adc::sw_trig_cmd(true) 启动,等待 Adc::readable 后取出结果,再调用 sw_trig_cmd(false) 停止触发。该模式为默认模式,适合单次或由软件手动节拍控制的采样场景。

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};
...
const ADC_CH: u8 = 3;
...
let adc = unsafe { Adc::steal() };
let mut cvlist = [0u8; 16];
cvlist[0] = ADC_CH;
let params = AdcInitParams {
    op_mode: AdcOpMode::SoftwareTrigger,
    rx_threshold_level: 0,
    cvlist,
    cvlist_len: 1,
    special_ch: 0xFF,
    sample_period_us: 6,
};
adc.init(&params);
adc.set_ch_list(&[ADC_CH]);
adc.cmd(true);
...
adc.clear_fifo();
adc.sw_trig_cmd(true);
while !adc.readable() {}
adc.sw_trig_cmd(false);

let raw = adc.read().data;
// EFuse-calibrated raw -> millivolts (per-chip curve, read once by the driver).
let mv = adc.get_voltage(raw as u32);

完整示例见 examples/adc/src/main.rs。

自动模式

Adc::auto_csw_cmd(true) 会在整个通道列表上启动连续扫描,无需软件进一步干预,各通道的结果依次进入 FIFO。Adc::receive_buf 将其封装为一次简单的阻塞式批量读取:清空 FIFO、启动扫描、轮询直到缓冲区填满,再停止扫描。

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};

let adc = unsafe { Adc::steal() };
let params = AdcInitParams {
    op_mode: AdcOpMode::Automatic,
    ..AdcInitParams::default()
};
adc.init(&params);
adc.cmd(true);

let mut buf = [0u32; 12];
adc.receive_buf(&mut buf);

examples/adc/ 下没有覆盖自动模式的示例。以上调用是真实的 Adc API,但此代码段并非取自某个示例文件。

定时器触发模式

Adc::timer_trig_cmd 将某个基础 RTIM(索引 0–7)配置为周期性触发源并启动或停止它,每个定时器周期都会自动向 FIFO 触发一次转换,期间无需 CPU 介入。

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};
...
use ameba_hal::{
    pinmux::{self, Pin, PinFunction, Pull},
    rcc,
};
...
rcc::enable(rcc::Peripheral::LTIM0);

adc.cmd(false);
let tt_params = AdcInitParams { op_mode: AdcOpMode::TimerTrigger, ..params };
adc.init(&tt_params);
adc.set_ch_list(&[ADC_CH]);
adc.cmd(true);
adc.clear_fifo();

// Basic timer 0 fires a conversion every 100 ms.
adc.timer_trig_cmd(0, 100, true);
...
if adc.readable() {
    let raw = adc.read().data;
    let mv = adc.get_voltage(raw as u32);
    ...
}
...
adc.timer_trig_cmd(0, 100, false);

完整示例见 examples/adc/src/main.rs。

比较器辅助模式

Adc::set_comp 为某通道设置高/低阈值及匹配条件,并启用该通道的比较器中断,Adc::set_comp_mode 选择中断是在条件持续满足期间连续触发(电平)还是仅在每次匹配时触发一次(边沿)。Adc::get_comp_status 可读回某通道当前的比较结果。

use ameba_hal::adc::{Adc, AdcChannel, AdcInt, CompCriteria, CompDetMode};

let adc = unsafe { Adc::steal() };
adc.set_comp_mode(CompDetMode::Edge);
adc.set_comp(AdcChannel::Ch3, 3600, 2800, CompCriteria::OutsideThlAndThh);

if adc.get_isr().contains(AdcInt::COMP_CH3) {
    adc.int_clear_pending(AdcInt::COMP_CH3);
    let status = adc.get_comp_status(AdcChannel::Ch3);
}

examples/adc/ 下没有覆盖比较器辅助模式的示例。以上调用是真实的 Adc API,但此代码段并非取自某个示例文件。

应用示例

Rust SDK 在 examples/adc 提供一个示例项目,依次演示软件触发模式和定时器触发模式:

  • 软件触发:以 200 ms 间隔对通道 3(PA17)采样 5 次,通过 EFuse 校准曲线将每次原始读数转换为毫伏,并检查结果是否落在 2800–3600 mV 范围内。

  • 定时器触发:将同一通道重新配置为由 RTIM0 以 100 ms 周期驱动触发,最多等待约 1 s 以等待一次采样进入 FIFO。

接线:将 PA17(ADC 通道 3)接 3.3V 或 GND。电压窗口为 2.8–3.6V,接 GND 会报 [FAIL]。

[ADC] start
[ADC] raw: NNNN voltage: 3.30V
[ADC] raw: NNNN voltage: 3.30V
...
[PASS] ADC: voltage OK
[ADC] timer-trig raw: NNNN voltage: 3.30V
[PASS] ADC: timer-trigger OK

备注

编译示例:cargo xtask build example --name adc。

API 参考

快速用法

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};

let adc = unsafe { Adc::steal() };
let params = AdcInitParams {
    op_mode: AdcOpMode::SoftwareTrigger,
    cvlist_len: 1,
    cvlist: { let mut l = [0u8; 16]; l[0] = 3; l },
    ..AdcInitParams::default()
};
adc.init(&params);
adc.set_ch_list(&[3]);
adc.cmd(true);

adc.clear_fifo();
adc.sw_trig_cmd(true);
while !adc.readable() {}
adc.sw_trig_cmd(false);

let mv = adc.get_voltage(adc.read().data as u32);

Adc 还支持自动模式、定时器触发模式和比较器辅助模式,请参见上文工作模式一节。