API referencestd/embedded

std/embedded/chip/rp_pio

Public declarations, types, methods, and source contracts for std/embedded/chip/rp_pio.

On this page

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 gpio names 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, status reads 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 \n between 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 divider 256ths 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_hz instructions 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 pins drive count pins from GPIO first, 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 count pins, up to five, from GPIO first.

pub fn set_set_pins(&mut self, first: u32, count: u32) -> void!hal.Error

Config.set_in_pins

Function · Source

IN, wait pin, and mov x, pins read from GPIO first up. 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 count of them, 1 to 32, and zeros above (RP2350). Unsupported on the RP2040, which always reads 32 pins, unless count is 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_set decides how many.

pub fn set_sideset_pins(&mut self, first: u32) -> void!hal.Error

Config.set_jmp_pin

Function · Source

jmp pin branches on GPIO pin, and wait jmppin waits 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 autopull refills from the TX FIFO once OUT has shifted out threshold bits, 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 autopush goes to the RX FIFO once IN has shifted in threshold bits, 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. With enable_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, status reads as all ones: STATUS_TX_LESS or STATUS_RX_LESS with a FIFO level n, 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 at target, 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 .set directives, 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 number at base, a PIO of version version, clocked at clock_hz, raising interrupts irq and irq + 1. SAFETY: base must be the base address of PIO block number, 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 program into free instruction slots: at its .origin, or else at the highest free addresses it fits. Its wait gpio instructions 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 load of 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 an irq instruction 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 of sources is 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 line for sources.

pub fn ignore(&mut self, line: u32, sources: u32)

Pio.interrupts

Function · Source

The listened-to sources raising line line now. 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 pin straight from the pad, without the two-cycle input synchronizer, if bypass: 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 word to 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 word to 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 push or autopush does while the processor reads too slowly, or dropped a word with push 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 instruction at once, between the program’s own, or on a stopped state machine. One that stalls, such as a blocking pull, 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 count pins from GPIO first to the levels in levels, bit 0 for first, 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). first outside the window traps.

pub fn set_pins(&mut self, first: u32, count: u32, levels: u32)

StateMachine.set_pindirs

Function · Source

Make the count pins from GPIO first outputs where outputs has a one, bit 0 for first, 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 with mov rxfifo[index], isr under 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 with mov 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

Search every guide, reference page, and API declaration.