API referencestd/embedded

std/embedded/chip/esp_i2s

Public declarations, types, methods, and source contracts for std/embedded/chip/esp_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/esp_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
cpu core/cpu esp_i2s.dodo
hal std/embedded/hal esp_i2s.dodo
mmio core/mmio esp_i2s.dodo
ptr core/ptr esp_i2s.dodo

CLOCK_HZ

Constant · Source

The function clock: the PLL’s 160 MHz output.

pub const CLOCK_HZ: u32 = 160_000_000

RING_DESCRIPTORS

Constant · Source

The ring: descriptors, and bytes in each.

pub const RING_DESCRIPTORS: u32 = 8

DESCRIPTOR_BYTES

Constant · Source

pub const DESCRIPTOR_BYTES: u32 = 512

Channel

Enum · Source

The slot a mono input keeps.

pub enum Channel {
    Left,
    Right
}

Config

Struct · Source

A stream’s settings, for Pins.i2s_output and Pins.i2s_input, as in rp_i2s.

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 ring holds.
    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 fractional divider of the 160 MHz clock to MCLK, integer + numerator / denominator, and MCLK’s divider to the bit clock.

pub struct Timing {
    pub clock_hz: u32
    // The sample rate asked for.
    pub sample_rate: u32
    pub slot_bits: u32
    pub integer: u32
    pub numerator: u32
    pub denominator: u32
    pub bit_divider: u32
}

Timing.actual_millihertz

Function · Source

The sample rate the dividers give, in millihertz, rounded.

pub fn actual_millihertz(&self) -> u64

Timing.actual_rate

Function · Source

The sample rate the dividers give, 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 dividers give, rounded to whole hertz.

pub fn bit_clock_hz(&self) -> u32

Timing.copy

Function · Source

pub fn copy(&self) -> Timing

timing

Function · Source

The dividers closest to sample_rate frames per second in slots of slot_bits (16 or 32) from a clock of clock_hz; see “Clock” above. InvalidInput for a rate the dividers cannot reach or another slot width.

pub fn timing(clock_hz: u32, sample_rate: u32, slot_bits: u32) -> Timing!hal.Error

divider_fields

Function · Source

The divider fraction b / a as PCR’s DIV_CONF fields: for b <= a / 2, Z = b, Y = a % b, X = a / b - 1, YN1 = 0; above, Z = a - b, Y = a % (a - b), X = a / (a - b) - 1, YN1 = 1; all zero without a fraction.

pub fn divider_fields(a: u32, b: u32) -> u32

slot_word

Function · Source

A sample as a 32-bit slot’s word: its top bits bits, or for right justified framing those bits at the bottom with copies of the sign above.

pub fn slot_word(sample: i32, bits: u32, right_justified: bool) -> u32

slot_sample

Function · Source

A 32-bit slot’s word as a sample, keeping bits bits: the top ones, or for right justified framing the bottom ones.

pub fn slot_sample(word: u32, bits: u32, right_justified: bool) -> i32

check

Function · Source

Check config and find its timing. InvalidInput for a rate out of range, bits other than 16, 24, or 32, more bits than the slot holds, or channels other than 1 or 2.

pub fn check(config: &Config) -> Timing!hal.Error

output_clock_pins

Function · Source

The output’s BCLK pin in bits 15-8 and WS pin in bits 7-0 while an output runs, else 0xFF.

pub fn output_clock_pins() -> u32

dma_interrupt

Function · Source

The runtime’s DMA interrupt handlers call this, through the chip package’s dodo_dma_interrupt, before anything else: it zeroes the output descriptors the output channel has read and counts them, acknowledging the interrupt.

pub fn dma_interrupt()

Output

Struct · Source

An I2S output on I2S0’s transmitter and one GDMA channel; see the package comment.

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

Output.start

Function · Source

Start the transmitter as master with config’s stream through GDMA channel channel, sending zeros until samples are queued; BCLK and WS are on pins bclk and ws, which only output_clock_pins reports. InvalidInput as for check. SAFETY: the caller owns I2S0’s transmitter (bus clock on, out of reset), the GDMA channel, and its DMA_OUT interrupt, which must call dma_interrupt once enabled; it routes the pins.

pub unsafe fn start(channel: u32, bclk: u32, ws: u32, config: &Config) -> Output!hal.Error

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

Output.sample_rate

Function · Source

Frames per second, as asked for; timing tells the rate the dividers give.

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

pub fn timing(&self) -> Timing

Output.dma_channel

Function · Source

The GDMA channel the output streams through.

pub fn dma_channel(&self) -> u32

Output.poll_write

Function · Source

Queue samples without waiting: as many whole frames as the ring has room for. Returns how many samples, 0 when the queue 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 playing.

pub fn queued(&self) -> u32

Output.frames_played

Function · Source

The frames the transmitter has taken from the ring since it started, silence included, a descriptor at a time: a count that rises at the sample rate.

pub fn frames_played(&self) -> u64

Output.frames_per_descriptor

Function · Source

Frames per descriptor: 64 in 32-bit slots, 128 in 16-bit ones.

pub fn frames_per_descriptor(&self) -> u32

Output.stop

Function · Source

Stop the transmitter and the channel, and turn the function clock off. Returns the channel’s number.

pub fn stop(self) -> u32

Input

Struct · Source

An I2S input on I2S0’s receiver and one GDMA channel; see the package comment.

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

Input.start

Function · Source

Start the receiver with config’s stream through GDMA channel channel: as master, or with shared as slave to the running output’s BCLK and WS. InvalidInput as for check, and with shared unless an output runs at the same sample rate and slot width. SAFETY: the caller owns I2S0’s receiver (bus clock on, out of reset) and the GDMA channel; it routes the pins.

pub unsafe fn start(channel: u32, shared: bool, config: &Config) -> Input!hal.Error

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

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.is_shared

Function · Source

Whether the input runs on the output’s clocks.

pub fn is_shared(&self) -> bool

Input.dma_channel

Function · Source

The GDMA channel the input streams through.

pub fn dma_channel(&self) -> u32

Input.poll_read

Function · Source

The samples received since the last call, as many whole frames as fit samples, a descriptor at a time, without waiting; returns how many samples. A 24-bit sample comes in the top 24 bits, the bits below zero. Overrun once after the ring filled up and the channel stopped: the frames it held are dropped, the receiver restarts, and the next calls return the samples that follow.

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

Input.available

Function · Source

The frames received and not yet read, in completed descriptors.

pub fn available(&mut self) -> u32

Input.frames_received

Function · Source

The frames received since the input started, a descriptor at a time: a count that rises at the sample rate while the program keeps up.

pub fn frames_received(&mut self) -> u64

Input.frames_per_descriptor

Function · Source

Frames per descriptor: 64 in 32-bit slots, 128 in 16-bit ones.

pub fn frames_per_descriptor(&self) -> u32

Input.stop

Function · Source

Stop the receiver and the channel, end the signal loopback if shared, and turn the function clock off. Returns the channel’s number.

pub fn stop(self) -> u32

Search every guide, reference page, and API declaration.