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 sharedGpioPinBuilderConfigurable pull resistor via
Pull::NoPull/Pull::Up/Pull::Down, applied to all three typestatesInterrupt trigger via
IntTrigger::Level/IntTrigger::Edge/IntTrigger::BothEdge, polarity viaIntPolarity::ActiveLow/IntPolarity::ActiveHigh, and debounce viaIntDebounce::Disabled/IntDebounce::EnabledOutput control through
set_high/set_low/set/toggle, and level readback throughreadon every typestateAsync edge waiting on input pins via
wait_for_falling_edge/wait_for_rising_edge/wait_for_any_edge, backed by anembassywakerRaw ISR callback registration on interrupt pins via
register_irq/GpioIrqHandler, independent of the async waker pathembedded_hal::digital::InputPin/OutputPin/StatefulOutputPinandembedded_hal_async::digital::Waitimplementations
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/:
-
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
-
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
-
PA14 toggled 10 times from a high starting level while PA13 registers a raw ISR callback via
register_irqthat counts falling edges directly from interrupt context, independent of the async waker path used bygpio/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;