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
pinwithin 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
timingordivided.
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_hzwith 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 sliceslice_of(pin)attiming, low. If the slice’s other output is already in use, the slice keeps running andtimingmust 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:registersmust 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
newin a block ofslicesslices: 8 on the RP2040, 12 on the RP2350. SAFETY: as fornew.
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, astimingfinds 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;
wrappedstill 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, ofslicesslices, whose wrap interrupt isirq. SAFETY: as for Channel.new, withbasethe 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 checkswrappedon 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
slicesslices: 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_uscount with atclock_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.RegisterBlockat 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;PwmCapturereads 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 sliceslice_of(pin), atnow_us, in windows ofwindow_us; see capture_divider for the range.slicesis 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:registersmust be the PWM block’s, out of reset and clocked atclock_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 withcaptureset 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 attimer, whose TIMERAWH and TIMERAWL registers are at 0x24 and 0x28 on both chips. Errors as for Capture.new. SAFETY: as for Capture.new, withbasethe PWM block’s base address andtimera 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_hzfromclock_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.
PwmTimeris 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
sliceof a block ofslicesslices (8 on the RP2040, 12 on the RP2350, whose slices 8 to 11 reach no pins but count as timers), counting attick_hzfromclock_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:pwmmust be the PWM block’s, out of reset and clocked atclock_hz, used only by Channels, Captures, and SliceTimers, andclocka 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
startset, 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_ticksticks, 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
startor 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
periodticks attick_hzhas counted since it started from 0elapsed_usmicroseconds ago, now showingcount: of the values that showcount, a whole number of periods pluscount, 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
baseand the microsecond timer attimer, raising wrap interruptirq. Errors as for SliceTimer.new. SAFETY: as for SliceTimer.new, withbasethe PWM block’s base address andtimera 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