API referencestd/embedded

std/embedded/chip/rp_i2s

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

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_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_rate frames per second of channels samples of bits bits, framed as format, 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_rate frames per second in slots of slot_bits (16 or 32) from a clk_sys of clock_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 format in slots of slot_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 format in slots of slot_bits, 16 or 32; InvalidInput for another width. It makes LRCLK in runs of slot_bits bit 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 lbits with 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 sending config’s stream on GPIO data, with BCLK on GPIO clock and LRCLK on clock + 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; timing tells 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 samples without 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 samples into buffer in 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 buffer through channel, paced by the state machine’s TX FIFO, while the processor does other work: fill the buffer with pack, then start it 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. pio must 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 receiving config’s stream on GPIO data, with BCLK on GPIO clock and LRCLK on clock + 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)

Search every guide, reference page, and API declaration.