GPIO

概述

RTL8721F 提供 A/B/C 三个 GPIO 端口,每个端口最多 32 个引脚。Rust 驱动 ameba_hal::gpio 直接封装 PAC 寄存器块,不涉及裸位操作或 C FFI 调用。

功能特性

  • 三种类型状态 GpioPin<Input> / GpioPin<Output> / GpioPin<Interrupt>,均由共享的 GpioPinBuilder 创建

  • 可配置上下拉,通过 Pull::NoPull / Pull::Up / Pull::Down 设置,适用于全部三种类型状态

  • 中断触发方式通过 IntTrigger::Level / IntTrigger::Edge / IntTrigger::BothEdge 设置,极性通过 IntPolarity::ActiveLow / IntPolarity::ActiveHigh 设置,去抖通过 IntDebounce::Disabled / IntDebounce::Enabled 设置

  • 每种类型状态均提供 set_high / set_low / set / toggle 输出控制和 read 电平读取

  • 输入引脚可通过 wait_for_falling_edge / wait_for_rising_edge / wait_for_any_edge 异步等待边沿,基于 embassy waker 实现

  • 中断引脚可通过 register_irq / GpioIrqHandler 注册裸 ISR 回调,独立于 async waker 路径

  • 实现了 embedded_hal::digital::InputPin / OutputPin / StatefulOutputPin 和 embedded_hal_async::digital::Wait

工作模式

GPIO 提供三种类型状态,分别对应不同的使用场景:同步 Input/Output、异步边沿检测、裸中断回调。

同步 Input/Output

GpioPin<Output> 驱动引脚为高或低,并读回驱动电平,GpioPin<Input> 读取引脚的实时电平。两者都通过 GpioPin::builder(pin) 获得。

use ameba_hal::gpio::{GpioPin, Input, Output, Pin, Pull};
...
let pa14 = GpioPin::<Output>::builder(Pin::PA14).pull(Pull::NoPull).output();
let pa13 = GpioPin::<Input>::builder(Pin::PA13).pull(Pull::Up).input();

// Start HIGH so first toggle goes LOW → levels visible from the start.
pa14.set_high();
...
pa14.toggle();
...
let out = pa14.read();
let inp = pa13.read();

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

异步边沿检测

GpioPin<Input>::wait_for_falling_edge / wait_for_rising_edge / wait_for_any_edge 返回一个 future,在指定边沿发生后完成,基于 Embassy waker 实现。调用时会自动开启该引脚所在端口的 NVIC 中断。

use ameba_hal::gpio::{GpioPin, Input, Output, Pin, Pull};
...
#[embassy_executor::task]
async fn edge_task(mut pa13: GpioPin<Input>) {
    loop {
        pa13.wait_for_any_edge().await;
        let n = EDGE_COUNT.fetch_add(1, Ordering::AcqRel) + 1;
        println!("[GPIO] edge {}", n);
    }
}
...
let pa13 = GpioPin::<Input>::builder(Pin::PA13).pull(Pull::Up).input();
...
spawner.spawn(edge_task(pa13)).unwrap();

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

中断回调模式

GpioPin<Interrupt> 通过 register_irq 和 GpioIrqHandler 注册裸 ISR 回调,直接在 GPIO 端口的中断上下文中运行,而不经过 executor 调度。适合边沿处理不能等待任务调度的场景。

use core::ptr::addr_of_mut;
use core::sync::atomic::{AtomicU32, Ordering};
...
use ameba_hal::gpio::{GpioEvent, GpioIrqHandler, GpioPin, IntPolarity, IntTrigger, Interrupt, Output, Pin, Pull};
use ameba_hal::println;

struct EdgeCounter {
    count: AtomicU32,
}

impl GpioIrqHandler for EdgeCounter {
    fn on_irq(&mut self, event: GpioEvent) {
        let n = self.count.fetch_add(1, Ordering::Relaxed) + 1;
        println!("[GPIO-IRQ] edge {} (port={} pin={}, from ISR)", n, event.port, event.pin);
    }
}

static mut EDGE_COUNTER: EdgeCounter = EdgeCounter { count: AtomicU32::new(0) };
...
let pa13 = GpioPin::<Interrupt>::builder(Pin::PA13)
    .pull(Pull::Up)
    .trigger(IntTrigger::Edge)
    .polarity(IntPolarity::ActiveLow)
    .interrupt();

let handler = unsafe { &mut *addr_of_mut!(EDGE_COUNTER) };
pa13.register_irq(handler);

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

应用示例

Rust SDK 在 examples/gpio/ 下提供三个示例项目:

  • gpio/basic

    PA14 作为 output 翻转 10 次,PA13 作为 input 跟随,每次对比两者电平。

    接线:将 PA13 和 PA14 用跳线短接。

    [GPIO basic] start
    [GPIO] [0] PA14=L PA13=L
    [GPIO] [1] PA14=H PA13=H
    ...
    [PASS] GPIO basic: OK
    
  • gpio/async

    Phase 1:PA14 初始高,100 ms 后拉低,PA13 在 200 ms 内等待下降沿。Phase 2:一个任务每 500 ms 翻转 PA14 共 20 次,另一个任务通过 wait_for_any_edge 统计 PA13 上的边沿次数。

    接线:将 PA13 和 PA14 用跳线短接。

    [GPIO async] start
    [PASS] GPIO: falling edge detected
    [GPIO] PA14 toggle 1
    [GPIO] edge 1
    ...
    [PASS] GPIO async: 20 toggles 20 edges OK
    
  • gpio/interrupt

    PA14 从高电平开始翻转 10 次,PA13 通过 register_irq 注册裸 ISR 回调,直接在中断上下文中统计下降沿次数,独立于 gpio/async 所用的 async waker 路径。

    接线:将 PA13 和 PA14 用跳线短接。

    [GPIO interrupt] start
    [GPIO-IRQ] edge 1 (port=0 pin=13, from ISR)
    [GPIO] [0] PA14=L edge_count=1
    ...
    [PASS] GPIO interrupt: 5 edges OK
    

备注

编译任意示例:cargo xtask build example --name gpio/<demo>。

API 参考

快速用法

use ameba_hal::gpio::{GpioPin, Input, Output, Pin, Pull};

let out = GpioPin::<Output>::builder(Pin::PA14).pull(Pull::NoPull).output();
let mut inp = GpioPin::<Input>::builder(Pin::PA13).pull(Pull::Up).input();

out.set_high();
let level = inp.read();
inp.wait_for_falling_edge().await;