API referencestd/embedded

std/embedded/chip/rp_adc

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

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

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
cortex_m std/embedded/cortex_m rp_adc.dodo
cpu core/cpu rp_adc.dodo
executor std/embedded/executor rp_adc.dodo
hal std/embedded/hal rp_adc.dodo
mmio core/mmio rp_adc.dodo
ptr core/ptr rp_adc.dodo

MAX_VALUE

Constant · Source

The converter’s 12-bit range.

pub const MAX_VALUE: u16 = 4095

TEMPERATURE_INPUT

Constant · Source

The input that measures the temperature sensor.

pub const TEMPERATURE_INPUT: u32 = 4

FIRST_PIN

Constant · Source

GPIO 26 to 29 are inputs 0 to 3.

pub const FIRST_PIN: u32 = 26

PIN_COUNT

Constant · Source

pub const PIN_COUNT: u32 = 4

Inputs

Type alias · Source

A set of inputs for a Sampler, one bit per input number.

pub type Inputs = u32

GPIO26

Constant · Source

pub const GPIO26: Inputs = 1 << 0

GPIO27

Constant · Source

pub const GPIO27: Inputs = 1 << 1

GPIO28

Constant · Source

pub const GPIO28: Inputs = 1 << 2

GPIO29

Constant · Source

pub const GPIO29: Inputs = 1 << 3

TEMPERATURE

Constant · Source

pub const TEMPERATURE: Inputs = 1 << 4

ALL_INPUTS

Constant · Source

pub const ALL_INPUTS: Inputs = 0x1F

CLOCK_HZ

Constant · Source

The converter’s clock, clk_adc, which the chip packages run at 48 MHz.

pub const CLOCK_HZ: u32 = 48_000_000

MAX_RATE_HZ

Constant · Source

A conversion takes 96 cycles, so the converter makes at most 500 000 a second; DIV’s 16-bit integer part stretches the period to at most 65 536 cycles and a fraction, 733 a second.

pub const MAX_RATE_HZ: u32 = 500_000

MIN_RATE_HZ

Constant · Source

pub const MIN_RATE_HZ: u32 = 733

FIFO_DEPTH

Constant · Source

The FIFO’s depth, the highest threshold.

pub const FIFO_DEPTH: u32 = 8

SAMPLE_VALUE

Constant · Source

The parts of a tagged sample.

pub const SAMPLE_VALUE: u16 = 0x0FFF

SAMPLE_INPUT

Constant · Source

pub const SAMPLE_INPUT: u16 = 0x7000

SAMPLE_FAILED

Constant · Source

pub const SAMPLE_FAILED: u16 = 0x8000

MIN_RING

Constant · Source

The smallest ring a Stream uses, the FIFO’s 8 samples, and the largest, 32 KiB, as DMA rings go; as powers of two, in bytes.

pub const MIN_RING: usize = 8

input_of

Function · Source

The input of GPIO pin; InvalidInput for a pin without one.

pub fn input_of(pin: u32) -> u32!hal.Error

start

Function · Source

Turn the converter on and wait until it is ready, after its reset. Timeout if it does not become ready.

pub fn start<R: hal.Registers>(registers: &mut R) -> void!hal.Error

stop

Function · Source

Turn the converter and the temperature sensor off.

pub fn stop<R: hal.Registers>(registers: &mut R)

millicelsius

Function · Source

The temperature in thousandths of a degree Celsius that a reading of the temperature sensor shows, for a converter whose reference is reference_mv: 27 C at 706 mV, falling 1.721 mV per degree (RP2040 datasheet 4.9.5, RP2350 datasheet 12.4.6). The sensor is accurate to a few degrees, and the result depends on the reference being exact.

pub fn millicelsius(value: u16, reference_mv: u32) -> i32

Input

Struct · Source

One input of the converter. Implements hal.AnalogInput.

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

Input.new

Function · Source

Input input, 0 to 3 for GPIO 26 to 29 or TEMPERATURE_INPUT, which powers the temperature sensor until release. SAFETY: registers must be the converter’s, started with start, and only Inputs may use it, one for each input number.

pub unsafe fn new(registers: R, input: u32) -> Input<R>

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

Input.max_value

Function · Source

pub fn max_value(&self) -> u16

Input.input

Function · Source

The input number, 0 to 4.

pub fn input(&self) -> u32

Input.read

Function · Source

Convert once: 0 at ground to MAX_VALUE at the reference. Timeout if the conversion does not finish, Bus if the converter reports that it failed.

pub fn read(&mut self) -> u16!hal.Error

Input.release

Function · Source

Stop the temperature sensor, if this is its input, and give back the registers.

pub fn release(self) -> R

Analog

Struct · Source

An input on the chip: an Input over the converter’s registers, which the chip packages hand out. Implements hal.AnalogInput.

pub struct Analog: hal.AnalogInput {
    // Private implementation fields omitted.
}

Analog.at

Function · Source

Input.new over the converter at base. SAFETY: as for Input.new, with base the converter’s base address.

pub unsafe fn at(base: usize, input: u32) -> Analog

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

Analog.max_value

Function · Source

pub fn max_value(&self) -> u16

Analog.read

Function · Source

pub fn read(&mut self) -> u16!hal.Error

Analog.input

Function · Source

pub fn input(&self) -> u32

Analog.release

Function · Source

Input.release; returns the converter’s base address.

pub fn release(self) -> usize

sample_value

Function · Source

The value of a tagged sample: 0 to MAX_VALUE, or 0 to 255 from a sampler in eight-bit mode.

pub fn sample_value(sample: u16) -> u16

sample_input

Function · Source

The input a tagged sample came from, 0 to 4.

pub fn sample_input(sample: u16) -> u32

sample_failed

Function · Source

Whether the converter flagged a tagged sample’s conversion as failed; its value is then undefined or noisy.

pub fn sample_failed(sample: u16) -> bool

pin_input

Function · Source

The bit of GPIO pin’s input in a set of Inputs; InvalidInput for a pin without one.

pub fn pin_input(pin: u32) -> Inputs!hal.Error

pins_of

Function · Source

The GPIOs of the inputs in inputs, one bit per GPIO number.

pub fn pins_of(inputs: Inputs) -> u32

check_inputs

Function · Source

InvalidInput for an empty set of inputs or one with inputs beyond 4.

pub fn check_inputs(inputs: Inputs) -> void!hal.Error

input_count

Function · Source

The number of inputs in inputs.

pub fn input_count(inputs: Inputs) -> u32

input_at

Function · Source

The input that sample index of a round through inputs comes from, counting from 0 at the lowest input: the inputs in ascending order, round and round. A capture’s sample index comes from this input.

pub fn input_at(inputs: Inputs, index: usize) -> u32

divider_for

Function · Source

The DIV value that starts rate_hz conversions a second: DIV holds a period of 1 + INT + FRAC / 256 clk_adc cycles (4.9.2.2), rounded here to the nearest 1/256 cycle, and the converter’s delta-sigma divider keeps that period on average. InvalidInput outside MIN_RATE_HZ to MAX_RATE_HZ.

pub fn divider_for(rate_hz: u32) -> u32!hal.Error

rate_of

Function · Source

The conversions a second that DIV value divider starts, rounded. A period below a conversion’s 96 cycles, 0 included, runs conversions back to back, MAX_RATE_HZ.

pub fn rate_of(divider: u32) -> u32

Sampler

Struct · Source

The converter running by itself over registers R, any hal.Registers: a set of inputs converted round-robin at a steady rate into the FIFO, read by polling, from the FIFO interrupt, or by DMA.

A sampler starts stopped. start empties the FIFO and begins a round at the lowest input; poll_read and read then return tagged samples in the order they were converted. The FIFO holds 8 samples, 16 us at the highest rate: a program that falls further behind loses samples, which poll_read reports once as Overrun, starting over. DMA keeps up at any rate: capture_at fills a buffer, dma_at does so in the background, and stream_at keeps filling a ring. They take a stopped sampler and leave it stopped.

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

Sampler.new

Function · Source

A sampler of inputs, a set such as GPIO26 | TEMPERATURE, that converts rate_hz times a second in all, so each of n inputs rate_hz / n times; stopped. A set with TEMPERATURE powers the temperature sensor until release. InvalidInput for an empty set, one beyond ALL_INPUTS, or a rate outside MIN_RATE_HZ to MAX_RATE_HZ. SAFETY: registers must be the converter’s, started with start, and only this sampler may use it until it is released.

pub unsafe fn new(registers: R, inputs: Inputs, rate_hz: u32) -> Sampler<R>!hal.Error

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

Sampler.inputs

Function · Source

The set of inputs, and how many it has.

pub fn inputs(&self) -> Inputs

Sampler.input_count

Function · Source

pub fn input_count(&self) -> u32

Sampler.input_at

Function · Source

The input of sample index of a capture; see input_at.

pub fn input_at(&self, index: usize) -> u32

Sampler.next_input

Function · Source

The input the next sample poll_read returns comes from.

pub fn next_input(&self) -> u32

Sampler.set_rate

Function · Source

Convert rate_hz times a second, from now if running; see divider_for. The rate is rounded to 1/256 of a clk_adc cycle.

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

Sampler.set_divider

Function · Source

Set DIV directly: a period of 1 + divider / 256 clk_adc cycles, divider up to 0xFF_FFFF; below 95 * 256, conversions run back to back. InvalidInput above that.

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

Sampler.divider

Function · Source

The DIV value, and the conversions a second it gives.

pub fn divider(&self) -> u32

Sampler.rate_hz

Function · Source

pub fn rate_hz(&self) -> u32

Sampler.set_eight_bit

Function · Source

Shift samples to 8 bits, 0 to 255, for polled reads (FCS.SHIFT). Busy while running.

pub fn set_eight_bit(&mut self, on: bool) -> void!hal.Error

Sampler.is_eight_bit

Function · Source

pub fn is_eight_bit(&self) -> bool

Sampler.set_threshold

Function · Source

Raise the FIFO interrupt while at least level samples wait, 1 to FIFO_DEPTH (1 at first); InvalidInput otherwise.

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

Sampler.threshold

Function · Source

pub fn threshold(&self) -> u32

Sampler.set_poll_limit

Function · Source

Give up a read after polls polls without a sample; hal.NO_POLL_LIMIT never does. hal.DEFAULT_POLL_LIMIT at first.

pub fn set_poll_limit(&mut self, polls: u32)

Sampler.start

Function · Source

Start converting, or start over if running: the FIFO is emptied and a round begins at the lowest input.

pub fn start(&mut self)

Sampler.stop

Function · Source

Stop converting. Samples still in the FIFO are dropped.

pub fn stop(&mut self)

Sampler.is_running

Function · Source

pub fn is_running(&self) -> bool

Sampler.available

Function · Source

The samples waiting in the FIFO, up to FIFO_DEPTH.

pub fn available(&mut self) -> u32

Sampler.poll_read

Function · Source

Move the samples waiting in the FIFO into samples, tagged with their inputs, up to its length, without waiting; returns how many. Overrun if the FIFO overflowed since the last read: samples were lost, those it held are dropped, and the sampler starts over at the lowest input.

pub fn poll_read(&mut self, samples: &mut[u16]) -> usize!hal.Error

Sampler.read

Function · Source

Fill samples, waiting for them; Timeout after the poll limit passes without a sample, as when the sampler is stopped, and Overrun as for poll_read, either way with the samples read so far dropped.

pub fn read(&mut self, samples: &mut[u16]) -> void!hal.Error

Sampler.listen

Function · Source

Raise the converter’s interrupt, ADC_IRQ_FIFO, while the threshold’s number of samples wait; reading them ends it.

pub fn listen(&mut self)

Sampler.ignore

Function · Source

Stop raising it.

pub fn ignore(&mut self)

Sampler.is_listening

Function · Source

pub fn is_listening(&mut self) -> bool

Sampler.is_pending

Function · Source

True while the interrupt is raised.

pub fn is_pending(&mut self) -> bool

Sampler.capture_at

Function · Source

Fill samples by DMA through channel, from a fresh round, and wait: sample i comes from input_at(i), tagged like poll_read’s. fifo is the FIFO’s address as the channel sees it, which the chip packages know. Busy if the sampler runs or the channel is busy; InvalidInput for more samples than the channel moves at once; Overrun if the channel fell eight samples behind; Timeout if it moves nothing for the poll limit; Bus on a bus error. The sampler is stopped afterwards.

pub fn capture_at(&mut self, fifo: usize, channel: &mut dyn hal.DmaChannel, samples: &mut[u16]) -> void!hal.Error

Sampler.capture_bytes_at

Function · Source

capture_at with eight-bit samples, 0 to 255, untagged: half the memory, for twice the samples. Errors as for capture_at.

pub fn capture_bytes_at(&mut self, fifo: usize, channel: &mut dyn hal.DmaChannel, samples: &mut[u8]) -> void!hal.Error

Sampler.dma_at

Function · Source

A session that captures into samples by DMA in the background, until it is dropped; see Capture. Busy if the sampler runs or the channel is busy.

pub fn dma_at(&mut self, fifo: usize, channel: &mut dyn hal.DmaChannel, samples: &mut[u16]) -> Capture!hal.Error from(self, channel, samples)

Sampler.stream_at

Function · Source

A session that keeps converting into a ring within ring by DMA until it is dropped; see Stream. Busy if the sampler runs or the channel is busy; InvalidInput if ring holds no aligned block of MIN_RING samples.

pub fn stream_at(&mut self, fifo: usize, channel: &mut dyn hal.DmaChannel, ring: &mut[u16]) -> Stream!hal.Error from(self, channel, ring)

Sampler.release

Function · Source

Stop, turn the interrupt off, power the temperature sensor down if the set has it, and give back the registers.

pub fn release(self) -> R

Capture

Struct · Source

A capture of samples by DMA that runs in the background, from Sampler.dma_at or AdcSampler.dma. It holds the sampler, the channel, and the buffer, and lends the buffer out only between captures:

capture.start(256)? … other work, or return Pending from a task … if capture.poll_finish()? { … read capture.buffer()? … }

Each capture is a fresh round from the lowest input: sample i comes from input_at(i), and once it is done the buffer holds samples tagged as poll_read’s are. The channel’s signal tells a task when a capture is done. Dropping the session aborts a running capture and stops the sampler.

pub struct Capture {
    // Private implementation fields omitted.
}

Capture.buffer

Function · Source

The buffer, between captures; Busy while one runs.

pub fn buffer(&mut self) -> &mut[u16]!hal.Error from(self)

Capture.capacity

Function · Source

The buffer’s length in samples, the most a capture takes.

pub fn capacity(&self) -> usize

Capture.start

Function · Source

Start capturing count samples into buffer[..count], and return at once. InvalidInput for 0, more than the capacity, or more than the channel moves at once; Busy while a capture runs.

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

Capture.is_busy

Function · Source

True while a capture runs.

pub fn is_busy(&mut self) -> bool

Capture.remaining

Function · Source

The samples the running capture has yet to take: 0 once it is done.

pub fn remaining(&mut self) -> usize

Capture.poll_finish

Function · Source

Without waiting: true once no capture runs, ending one that is done, false while one does. Overrun if the channel fell eight samples behind, Bus on a bus error; either way the capture is over.

pub fn poll_finish(&mut self) -> bool!hal.Error

Capture.finish

Function · Source

Wait for the running capture, if any, and end it; errors as for poll_finish, and Timeout if the channel moves nothing for the poll limit, which aborts it.

pub fn finish(&mut self) -> void!hal.Error

Capture.capture

Function · Source

Start a capture of count samples and finish it.

pub fn capture(&mut self, count: usize) -> void!hal.Error

Capture.abort

Function · Source

Stop the running capture, if any, and the sampler; the buffer holds part of it, untagged.

pub fn abort(&mut self)

Stream

Struct · Source

A sampler that keeps converting into a ring buffer by DMA, from Sampler.stream_at or AdcSampler.stream, until it is dropped: the channel moves each sample into the ring as the converter makes it, round and round, and the program reads them at its own pace, tagged with their inputs, in the order they were converted. A 4096-sample ring holds 8 ms at 500 000 samples a second.

The ring is the largest block within ring whose size in bytes is a power of two and whose address is a multiple of it, as the channel needs: a static buffer of N samples with @align(2 * N) gives all N, any other buffer at least a quarter of its length (ring_size() tells). Samples the program has not read when the ring comes round again are lost: the next read reports Overrun and continues with the newest sample, still tagged with the right input, since the stream counts every sample the channel moves.

A transfer moves at most the channel’s max_count samples, 2^28 - 1 on the RP2350, 9 minutes at the highest rate; the next read after one ends starts another, while the FIFO holds 8 samples. A read that comes later than that finds the FIFO overflowed, reports Overrun, and starts the stream over. A task polls the stream on a ticker, as the channel raises its signal only when a transfer ends.

pub struct Stream {
    // Private implementation fields omitted.
}

Stream.ring_size

Function · Source

The ring’s size in samples.

pub fn ring_size(&self) -> usize

Stream.available

Function · Source

The samples converted and not yet read, up to the ring’s size.

pub fn available(&mut self) -> usize

Stream.next_input

Function · Source

The input the next sample read comes from.

pub fn next_input(&self) -> u32

Stream.poll_read

Function · Source

Move the samples waiting in the ring into samples, tagged, up to its length, without waiting; returns how many. Overrun if the ring came round over unread samples, which are dropped (reading goes on with the newest), or the FIFO overflowed, which starts the stream over at the lowest input. Bus if a transfer hit a bus error; the stream goes on with a new one.

pub fn poll_read(&mut self, samples: &mut[u16]) -> usize!hal.Error

Stream.read

Function · Source

Fill samples, waiting for them; Timeout after the poll limit passes without a sample, Overrun as for poll_read, either way with the samples read so far dropped.

pub fn read(&mut self, samples: &mut[u16]) -> void!hal.Error

AdcSampler

Struct · Source

A sampler on the chip: a Sampler over the converter’s registers, which the chip packages hand out with pins.sampler(inputs, rate_hz).

pub struct AdcSampler {
    // Private implementation fields omitted.
}

AdcSampler.at

Function · Source

Sampler.new over the converter at base, whose interrupt is irq. SAFETY: as for Sampler.new, with base the converter’s base address.

pub unsafe fn at(base: usize, inputs: Inputs, rate_hz: u32, irq: u32) -> AdcSampler!hal.Error

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

AdcSampler.inputs

Function · Source

pub fn inputs(&self) -> Inputs

AdcSampler.input_count

Function · Source

pub fn input_count(&self) -> u32

AdcSampler.input_at

Function · Source

pub fn input_at(&self, index: usize) -> u32

AdcSampler.next_input

Function · Source

pub fn next_input(&self) -> u32

AdcSampler.set_rate

Function · Source

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

AdcSampler.set_divider

Function · Source

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

AdcSampler.divider

Function · Source

pub fn divider(&self) -> u32

AdcSampler.rate_hz

Function · Source

pub fn rate_hz(&self) -> u32

AdcSampler.set_eight_bit

Function · Source

pub fn set_eight_bit(&mut self, on: bool) -> void!hal.Error

AdcSampler.is_eight_bit

Function · Source

pub fn is_eight_bit(&self) -> bool

AdcSampler.set_threshold

Function · Source

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

AdcSampler.threshold

Function · Source

pub fn threshold(&self) -> u32

AdcSampler.set_poll_limit

Function · Source

pub fn set_poll_limit(&mut self, polls: u32)

AdcSampler.start

Function · Source

pub fn start(&mut self)

AdcSampler.stop

Function · Source

pub fn stop(&mut self)

AdcSampler.is_running

Function · Source

pub fn is_running(&self) -> bool

AdcSampler.available

Function · Source

pub fn available(&mut self) -> u32

AdcSampler.poll_read

Function · Source

pub fn poll_read(&mut self, samples: &mut[u16]) -> usize!hal.Error

AdcSampler.read

Function · Source

pub fn read(&mut self, samples: &mut[u16]) -> void!hal.Error

AdcSampler.irq

Function · Source

The converter’s interrupt, ADC_IRQ_FIFO: its number for cortex_m.enable, and its vector name for @interrupt.

pub fn irq(&self) -> u32

AdcSampler.listen

Function · Source

Interrupts for handlers of your own: listen raises ADC_IRQ_FIFO while the threshold’s number of samples wait. Enable it in the NVIC too: cortex_m.enable(sampler.irq()).

pub fn listen(&mut self)

AdcSampler.ignore

Function · Source

pub fn ignore(&mut self)

AdcSampler.is_listening

Function · Source

pub fn is_listening(&mut self) -> bool

AdcSampler.is_pending

Function · Source

pub fn is_pending(&mut self) -> bool

AdcSampler.set_signal

Function · Source

Raise signal whenever the threshold’s number of samples wait, from the chip runtime’s default ADC_IRQ_FIFO handler, so a task waits for samples instead of polling: take the signal, then poll_read. The handler holds the interrupt back until the next read. Enables the interrupt and ADC_IRQ_FIFO in the NVIC.

pub fn set_signal(&mut self, signal: &executor.Signal)

AdcSampler.clear_signal

Function · Source

Stop raising the signal and the interrupt.

pub fn clear_signal(&mut self)

AdcSampler.capture

Function · Source

Fill samples by DMA and wait; see Sampler.capture_at.

pub fn capture(&mut self, channel: &mut dyn hal.DmaChannel, samples: &mut[u16]) -> void!hal.Error

AdcSampler.capture_bytes

Function · Source

Fill samples with eight-bit samples by DMA and wait; see Sampler.capture_bytes_at.

pub fn capture_bytes(&mut self, channel: &mut dyn hal.DmaChannel, samples: &mut[u8]) -> void!hal.Error

AdcSampler.dma

Function · Source

Capture into samples in the background; see Capture.

pub fn dma(&mut self, channel: &mut dyn hal.DmaChannel, samples: &mut[u16]) -> Capture!hal.Error from(self, channel, samples)

AdcSampler.stream

Function · Source

Keep converting into a ring within ring; see Stream.

pub fn stream(&mut self, channel: &mut dyn hal.DmaChannel, ring: &mut[u16]) -> Stream!hal.Error from(self, channel, ring)

AdcSampler.release

Function · Source

Stop the signal, if set, and Sampler.release; returns the converter’s base address.

pub fn release(self) -> usize

Search every guide, reference page, and API declaration.