General Purpose Input/Output (GPIO)

Overview

RTL8721F provides GPIO ports A/B/C, each with up to 32 pins. The Rust driver ameba_hal::gpio wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • Three typestates via GpioPin<Input> / GpioPin<Output> / GpioPin<Interrupt>, built from a shared GpioPinBuilder

  • Configurable pull resistor via Pull::NoPull / Pull::Up / Pull::Down, applied to all three typestates

  • Interrupt trigger via IntTrigger::Level / IntTrigger::Edge / IntTrigger::BothEdge, polarity via IntPolarity::ActiveLow / IntPolarity::ActiveHigh, and debounce via IntDebounce::Disabled / IntDebounce::Enabled

  • Output control through set_high / set_low / set / toggle, and level readback through read on every typestate

  • Async edge waiting on input pins via wait_for_falling_edge / wait_for_rising_edge / wait_for_any_edge, backed by an embassy waker

  • Raw ISR callback registration on interrupt pins via register_irq / GpioIrqHandler, independent of the async waker path

  • embedded_hal::digital::InputPin / OutputPin / StatefulOutputPin and embedded_hal_async::digital::Wait implementations

Operating Modes

GPIO exposes three typestates, each covering a distinct usage pattern: synchronous Input/Output, async edge detection, and raw interrupt callback.

Synchronous Input/Output

GpioPin<Output> drives a pin high or low and reads back the driven level, and GpioPin<Input> reads the live pin level. Both are obtained from 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();

Full example: examples/gpio/basic/src/main.rs.

Async Edge Detection

GpioPin<Input>::wait_for_falling_edge / wait_for_rising_edge / wait_for_any_edge return a future that resolves once the requested edge occurs, backed by an Embassy waker. The pin’s NVIC port interrupt is armed automatically.

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();

Full example: examples/gpio/async/src/main.rs.

Interrupt Callback Mode

GpioPin<Interrupt> registers a raw ISR callback via register_irq and GpioIrqHandler, running directly in the GPIO port’s interrupt context rather than through the executor. Useful when edge handling must not wait on task scheduling.

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);

Full example: examples/gpio/interrupt/src/main.rs.

Application Examples

The Rust SDK provides three example projects under examples/gpio/:

  • gpio/basic

    PA14 output toggled 10 times, mirrored by PA13 input, comparing the two levels each round.

    Wiring: PA13 ↔ PA14 jumper required.

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

    Phase 1 waits for a falling edge on PA13 with a 200 ms timeout while a task drives PA14 low after 100 ms. Phase 2 runs 20 rounds of toggling PA14 every 500 ms while a task counts edges on PA13 via wait_for_any_edge.

    Wiring: PA13 ↔ PA14 jumper required.

    [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 toggled 10 times from a high starting level while PA13 registers a raw ISR callback via register_irq that counts falling edges directly from interrupt context, independent of the async waker path used by gpio/async.

    Wiring: PA13 ↔ PA14 jumper required.

    [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
    

Note

Build any example with cargo xtask build example --name gpio/<demo>.

API Reference

Quick Usage

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;