Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/embedded/chip/rp_pio"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
hal |
std/embedded/hal |
rp_pio.dodo |
INSTRUCTION_COUNT
Constant · Source
Instruction slots in a block, and state machines.
pub const INSTRUCTION_COUNT: u32 = 32
MACHINE_COUNT
Constant · Source
pub const MACHINE_COUNT: u32 = 4
PIN_LIMIT
Constant · Source
The GPIOs a block’s window spans: its pin mappings reach PIN_LIMIT consecutive GPIOs from its GPIO base.
pub const PIN_LIMIT: u32 = 32
HIGH_GPIO_BASE
Constant · Source
The GPIO base of the RP2350’s upper window, GPIO 16 to 47.
pub const HIGH_GPIO_BASE: u32 = 16
GPIOS_0_TO_15
Constant · Source
Program.gpio_ranges bits: a
wait gpionames a GPIO from 0 to 15, 16 to 31, or 32 to 47.
pub const GPIOS_0_TO_15: u32 = 1 << 0
GPIOS_16_TO_31
Constant · Source
pub const GPIOS_16_TO_31: u32 = 1 << 1
GPIOS_32_TO_47
Constant · Source
pub const GPIOS_32_TO_47: u32 = 1 << 2
ANYWHERE
Constant · Source
Program.origin of a program that loads at any address.
pub const ANYWHERE: u32 = 0xFFFF_FFFF
FIFO_TXRX
Constant · Source
FIFO joins, for Program.fifo and Config.set_fifo_join. TX and RX give the one FIFO both directions’ entries, eight words deep. The rest are RP2350 only and keep the TX FIFO: TXPUT makes the RX FIFO four registers the program writes (with
mov rxfifo[...], isr) and the processor reads with StateMachine.rx_register, TXGET four the processor writes and the program reads (mov osr, rxfifo[...]), and PUTGET four the program both writes and reads.
pub const FIFO_TXRX: u32 = 0
FIFO_TX
Constant · Source
pub const FIFO_TX: u32 = 1
FIFO_RX
Constant · Source
pub const FIFO_RX: u32 = 2
FIFO_TXPUT
Constant · Source
pub const FIFO_TXPUT: u32 = 3
FIFO_TXGET
Constant · Source
pub const FIFO_TXGET: u32 = 4
FIFO_PUTGET
Constant · Source
pub const FIFO_PUTGET: u32 = 5
STATUS_TX_LESS
Constant · Source
What
mov x, statusreads as all ones, for Config.set_mov_status: the TX FIFO holds fewer than N words, the RX FIFO does, or (RP2350) IRQ flag N is set, with N + 8 for the previous block’s flag N and N + 16 for the next block’s.
pub const STATUS_TX_LESS: u32 = 0
STATUS_RX_LESS
Constant · Source
pub const STATUS_RX_LESS: u32 = 1
STATUS_IRQ
Constant · Source
pub const STATUS_IRQ: u32 = 2
rx_not_empty
Function · Source
Interrupt sources, for Pio.listen, ignore, and interrupts: the state machine’s RX FIFO holds a word, its TX FIFO has room, or IRQ flag n is set (flags 0 to 3 on the RP2040, 0 to 7 on the RP2350).
pub fn rx_not_empty(machine: u32) -> u32
tx_not_full
Function · Source
pub fn tx_not_full(machine: u32) -> u32
flag
Function · Source
pub fn flag(number: u32) -> u32
Program
Struct · Source
An assembled PIO program and the state machine settings it asks for, from
assemble. Load it into a block with Pio.load.
pub struct Program {
// The instructions, `length` of them, with JMP targets relative to the
// first; loading adds the address the program lands at.
pub instructions: [32]u16
pub length: u32
// The address `.origin` fixes, or ANYWHERE.
pub origin: u32
// `.wrap_target` and `.wrap`, relative to the first instruction: after
// the instruction at `wrap`, the program continues at `wrap_target`.
// By default the program wraps from its last instruction to its first.
pub wrap_target: u32
pub wrap: u32
// `.side_set`: the delay field bits side-set takes, counting the enable
// bit of an optional side-set, whether it is optional, and whether it
// sets pin directions instead of levels. 0 without side-set.
pub side_set_count: u32
pub side_set_optional: bool
pub side_set_pindirs: bool
// The PIO version the program needs: 1 if it uses RP2350 features.
pub version: u32
// `.clock_div`, in 256ths: 256 runs one instruction per system clock.
pub clock_divider: u32
// `.fifo`: FIFO_TXRX to FIFO_PUTGET.
pub fifo: u32
// `.mov_status`: STATUS_TX_LESS, STATUS_RX_LESS, or STATUS_IRQ, and N.
pub status_select: u32
pub status_n: u32
// `.in`: the pins IN reads unmasked (RP2350; 32 reads all), whether
// the ISR shifts right, autopush, and its threshold in bits.
pub in_count: u32
pub in_right: bool
pub autopush: bool
pub push_threshold: u32
// `.out`: the pins OUT drives, whether the OSR shifts right, autopull,
// and its threshold in bits.
pub out_count: u32
pub out_right: bool
pub autopull: bool
pub pull_threshold: u32
// `.set`: the pins SET drives, 0 to 5.
pub set_count: u32
// The GPIO ranges its `wait gpio` instructions name, GPIOS_0_TO_15 to
// GPIOS_32_TO_47; they hold the low five bits of the GPIO number, and
// loading translates them into the block's window.
pub gpio_ranges: u32
}
assemble
Function · Source
Assemble a PIO program when the firmware is compiled, from string literals, one line each, and return it. The language is the Pico SDK’s pioasm: labels,
.define, expressions, side-set and delay, every instruction, and the directives above; comments start with;or//. The program may also be one literal with\nbetween its lines. An error in the program is a compile error at its line. Only firmware for the RP2040 and RP2350 can assemble programs.
@compiler(pio)
pub fn assemble(source: &str) -> Program
Config
Struct · Source
A state machine’s settings: clock divider, pin mappings, shifting, FIFO joins, and wrap. Loaded.config starts one from the program’s settings; the set_ methods change it, and StateMachine.init applies it.
pub struct Config {
// Private implementation fields omitted.
}
Config.set_divider
Function · Source
Run one instruction every
divider256ths of a system clock cycle, from 256 (every cycle) to 65535 255/256 cycles. InvalidInput outside that range.
pub fn set_divider(&mut self, divider: u32) -> void!hal.Error
Config.set_frequency
Function · Source
Run
frequency_hzinstructions a second, as closely as the divider allows: from the system clock frequency down to 1/65536th of it. InvalidInput outside that range.
pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error
Config.divider
Function · Source
The divider, in 256ths.
pub fn divider(&self) -> u32
Config.frequency_hz
Function · Source
The instruction rate the divider gives, rounded to whole hertz.
pub fn frequency_hz(&self) -> u32
Config.gpio_base
Function · Source
The GPIO base of the block’s window the config was made for: 0, or HIGH_GPIO_BASE. The set_ methods below refuse pins outside it.
pub fn gpio_base(&self) -> u32
Config.set_out_pins
Function · Source
OUT and
mov pinsdrivecountpins from GPIOfirst, wrapping at the end of the block’s window (after GPIO 31, or 47 in the upper window). InvalidInput for a pin outside the window or more than 32 pins.
pub fn set_out_pins(&mut self, first: u32, count: u32) -> void!hal.Error
Config.set_set_pins
Function · Source
SET drives
countpins, up to five, from GPIOfirst.
pub fn set_set_pins(&mut self, first: u32, count: u32) -> void!hal.Error
Config.set_in_pins
Function · Source
IN,
wait pin, andmov x, pinsread from GPIOfirstup. They read any GPIO with its input enabled, whichever function drives it: pins given to the block, and pins claimed as inputs, for example.
pub fn set_in_pins(&mut self, first: u32) -> void!hal.Error
Config.set_in_count
Function · Source
Reads of the IN pins see only the first
countof them, 1 to 32, and zeros above (RP2350). Unsupported on the RP2040, which always reads 32 pins, unlesscountis 32.
pub fn set_in_count(&mut self, count: u32) -> void!hal.Error
Config.set_sideset_pins
Function · Source
Side-set drives pins from GPIO
first; the program’s.side_setdecides how many.
pub fn set_sideset_pins(&mut self, first: u32) -> void!hal.Error
Config.set_jmp_pin
Function · Source
jmp pinbranches on GPIOpin, andwait jmppinwaits on it.
pub fn set_jmp_pin(&mut self, pin: u32) -> void!hal.Error
Config.set_out_shift
Function · Source
The OSR shifts right (least significant bit first) or left, and with
autopullrefills from the TX FIFO once OUT has shifted outthresholdbits, 1 to 32.
pub fn set_out_shift(&mut self, right: bool, autopull: bool, threshold: u32) -> void!hal.Error
Config.set_in_shift
Function · Source
The ISR shifts right or left, and with
autopushgoes to the RX FIFO once IN has shifted inthresholdbits, 1 to 32.
pub fn set_in_shift(&mut self, right: bool, autopush: bool, threshold: u32) -> void!hal.Error
Config.set_fifo_join
Function · Source
Join the FIFOs: FIFO_TXRX to FIFO_PUTGET. InvalidInput for another value, Unsupported for an RP2350 join on the RP2040.
pub fn set_fifo_join(&mut self, join: u32) -> void!hal.Error
Config.set_out_special
Function · Source
With
sticky, the OUT pins keep their last level and direction while OUT and SET do not write them. Withenable_pin, an OUT data bit at that index (0 to 31) decides whether each OUT writes the pins at all.
pub fn set_out_special(&mut self, sticky: bool, enable_pin: Option<u32>) -> void!hal.Error
Config.set_mov_status
Function · Source
What
mov x, statusreads as all ones: STATUS_TX_LESS or STATUS_RX_LESS with a FIFO leveln, or STATUS_IRQ (RP2350) with a flag. InvalidInput for values out of range, Unsupported for STATUS_IRQ on the RP2040.
pub fn set_mov_status(&mut self, select: u32, n: u32) -> void!hal.Error
Config.set_wrap
Function · Source
After the instruction at address
wrap, continue attarget, both absolute addresses (Loaded.offset plus the program’s).
pub fn set_wrap(&mut self, target: u32, wrap: u32) -> void!hal.Error
Config.set_start
Function · Source
StateMachine.init starts the program at absolute address
address, instead of at the program’s first instruction.
pub fn set_start(&mut self, address: u32) -> void!hal.Error
Config.copy
Function · Source
pub fn copy(&self) -> Config
Loaded
Struct · Source
A program in a block’s instruction memory, from Pio.load.
pub struct Loaded {
// Private implementation fields omitted.
}
Loaded.offset
Function · Source
The address of the program’s first instruction. Add a label’s address in the program to get its address in the block.
pub fn offset(&self) -> u32
Loaded.length
Function · Source
pub fn length(&self) -> u32
Loaded.config
Function · Source
The settings the program asks for: its wrap, side-set, and the
.clock_div,.fifo,.mov_status,.in,.out, and.setdirectives, starting at its first instruction. Pins start at the first GPIO of the block’s window.
pub fn config(&self) -> Config
Loaded.gpio_base
Function · Source
The GPIO base of the block’s window when the program was loaded.
pub fn gpio_base(&self) -> u32
Pio
Struct · Source
A PIO block, claimed from a chip’s Pins with
pins.pio(n): its instruction memory, state machines, IRQ flags, and interrupts.
pub struct Pio {
// Private implementation fields omitted.
}
Pio.at
Function · Source
The block
numberatbase, a PIO of versionversion, clocked atclock_hz, raising interruptsirqandirq + 1. SAFETY:basemust be the base address of PIO blocknumber, out of reset and in its reset state, and only this Pio and the StateMachines it hands out may use it.
pub unsafe fn at(base: usize, number: u32, version: u32, clock_hz: u32, irq: u32) -> Pio
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
Pio.number
Function · Source
The block number: 0 to 1 on the RP2040, 0 to 2 on the RP2350.
pub fn number(&self) -> u32
Pio.version
Function · Source
The block’s PIO version: 0 on the RP2040, 1 on the RP2350.
pub fn version(&self) -> u32
Pio.memory
Function · Source
The instruction slots in use, one bit each.
pub fn memory(&self) -> u32
Pio.gpio_base
Function · Source
The first GPIO of the block’s window: 0 (GPIO 0 to 31), as after reset, or HIGH_GPIO_BASE (GPIO 16 to 47).
pub fn gpio_base(&self) -> u32
Pio.set_gpio_base
Function · Source
Move the block’s window to start at GPIO
base: 0, or on the RP2350 HIGH_GPIO_BASE, so that its pin mappings reach GPIO 16 to 47. Choose it before giving the block pins (Pins.pio_pins), loading programs, or claiming state machines, whose pins it would move. InvalidInput for another base, Unsupported for HIGH_GPIO_BASE on the RP2040, Busy while a program is loaded or a state machine claimed.
pub fn set_gpio_base(&mut self, base: u32) -> void!hal.Error
Pio.load
Function · Source
Load
programinto free instruction slots: at its.origin, or else at the highest free addresses it fits. Itswait gpioinstructions are translated into the block’s window. Busy if it does not fit, InvalidInput for an empty program, one longer than 32 instructions, or one that waits on a GPIO outside the window, Unsupported for an RP2350 program on the RP2040.
pub fn load(&mut self, program: &Program) -> Loaded!hal.Error
Pio.unload
Function · Source
Free the slots of a program from
loadof this block. State machines must no longer run it.
pub fn unload(&mut self, loaded: Loaded)
Pio.state_machine
Function · Source
Claim state machine
index, 0 to 3, stopped. Busy if it is claimed, InvalidInput for another index.
pub fn state_machine(&mut self, index: u32) -> StateMachine!hal.Error
Pio.free_state_machine
Function · Source
Claim the lowest-numbered free state machine. Busy if all four are claimed.
pub fn free_state_machine(&mut self) -> StateMachine!hal.Error
Pio.release_state_machine
Function · Source
Stop a state machine claimed from this block and give it back, with its interrupt sources turned off.
pub fn release_state_machine(&mut self, machine: StateMachine)
Pio.machines
Function · Source
The state machines claimed, one bit each.
pub fn machines(&self) -> u32
Pio.enable_in_sync
Function · Source
Start the claimed state machines among
machines(one bit each) together, with their clock dividers in step, so they run in lock step.
pub fn enable_in_sync(&mut self, machines: u32)
Pio.flags
Function · Source
The IRQ flags that are set, one bit each.
pub fn flags(&mut self) -> u32
Pio.clear_flags
Function · Source
Clear the IRQ flags among
flags, releasing state machines waiting for them to clear.
pub fn clear_flags(&mut self, flags: u32)
Pio.force_flags
Function · Source
Set the IRQ flags among
flags, as anirqinstruction would.
pub fn force_flags(&mut self, flags: u32)
Pio.irq
Function · Source
The interrupt number of the block’s interrupt line 0 or 1, for cortex_m.enable and
@interrupt.
pub fn irq(&self, line: u32) -> u32
Pio.listen
Function · Source
Raise interrupt line
line, 0 or 1, while any ofsourcesis active: rx_not_empty, tx_not_full, and flag bits. Enable the interrupt in the NVIC too:cortex_m.enable(pio.irq(line)).
pub fn listen(&mut self, line: u32, sources: u32)
Pio.ignore
Function · Source
Stop raising line
lineforsources.
pub fn ignore(&mut self, line: u32, sources: u32)
Pio.interrupts
Function · Source
The listened-to sources raising line
linenow. A flag stays active until cleared with clear_flags; FIFO sources until the FIFO changes.
pub fn interrupts(&mut self, line: u32) -> u32
Pio.bypass_input_sync
Function · Source
Read GPIO
pinstraight from the pad, without the two-cycle input synchronizer, ifbypass: faster for clocked inputs, and safe only for signals synchronous to the system clock. The pin must lie in the block’s window; another traps.
pub fn bypass_input_sync(&mut self, pin: u32, bypass: bool)
Pio.release
Function · Source
Stop every state machine and return the block number, for the chip package to hold the block in reset. Every state machine must have been given back.
pub fn release(self) -> u32
StateMachine
Struct · Source
One state machine, claimed with Pio.state_machine. It runs the program a Config points it at, moving words through its FIFOs.
pub struct StateMachine {
// Private implementation fields omitted.
}
StateMachine.index
Function · Source
0 to 3, within its block.
pub fn index(&self) -> u32
StateMachine.block
Function · Source
The number of the block it belongs to.
pub fn block(&self) -> u32
StateMachine.gpio_base
Function · Source
Its block’s window base, as Pio.gpio_base.
pub fn gpio_base(&self) -> u32
StateMachine.init
Function · Source
Stop the state machine and set it up with
config: its settings apply, its FIFOs and their error flags clear, its state (shift counters, delay, stall) resets, and it jumps to the config’s start. Its X, Y, ISR, and OSR keep their values. Start it with set_enabled. The config must come from a program loaded into a block with the same window (Config.gpio_base); another traps.
pub fn init(&mut self, config: &Config)
StateMachine.set_enabled
Function · Source
Run (true) or pause (false) the program. A paused state machine keeps its state and resumes where it stopped.
pub fn set_enabled(&mut self, enabled: bool)
StateMachine.is_enabled
Function · Source
pub fn is_enabled(&mut self) -> bool
StateMachine.restart
Function · Source
Reset the state machine’s internal state: shift counters, a pending delay or stall, and its sticky output. Not its registers or FIFOs.
pub fn restart(&mut self)
StateMachine.restart_clock
Function · Source
Restart the clock divider’s phase, as enable_in_sync does for several state machines.
pub fn restart_clock(&mut self)
StateMachine.set_divider
Function · Source
Change the clock divider while running, in 256ths, as for Config.set_divider.
pub fn set_divider(&mut self, divider: u32) -> void!hal.Error
StateMachine.set_frequency
Function · Source
Change the instruction rate while running, as for Config.set_frequency.
pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error
StateMachine.put
Function · Source
Write
wordto the TX FIFO, waiting while it is full. Waits forever if the program never takes words.
pub fn put(&mut self, word: u32)
StateMachine.try_put
Function · Source
Write
wordto the TX FIFO unless it is full. Returns whether it did.
pub fn try_put(&mut self, word: u32) -> bool
StateMachine.get
Function · Source
Read a word from the RX FIFO, waiting while it is empty. Waits forever if the program never pushes.
pub fn get(&mut self) -> u32
StateMachine.try_get
Function · Source
Read a word from the RX FIFO, or none if it is empty.
pub fn try_get(&mut self) -> Option<u32>
StateMachine.tx_level
Function · Source
The words in the TX and RX FIFOs.
pub fn tx_level(&mut self) -> u32
StateMachine.rx_level
Function · Source
pub fn rx_level(&mut self) -> u32
StateMachine.is_tx_full
Function · Source
pub fn is_tx_full(&mut self) -> bool
StateMachine.is_tx_empty
Function · Source
pub fn is_tx_empty(&mut self) -> bool
StateMachine.is_rx_full
Function · Source
pub fn is_rx_full(&mut self) -> bool
StateMachine.is_rx_empty
Function · Source
pub fn is_rx_empty(&mut self) -> bool
StateMachine.clear_fifos
Function · Source
Empty both FIFOs, dropping their words.
pub fn clear_fifos(&mut self)
StateMachine.drain_tx
Function · Source
Drop the words in the TX FIFO by pulling them into the OSR with executed instructions, which changes the OSR.
pub fn drain_tx(&mut self)
StateMachine.take_tx_stall
Function · Source
Whether the program stalled on an empty TX FIFO since the last call, as it does once it has sent every word; clears the flag.
pub fn take_tx_stall(&mut self) -> bool
StateMachine.take_rx_stall
Function · Source
Whether the program stalled on a full RX FIFO since the last call, as a blocking
pushor autopush does while the processor reads too slowly, or dropped a word withpush noblock; clears the flag. It writes the flag only when it was set, so a stall that comes after the read stays set for the next call.
pub fn take_rx_stall(&mut self) -> bool
StateMachine.exec
Function · Source
Run
instructionat once, between the program’s own, or on a stopped state machine. One that stalls, such as a blockingpull, finishes when its condition is met, while the program waits.
pub fn exec(&mut self, instruction: u16)
StateMachine.exec_wait
Function · Source
exec, then wait until the instruction has finished stalling.
pub fn exec_wait(&mut self, instruction: u16)
StateMachine.is_exec_stalled
Function · Source
Whether an instruction from exec is still stalled.
pub fn is_exec_stalled(&mut self) -> bool
StateMachine.address
Function · Source
The address of the instruction it runs now.
pub fn address(&mut self) -> u32
StateMachine.jump
Function · Source
Continue at absolute address
address.
pub fn jump(&mut self, address: u32)
StateMachine.set_pins
Function · Source
Drive the
countpins from GPIOfirstto the levels inlevels, bit 0 forfirst, through the state machine, wrapping at the end of the block’s window. Use it before starting a program, to give its pins defined levels; the pins must belong to the block (Pins.pio_pins).firstoutside the window traps.
pub fn set_pins(&mut self, first: u32, count: u32, levels: u32)
StateMachine.set_pindirs
Function · Source
Make the
countpins from GPIOfirstoutputs whereoutputshas a one, bit 0 forfirst, and inputs elsewhere, as for set_pins.
pub fn set_pindirs(&mut self, first: u32, count: u32, outputs: u32)
StateMachine.rx_register
Function · Source
RX FIFO register
index, 0 to 3, which the program writes withmov rxfifo[index], isrunder FIFO_TXPUT or FIFO_PUTGET (RP2350). Unsupported on the RP2040, InvalidInput for another index.
pub fn rx_register(&mut self, index: u32) -> u32!hal.Error
StateMachine.set_rx_register
Function · Source
Write RX FIFO register
index, which the program reads withmov osr, rxfifo[index]under FIFO_TXGET or FIFO_PUTGET (RP2350).
pub fn set_rx_register(&mut self, index: u32, value: u32) -> void!hal.Error
StateMachine.tx_fifo_address
Function · Source
The addresses of the TX and RX FIFOs, for DMA.
pub fn tx_fifo_address(&self) -> usize
StateMachine.rx_fifo_address
Function · Source
pub fn rx_fifo_address(&self) -> usize