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_i2s"
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_i2s.dodo |
rp_pio |
std/embedded/chip/rp_pio |
rp_i2s.dodo |
FIFO_DEPTH
Constant · Source
The joined FIFO’s depth, in words.
pub const FIFO_DEPTH: u32 = 8
CYCLES_PER_BIT
Constant · Source
State machine cycles per bit clock.
pub const CYCLES_PER_BIT: u32 = 4
Channel
Enum · Source
The slot a mono input keeps.
pub enum Channel {
Left,
Right
}
Config
Struct · Source
A stream’s settings, for Output.new and Input.new.
pub struct Config {
// Frames per second.
pub sample_rate: u32
// Bits per sample: 16, 24, or 32.
pub bits: u32
// Samples per frame in the slices the program passes: 1 or 2. The
// wire always carries two slots.
pub channels: u32
pub format: hal.I2sFormat
// Bit clocks per slot: 32, or 16 for 16-bit samples, which halves the
// bit clock and doubles the frames the queue holds. Most devices accept
// both; some, such as the INMP441, need 32.
pub slot_bits: u32
// The slot a mono input keeps; the other is dropped.
pub channel: Channel
}
Config.new
Function · Source
sample_rateframes per second ofchannelssamples ofbitsbits, framed asformat, in 32-bit slots, a mono input keeping the left slot.
pub fn new(sample_rate: u32, bits: u32, channels: u32, format: hal.I2sFormat) -> Config
Timing
Struct · Source
A stream’s clock: the state machine’s divider of clk_sys and the sample rate it gives, from
timing.
pub struct Timing {
// clk_sys, in hertz.
pub clock_hz: u32
// The sample rate asked for.
pub sample_rate: u32
pub slot_bits: u32
// The divider of clk_sys in 256ths, 256 to 0xFF_FFFF.
pub divider: u32
}
Timing.actual_millihertz
Function · Source
The sample rate the divider gives, in millihertz.
pub fn actual_millihertz(&self) -> u64
Timing.actual_rate
Function · Source
The sample rate the divider gives, rounded to whole hertz.
pub fn actual_rate(&self) -> u32
Timing.error_ppm
Function · Source
How far the actual rate is from the rate asked for, in parts per million, rounded: positive when it runs fast.
pub fn error_ppm(&self) -> i32
Timing.bit_clock_hz
Function · Source
The bit clock the divider gives, rounded to whole hertz.
pub fn bit_clock_hz(&self) -> u32
Timing.copy
Function · Source
pub fn copy(&self) -> Timing
timing
Function · Source
The divider closest to
sample_rateframes per second in slots ofslot_bits(16 or 32) from a clk_sys ofclock_hz. InvalidInput for a rate the divider cannot reach or another slot width.
pub fn timing(clock_hz: u32, sample_rate: u32, slot_bits: u32) -> Timing!hal.Error
output_program
Function · Source
The output program for
formatin slots ofslot_bits, 16 or 32; InvalidInput for another width. In 32-bit slots, for Philips framing (left-justified framing has LRCLK high in the left slot and low in the right, throughout each slot):.side_set 2 ; LRCLK, BCLK .out 1 left .fifo tx .mov_status txfifo < 2 ; x: all ones while no whole frame .wrap_target out pins, 1 side 0b00 [1] ; left bit 31 set y, 29 side 0b01 [1] lbits: out pins, 1 side 0b00 [1] ; bits 30 to 1 jmp y– lbits side 0b01 [1] out pins, 1 side 0b10 ; bit 0, under the right’s LRCLK jmp !x take_right side 0b10 jmp right_msb side 0b11 [1] ; no frame: the right sends zeros take_right: pull block side 0b11 [1] right_msb: out pins, 1 side 0b10 [1] ; right bit 31 set y, 29 side 0b11 mov x, status side 0b11 ; a whole frame queued? rbits: out pins, 1 side 0b10 [1] jmp y– rbits side 0b11 [1] out pins, 1 side 0b00 jmp !x take_left side 0b00 jmp 0 side 0b01 [1] ; no frame: send zeros take_left: pull block side 0b01 [1] .wrap
Each bit takes four cycles, BCLK low for two and high for two. The OSR shifts left and fills with zeros, so a slot that pulled nothing sends zeros; the program pulls a frame’s two words only when both are queued, deciding once a frame with
mov x, status, and so never stalls. Start it with OSR zero and X all ones. In 16-bit slots a word holds a frame, left in its upper half:.side_set 2 .out 1 left .fifo tx .wrap_target out pins, 1 side 0b00 [1] ; left bit 15 set y, 13 side 0b01 [1] lbits: out pins, 1 side 0b00 [1] ; bits 14 to 1 jmp y– lbits side 0b01 [1] out pins, 1 side 0b10 [1] ; bit 0 set y, 14 side 0b11 [1] rbits: out pins, 1 side 0b10 [1] ; bits 15 to 1 jmp y– rbits side 0b11 [1] out pins, 1 side 0b00 [1] ; bit 0 pull noblock side 0b01 [1] ; the next frame, or X: zero .wrap
Start it with OSR and X zero.
pub fn output_program(format: &hal.I2sFormat, slot_bits: u32) -> rp_pio.Program!hal.Error
input_program
Function · Source
The input program for
formatin slots ofslot_bits, 16 or 32; InvalidInput for another width. It makes LRCLK in runs ofslot_bitsbit clocks and shifts in DATA on each rising edge of BCLK; autopush cuts the bits into 32-bit words, which line up with the slots because the program starts at a slot’s first bit. In 32-bit slots, for left-justified framing:.side_set 2 ; LRCLK, BCLK .in 32 left auto 32 .fifo rx .wrap_target set y, 30 side 0b10 [1] ; LRCLK high: the left slot lbits: in pins, 1 side 0b11 [1] ; bits 31 to 1 jmp y– lbits side 0b10 [1] in pins, 1 side 0b11 [1] ; bit 0 set y, 30 side 0b00 [1] ; LRCLK low: the right slot rbits: in pins, 1 side 0b01 [1] jmp y– rbits side 0b00 [1] in pins, 1 side 0b01 [1] .wrap
Philips framing swaps the levels, LRCLK low for the run that starts with the right slot’s last bit, and starts at
lbitswith Y 30, the left slot’s first bit; 16-bit slots set Y to 14. A full RX FIFO stalls the autopush, and with it the clocks.
pub fn input_program(format: &hal.I2sFormat, slot_bits: u32) -> rp_pio.Program!hal.Error
Output
Struct · Source
An I2S output on one PIO state machine; see the package comment. It implements hal.I2sOutput.
pub struct Output: hal.I2sOutput {
// Private implementation fields omitted.
}
Output.new
Function · Source
Load the output program into
pio, claim its lowest free state machine, and start sendingconfig’s stream on GPIOdata, with BCLK on GPIOclockand LRCLK onclock + 1; the three pins must be given to the block (Pins.pio_pins). It sends zeros until samples are queued. InvalidInput for settings out of range (see Config) or a rate the divider cannot reach; Busy if the program does not fit the block’s free instruction slots or every state machine is claimed.
pub fn new(pio: &mut rp_pio.Pio, data: u32, clock: u32, config: &Config) -> Output!hal.Error
Output.sample_rate
Function · Source
Frames per second, as asked for;
timingtells the rate the divider gives.
pub fn sample_rate(&self) -> u32
Output.channels
Function · Source
Samples per frame: 1 or 2.
pub fn channels(&self) -> u32
Output.bits
Function · Source
Bits per sample: 16, 24, or 32.
pub fn bits(&self) -> u32
Output.slot_bits
Function · Source
Bit clocks per slot: 16 or 32.
pub fn slot_bits(&self) -> u32
Output.timing
Function · Source
The clock divider and the sample rate it gives.
pub fn timing(&self) -> Timing
Output.machine_index
Function · Source
The state machine’s number in its block, for Pio.listen with rp_pio.tx_not_full.
pub fn machine_index(&self) -> u32
Output.poll_write
Function · Source
Queue
sampleswithout waiting: as many whole frames as the FIFO has room for, in the wire’s format. Returns how many samples, 0 when the FIFO is full. InvalidInput for a slice that is not whole frames.
pub fn poll_write(&mut self, samples: &[i32]) -> usize!hal.Error
Output.queued
Function · Source
The frames queued and not yet started.
pub fn queued(&mut self) -> u32
Output.pack
Function · Source
Write
samplesintobufferin the wire’s format, as poll_write queues them: little-endian words for the TX FIFO, for Output.dma. Returns the bytes written, 4 or 8 per frame. InvalidInput for a slice that is not whole frames, or a buffer too small for them.
pub fn pack(&self, samples: &[i32], buffer: &mut[u8]) -> usize!hal.Error
Output.dma
Function · Source
A DMA session that plays buffers from
bufferthroughchannel, paced by the state machine’s TX FIFO, while the processor does other work: fill the buffer withpack, thenstartit with the bytes packed. Transfers of whole frames keep left and right in place; the output sends zeros after the last one. The output stays borrowed until the session is dropped. Errors as for hal.DmaStream.transmit: InvalidInput for an empty buffer or one not aligned to 4 bytes, Busy if the channel is running.
pub fn dma(&mut self, channel: &mut dyn hal.DmaChannel, buffer: &mut[u8]) -> hal.DmaStream!hal.Error from(self, channel, buffer)
Output.tx_fifo_address
Function · Source
The address of the state machine’s TX FIFO, for DMA transfers of one’s own.
pub fn tx_fifo_address(&self) -> usize
Output.release
Function · Source
Stop the clocks, make the three pins inputs, give the state machine back to
pio, and unload the program.piomust be the block the output was created in.
pub fn release(self, pio: &mut rp_pio.Pio)
Input
Struct · Source
An I2S input on one PIO state machine; see the package comment. It implements hal.I2sInput.
pub struct Input: hal.I2sInput {
// Private implementation fields omitted.
}
Input.new
Function · Source
Load the input program into
pio, claim its lowest free state machine, and start receivingconfig’s stream on GPIOdata, with BCLK on GPIOclockand LRCLK onclock + 1, all three given to the block (Pins.pio_pins). Errors as for Output.new.
pub fn new(pio: &mut rp_pio.Pio, data: u32, clock: u32, config: &Config) -> Input!hal.Error
Input.sample_rate
Function · Source
Frames per second, as asked for.
pub fn sample_rate(&self) -> u32
Input.channels
Function · Source
pub fn channels(&self) -> u32
Input.bits
Function · Source
pub fn bits(&self) -> u32
Input.slot_bits
Function · Source
pub fn slot_bits(&self) -> u32
Input.timing
Function · Source
pub fn timing(&self) -> Timing
Input.machine_index
Function · Source
The state machine’s number in its block, for Pio.listen with rp_pio.rx_not_empty.
pub fn machine_index(&self) -> u32
Input.poll_read
Function · Source
The samples received since the last call, as many whole frames as fit
samples, without waiting; returns how many samples. A 24-bit sample comes in the top 24 bits, the bits below zero. Overrun once after the FIFO filled up and stalled the clocks: the frames queued then are dropped, and the next call returns the samples that follow.
pub fn poll_read(&mut self, samples: &mut[i32]) -> usize!hal.Error
Input.release
Function · Source
Stop the clocks, make the pins inputs, give the state machine back to
pio, and unload the program, as Output.release does.
pub fn release(self, pio: &mut rp_pio.Pio)