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:registersmust be the converter’s, started withstart, 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, withbasethe 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
indexof a round throughinputscomes from, counting from 0 at the lowest input: the inputs in ascending order, round and round. A capture’s sampleindexcomes from this input.
pub fn input_at(inputs: Inputs, index: usize) -> u32
divider_for
Function · Source
The DIV value that starts
rate_hzconversions 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
dividerstarts, 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.
startempties the FIFO and begins a round at the lowest input;poll_readandreadthen 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, whichpoll_readreports once as Overrun, starting over. DMA keeps up at any rate:capture_atfills a buffer,dma_atdoes so in the background, andstream_atkeeps 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 convertsrate_hztimes a second in all, so each of n inputsrate_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:registersmust be the converter’s, started withstart, 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
indexof a capture; see input_at.
pub fn input_at(&self, index: usize) -> u32
Sampler.next_input
Function · Source
The input the next sample
poll_readreturns comes from.
pub fn next_input(&self) -> u32
Sampler.set_rate
Function · Source
Convert
rate_hztimes 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
levelsamples 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
readafterpollspolls 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
samplesby DMA throughchannel, from a fresh round, and wait: sample i comes from input_at(i), tagged like poll_read’s.fifois 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
samplesby 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
ringby DMA until it is dropped; see Stream. Busy if the sampler runs or the channel is busy; InvalidInput ifringholds 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_atorAdcSampler.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
countsamples 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
countsamples 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_atorAdcSampler.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
ringwhose 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 isirq. SAFETY: as for Sampler.new, withbasethe 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:
listenraises 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
signalwhenever 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
samplesby 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
sampleswith 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
samplesin 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