API referencestd/embedded

std/embedded/chip/rp_pwm

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

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_pwm"

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_pwm.dodo
rp_timer std/embedded/chip/rp_timer rp_pwm.dodo

SLICE_COUNT

Constant · Source

The slices GPIO 0 to 31 reach.

pub const SLICE_COUNT: u32 = 8

PIN_COUNT

Constant · Source

The GPIOs with a PWM output, on the chips that have them: GPIO 0 to 47. The chip packages’ Pins refuse GPIOs the chip lacks.

pub const PIN_COUNT: u32 = 48

MIN_DIVIDER

Constant · Source

The divider is a fixed-point number in sixteenths: 16 divides by one, 4095 by 255 15/16.

pub const MIN_DIVIDER: u32 = 16

MAX_DIVIDER

Constant · Source

pub const MAX_DIVIDER: u32 = 4095

MAX_TOP

Constant · Source

The largest TOP: one short of 16 bits, so that the compare value that holds an output high, TOP + 1, still fits its 16-bit field.

pub const MAX_TOP: u32 = 0xFFFE

slice_of

Function · Source

The slice of GPIO pin.

pub fn slice_of(pin: u32) -> u32

output_of

Function · Source

The output of GPIO pin within its slice: 0 for A, 1 for B.

pub fn output_of(pin: u32) -> u32

Timing

Struct · Source

A slice’s divider and TOP, from timing or divided.

pub struct Timing {
    // The block's input clock, clk_sys, in hertz.
    pub clock_hz: u32
    // The divider in sixteenths, MIN_DIVIDER to MAX_DIVIDER.
    pub divider: u32
    // The count the counter wraps after, 0 to MAX_TOP: a period is TOP + 1
    // counts, and outputs have TOP + 2 duty steps, 0 to TOP + 1.
    pub top: u32
}

Timing.frequency_hz

Function · Source

The resulting frequency, rounded to whole hertz.

pub fn frequency_hz(&self) -> u32

timing

Function · Source

The divider and TOP closest to frequency_hz with the finest duty steps: the smallest divider whose period fits in MAX_TOP + 1 counts. At a clk_sys of 125 MHz, from 8 Hz to 62.5 MHz; up to 1907 Hz the period has the full 65535 counts. InvalidInput outside that range.

pub fn timing(clock_hz: u32, frequency_hz: u32) -> Timing!hal.Error

divided

Function · Source

A timing with a given divider, in sixteenths, and TOP. InvalidInput if either is out of range.

pub fn divided(clock_hz: u32, divider: u32, top: u32) -> Timing!hal.Error

Channel

Struct · Source

One output of a slice, driving the GPIO it is routed to. Implements hal.PwmOutput: max_duty is TOP + 1, so a duty of 0 holds the output low and max_duty holds it high.

pub struct Channel<R: hal.Registers>: hal.PwmOutput {
    // Private implementation fields omitted.
}

Channel.new

Function · Source

Start output output_of(pin) of slice slice_of(pin) at timing, low. If the slice’s other output is already in use, the slice keeps running and timing must be what it runs at: Busy otherwise, and Busy if this output is in use too. InvalidInput above GPIO 47 or for a GPIO whose slice the block lacks. The block has the RP2040’s 8 slices, which places its wrap flags; new_in names another count. SAFETY: registers must be the PWM block’s, out of reset and clocked at timing.clock_hz, and only Channels may use it.

pub unsafe fn new(registers: R, pin: u32, timing: Timing) -> Channel<R>!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Channel.new_in

Function · Source

new in a block of slices slices: 8 on the RP2040, 12 on the RP2350. SAFETY: as for new.

pub unsafe fn new_in(registers: R, slices: u32, pin: u32, timing: Timing) -> Channel<R>!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Channel.max_duty

Function · Source

pub fn max_duty(&self) -> u16

Channel.set_duty

Function · Source

The output is high for duty / max_duty of each period, from the next period on. InvalidInput above max_duty.

pub fn set_duty(&mut self, duty: u16) -> void!hal.Error

Channel.duty

Function · Source

The duty last set.

pub fn duty(&self) -> u16

Channel.timing

Function · Source

The slice’s divider and TOP.

pub fn timing(&self) -> Timing

Channel.frequency_hz

Function · Source

pub fn frequency_hz(&self) -> u32

Channel.pin

Function · Source

The GPIO the output was started for.

pub fn pin(&self) -> u32

Channel.slice

Function · Source

The slice, 0 to 7, and the output within it, 0 for A and 1 for B.

pub fn slice(&self) -> u32

Channel.output

Function · Source

pub fn output(&self) -> u32

Channel.set_frequency

Function · Source

Change the frequency to the closest to frequency_hz, as timing finds it, keeping the duty cycle. Busy if the slice’s other output is in use, since it shares the frequency, unless the timing does not change; InvalidInput if the frequency is out of range.

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

Channel.set_timing

Function · Source

Change the divider and TOP, as from divided, keeping the duty cycle as closely as the new duty steps allow. Busy as for set_frequency.

pub fn set_timing(&mut self, timing: Timing) -> void!hal.Error

Channel.set_inverted

Function · Source

Invert the output: high while the count is at or above the compare value instead of below it.

pub fn set_inverted(&mut self, inverted: bool)

Channel.count

Function · Source

The slice’s count, 0 to TOP, which advances while the slice runs.

pub fn count(&mut self) -> u32

Channel.wrapped

Function · Source

Whether the slice’s counter wrapped, ending a period, since the flag was last cleared. The flag and the wrap interrupt belong to the slice, so both outputs of a slice see them; with both in use, let one of them handle the interrupt. Compare values set in a period take effect at its wrap, so a handler that sets the next duty has a whole period to do it.

pub fn wrapped(&mut self) -> bool

Channel.clear_wrap

Function · Source

Clear the wrap flag. A wrap interrupt handler has to, or the interrupt stays raised.

pub fn clear_wrap(&mut self)

Channel.listen_wrap

Function · Source

Raise the wrap interrupt, PWM_IRQ_WRAP on the RP2040 and PWM_IRQ_WRAP_0 on the RP2350, while the wrap flag is set.

pub fn listen_wrap(&mut self)

Channel.ignore_wrap

Function · Source

Stop raising the wrap interrupt; wrapped still reports.

pub fn ignore_wrap(&mut self)

Channel.is_listening_wrap

Function · Source

pub fn is_listening_wrap(&mut self) -> bool

Channel.release

Function · Source

Hold the output low and give it up, and stop the slice if its other output is not in use either, with its wrap interrupt off and its flag clear. Returns the registers.

pub fn release(self) -> R

Pwm

Struct · Source

An output on the chip: a Channel over the PWM block’s registers, which the chip packages hand out. Implements hal.PwmOutput.

pub struct Pwm: hal.PwmOutput {
    // Private implementation fields omitted.
}

Pwm.at

Function · Source

Channel.new_in over the block at base, of slices slices, whose wrap interrupt is irq. SAFETY: as for Channel.new, with base the PWM block’s base address.

pub unsafe fn at(base: usize, slices: u32, irq: u32, pin: u32, timing: Timing) -> Pwm!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Pwm.irq

Function · Source

The wrap interrupt, for cortex_m.enable and @interrupt: PWM_IRQ_WRAP on the RP2040, PWM_IRQ_WRAP_0 on the RP2350. Every slice raises it, so its handler checks wrapped on each output or timer it listens for.

pub fn irq(&self) -> u32

Pwm.wrapped

Function · Source

pub fn wrapped(&mut self) -> bool

Pwm.clear_wrap

Function · Source

pub fn clear_wrap(&mut self)

Pwm.listen_wrap

Function · Source

pub fn listen_wrap(&mut self)

Pwm.ignore_wrap

Function · Source

pub fn ignore_wrap(&mut self)

Pwm.is_listening_wrap

Function · Source

pub fn is_listening_wrap(&mut self) -> bool

Pwm.max_duty

Function · Source

pub fn max_duty(&self) -> u16

Pwm.set_duty

Function · Source

pub fn set_duty(&mut self, duty: u16) -> void!hal.Error

Pwm.duty

Function · Source

pub fn duty(&self) -> u16

Pwm.timing

Function · Source

pub fn timing(&self) -> Timing

Pwm.frequency_hz

Function · Source

pub fn frequency_hz(&self) -> u32

Pwm.pin

Function · Source

pub fn pin(&self) -> u32

Pwm.slice

Function · Source

pub fn slice(&self) -> u32

Pwm.output

Function · Source

pub fn output(&self) -> u32

Pwm.set_frequency

Function · Source

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

Pwm.set_timing

Function · Source

pub fn set_timing(&mut self, timing: Timing) -> void!hal.Error

Pwm.set_inverted

Function · Source

pub fn set_inverted(&mut self, inverted: bool)

Pwm.count

Function · Source

pub fn count(&mut self) -> u32

Pwm.release

Function · Source

Channel.release; returns the block’s base address.

pub fn release(self) -> usize

MAX_EDGE_DIVIDER

Constant · Source

The largest whole divider in edge windows.

pub const MAX_EDGE_DIVIDER: u32 = 255

interrupt_offset

Function · Source

The offset of INTR, the raw interrupt flags, in a PWM block of slices slices: 8 on the RP2040 (0xA4), 12 on the RP2350 (0xF4). It follows the slices’ registers and EN.

pub fn interrupt_offset(slices: u32) -> usize

capture_divider

Function · Source

The divider, in sixteenths, that level windows of window_us count with at clock_hz: the smallest that covers four windows in 65535 counts, or as many windows as MAX_DIVIDER covers. InvalidInput for a window of 0 or one longer than MAX_DIVIDER covers: 134 ms at a clk_sys of 125 MHz, 111 ms at 150 MHz.

pub fn capture_divider(clock_hz: u32, window_us: u32) -> u32!hal.Error

max_window_us

Function · Source

The longest window, in microseconds, at clock_hz: what 65535 counts at MAX_DIVIDER cover.

pub fn max_window_us(clock_hz: u32) -> u32

Capture

Struct · Source

Input capture on the B pin of a slice, over any hal.Registers: a hal.RegisterBlock at the PWM block’s base on the chip, or a simulated block in a desktop test. The caller passes the time to each poll, in microseconds from any fixed start; PwmCapture reads the chip’s timer itself and implements hal.PwmInput. The input claims both outputs of its slice, since it uses the slice’s counter.

pub struct Capture<R: hal.Registers> {
    // Private implementation fields omitted.
}

Capture.new

Function · Source

Start measuring the signal on GPIO pin, output B of slice slice_of(pin), at now_us, in windows of window_us; see capture_divider for the range. slices is the number of slices of the block, 8 on the RP2040 and 12 on the RP2350, which places INTR. InvalidInput for an even pin (output A cannot count), above GPIO 47 or on a slice the block lacks, or for a window out of range; Busy if either output of the slice is in use, by a Channel or another Capture. SAFETY: registers must be the PWM block’s, out of reset and clocked at clock_hz, and only Channels and Captures may use it; nothing else may clear the slice’s INTR flag.

pub unsafe fn new(registers: R, slices: u32, clock_hz: u32, pin: u32, window_us: u32, now_us: u64) -> Capture<R>!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Capture.poll

Function · Source

Advance the measurement to now_us, without waiting, as hal.PwmInput.poll_capture does: true with capture set once a measurement has finished since the last call that returned true, false while none has. Overrun if a count wrapped in a way the input cannot recover from: an edge window that wraps even at MAX_EDGE_DIVIDER (a signal near clk_sys / 2, or polls far apart), or a level window that outlasts what its divider covers (a poll more than about three windows late). The measurement then starts over.

pub fn poll(&mut self, now_us: u64, capture: &mut hal.PulseCapture) -> bool!hal.Error

Capture.pin

Function · Source

The GPIO measured.

pub fn pin(&self) -> u32

Capture.slice

Function · Source

The slice, 0 to 7, whose counter measures.

pub fn slice(&self) -> u32

Capture.window_us

Function · Source

The window length, in microseconds; a measurement takes two.

pub fn window_us(&self) -> u32

Capture.level_divider

Function · Source

The level windows’ divider, in sixteenths, from capture_divider.

pub fn level_divider(&self) -> u32

Capture.edge_divider

Function · Source

The whole divider the next or running edge window counts edges with, 1 to MAX_EDGE_DIVIDER.

pub fn edge_divider(&self) -> u32

Capture.level_resolution_ps

Function · Source

The time a level count stands for, in picoseconds: divider / 16 clk_sys cycles, the high time’s resolution in one window.

pub fn level_resolution_ps(&self) -> u64

Capture.release

Function · Source

Stop the slice and give it up: it is left disabled, free-running (DIVMODE 0), at a divider of 1 and a TOP of 65535, with its wrap flag clear, so both outputs can be opened again. Returns the registers.

pub fn release(self) -> R

PwmCapture

Struct · Source

Input capture on the chip: a Capture over the PWM block’s registers, timed by the chip’s microsecond timer, which the chip packages hand out. Implements hal.PwmInput.

pub struct PwmCapture: hal.PwmInput {
    // Private implementation fields omitted.
}

PwmCapture.at

Function · Source

Capture.new over the block at base, timed by the microsecond timer at timer, whose TIMERAWH and TIMERAWL registers are at 0x24 and 0x28 on both chips. Errors as for Capture.new. SAFETY: as for Capture.new, with base the PWM block’s base address and timer a running microsecond timer’s.

pub unsafe fn at(base: usize, slices: u32, timer: usize, clock_hz: u32, pin: u32, window_us: u32) -> PwmCapture!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

PwmCapture.poll_capture

Function · Source

Capture.poll at the timer’s time.

pub fn poll_capture(&mut self, capture: &mut hal.PulseCapture) -> bool!hal.Error

PwmCapture.pin

Function · Source

pub fn pin(&self) -> u32

PwmCapture.slice

Function · Source

pub fn slice(&self) -> u32

PwmCapture.window_us

Function · Source

pub fn window_us(&self) -> u32

PwmCapture.level_divider

Function · Source

pub fn level_divider(&self) -> u32

PwmCapture.edge_divider

Function · Source

pub fn edge_divider(&self) -> u32

PwmCapture.level_resolution_ps

Function · Source

pub fn level_resolution_ps(&self) -> u64

PwmCapture.release

Function · Source

Capture.release; returns the block’s base address.

pub fn release(self) -> usize

claimed

Function · Source

The bits of CLAIMED in use: outputs, inputs, and timers, two bits per slice. The chip packages hold the block in reset while none is.

pub fn claimed() -> u32

MIN_PERIOD_US

Constant · Source

The shortest period, in microseconds.

pub const MIN_PERIOD_US: u64 = 8

MAX_PERIOD_TICKS

Constant · Source

The longest period, in ticks: the counter’s 16 bits.

pub const MAX_PERIOD_TICKS: u64 = 0x1_0000

timer_divider

Function · Source

The divider, in sixteenths, that makes a slice count at tick_hz from clock_hz: clock_hz / tick_hz, which must be a whole number of sixteenths from 1 to 255 15/16. At a clk_sys of 125 MHz, for example, 125 MHz, 10 MHz, 1 MHz, or 500 kHz; 488.3 kHz is the slowest rate. InvalidInput otherwise.

pub fn timer_divider(clock_hz: u32, tick_hz: u32) -> u32!hal.Error

SliceTimer

Struct · Source

A slice as a periodic timer and a counter, over a PWM block and the chip’s microsecond timer, each any rp_timer.Block: rp_timer.Mmio on the chip, or a simulated block in a desktop test. It claims both outputs of its slice and drives no pins. PwmTimer is the chip’s, which the chip packages hand out. Implements hal.PeriodicTimer and hal.TickCounter.

pub struct SliceTimer<B: rp_timer.Block>: hal.PeriodicTimer + hal.TickCounter {
    // Private implementation fields omitted.
}

SliceTimer.new

Function · Source

Slice slice of a block of slices slices (8 on the RP2040, 12 on the RP2350, whose slices 8 to 11 reach no pins but count as timers), counting at tick_hz from clock_hz; see timer_divider for the rates. It starts stopped. InvalidInput for another slice or rate; Busy if either output of the slice is in use. SAFETY: pwm must be the PWM block’s, out of reset and clocked at clock_hz, used only by Channels, Captures, and SliceTimers, and clock a running microsecond timer from the same crystal; nothing else may clear the slice’s INTR flag or change its INTE bit.

pub unsafe fn new(pwm: B, clock: B, slices: u32, clock_hz: u32, slice: u32, tick_hz: u32) -> SliceTimer<B>!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

SliceTimer.tick_hz

Function · Source

pub fn tick_hz(&self) -> u32

SliceTimer.slice

Function · Source

The slice, 0 to 11.

pub fn slice(&self) -> u32

SliceTimer.period_ticks

Function · Source

The period start set, in ticks; 0 before the first start.

pub fn period_ticks(&self) -> u64

SliceTimer.is_running

Function · Source

pub fn is_running(&self) -> bool

SliceTimer.start

Function · Source

Wrap every period_ticks ticks, 1 to MAX_PERIOD_TICKS and at least MIN_PERIOD_US long, the first time one period from now. The counter starts the period from 0; now_ticks carries on from where it was. InvalidInput for a period out of range.

pub fn start(&mut self, period_ticks: u64) -> void!hal.Error

SliceTimer.cancel

Function · Source

Stop the counter; now_ticks holds still until the next start.

pub fn cancel(&mut self)

SliceTimer.poll_periods

Function · Source

How many periods ended since start or the last call. Clears the wrap flag first, so a wrap interrupt handler calls it; a wrap that lands right after the clear sets the flag again but is counted now, so the next call may return 0.

pub fn poll_periods(&mut self) -> u32

SliceTimer.now_ticks

Function · Source

Ticks since the timer was opened, counted while it ran: the 16-bit counter extended by the microsecond timer.

pub fn now_ticks(&self) -> u64

SliceTimer.count

Function · Source

The counter’s position in the period, 0 to period - 1.

pub fn count(&self) -> u32

SliceTimer.wrapped

Function · Source

Whether the counter wrapped since the flag was last cleared.

pub fn wrapped(&self) -> bool

SliceTimer.listen

Function · Source

Raise the wrap interrupt, PWM_IRQ_WRAP on the RP2040 and PWM_IRQ_WRAP_0 on the RP2350, when a period ends.

pub fn listen(&mut self)

SliceTimer.ignore

Function · Source

pub fn ignore(&mut self)

SliceTimer.is_listening

Function · Source

pub fn is_listening(&self) -> bool

SliceTimer.release

Function · Source

Stop the slice and give it up, with its interrupt off, its flag clear, and its registers as Capture.release leaves them. Returns the PWM block.

pub fn release(self) -> B

extend_count

Function · Source

The ticks a counter of period ticks at tick_hz has counted since it started from 0 elapsed_us microseconds ago, now showing count: of the values that show count, a whole number of periods plus count, the one closest to what the elapsed time says. Exact while the elapsed time is right to within half a period, as it is from MIN_PERIOD_US on.

pub fn extend_count(elapsed_us: u64, count: u32, period: u64, tick_hz: u32) -> u64

PwmTimer

Struct · Source

A slice as a timer on the chip: a SliceTimer over the PWM block and the microsecond timer’s registers, which the chip packages hand out. Implements hal.PeriodicTimer and hal.TickCounter.

pub struct PwmTimer: hal.PeriodicTimer + hal.TickCounter {
    // Private implementation fields omitted.
}

PwmTimer.at

Function · Source

SliceTimer.new over the PWM block at base and the microsecond timer at timer, raising wrap interrupt irq. Errors as for SliceTimer.new. SAFETY: as for SliceTimer.new, with base the PWM block’s base address and timer a running microsecond timer’s.

pub unsafe fn at(base: usize, timer: usize, slices: u32, irq: u32, clock_hz: u32, slice: u32, tick_hz: u32) -> PwmTimer!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

PwmTimer.irq

Function · Source

The wrap interrupt, for cortex_m.enable and @interrupt: PWM_IRQ_WRAP on the RP2040, PWM_IRQ_WRAP_0 on the RP2350. Every slice raises it, so its handler polls each timer it listens for.

pub fn irq(&self) -> u32

PwmTimer.tick_hz

Function · Source

pub fn tick_hz(&self) -> u32

PwmTimer.slice

Function · Source

pub fn slice(&self) -> u32

PwmTimer.period_ticks

Function · Source

pub fn period_ticks(&self) -> u64

PwmTimer.is_running

Function · Source

pub fn is_running(&self) -> bool

PwmTimer.start

Function · Source

pub fn start(&mut self, period_ticks: u64) -> void!hal.Error

PwmTimer.cancel

Function · Source

pub fn cancel(&mut self)

PwmTimer.poll_periods

Function · Source

pub fn poll_periods(&mut self) -> u32

PwmTimer.now_ticks

Function · Source

pub fn now_ticks(&self) -> u64

PwmTimer.count

Function · Source

pub fn count(&self) -> u32

PwmTimer.wrapped

Function · Source

pub fn wrapped(&self) -> bool

PwmTimer.listen

Function · Source

pub fn listen(&mut self)

PwmTimer.ignore

Function · Source

pub fn ignore(&mut self)

PwmTimer.is_listening

Function · Source

pub fn is_listening(&self) -> bool

PwmTimer.release

Function · Source

SliceTimer.release; returns the PWM block’s base address.

pub fn release(self) -> usize

Search every guide, reference page, and API declaration.