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_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 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_rateframes per second in slots ofslot_bits(16 or 32) from a clock ofclock_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
bitsbits, 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
bitsbits: 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
configand 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 channelchannel, sending zeros until samples are queued; BCLK and WS are on pinsbclkandws, which only output_clock_pins reports. InvalidInput as forcheck. 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;
timingtells 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
sampleswithout 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 channelchannel: as master, or withsharedas slave to the running output’s BCLK and WS. InvalidInput as forcheck, and withsharedunless 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