gossamer 0.0.1
a very lightweight app framework for SAMD and SAML chips
Loading...
Searching...
No Matches
Inter-IC Sound interface

Functions for configuring and using the I2S peripheral. More...

Enumerations

enum  i2s_slot_size_t { I2S_SLOT_SIZE_8 = 0 , I2S_SLOT_SIZE_16 = 1 , I2S_SLOT_SIZE_24 = 2 , I2S_SLOT_SIZE_32 = 3 }
 
enum  i2s_data_size_t {
  I2S_DATA_SIZE_32 = 0 , I2S_DATA_SIZE_24 = 1 , I2S_DATA_SIZE_20 = 2 , I2S_DATA_SIZE_18 = 3 ,
  I2S_DATA_SIZE_16 = 4 , I2S_DATA_SIZE_16C = 5 , I2S_DATA_SIZE_8 = 6 , I2S_DATA_SIZE_8C = 7
}
 
enum  i2s_bit_delay_t { I2S_BIT_DELAY_LJ = 0 , I2S_BIT_DELAY_I2S = 1 }
 
enum  i2s_frame_sync_width_t { I2S_FRAME_SYNC_WIDTH_SLOT = 0 , I2S_FRAME_SYNC_WIDTH_HALF = 1 , I2S_FRAME_SYNC_WIDTH_BIT = 2 , I2S_FRAME_SYNC_WIDTH_BURST = 3 }
 
enum  i2s_rx_mode_t { I2S_RX_MODE_NORMAL = 0 , I2S_RX_MODE_PDM2 = 2 }
 

Functions

void i2s_init (void)
 Initializes the I2S peripheral, but does not enable it.
 
void i2s_disable (void)
 Disables the I2S peripheral and turns off its bus clock.
 
void i2s_set_rx_serializer (uint8_t serializer)
 Sets which serializer index to use for RX operations.
 
void i2s_set_tx_serializer (uint8_t serializer)
 Sets which serializer index to use for TX operations.
 
void i2s_configure_clock_unit (uint8_t clock_unit, generic_clock_generator_t clocksource, uint8_t mckdiv, i2s_slot_size_t slot_size, uint8_t num_slots)
 Configures a clock unit's clock source and frame format.
 
void i2s_configure_rx (i2s_rx_mode_t mode, uint8_t clock_unit, i2s_data_size_t data_size)
 Configures the RX serializer.
 
void i2s_configure_tx (uint8_t clock_unit, i2s_data_size_t data_size)
 Configures the TX serializer.
 
void i2s_enable_clock_unit (uint8_t clock_unit)
 Enables a clock unit.
 
void i2s_disable_clock_unit (uint8_t clock_unit)
 Disables a clock unit.
 
void i2s_enable_rx (void)
 Enables the RX serializer.
 
void i2s_disable_rx (void)
 Disables the RX serializer.
 
void i2s_enable_tx (void)
 Enables the TX serializer.
 
void i2s_disable_tx (void)
 Disables the TX serializer.
 

Detailed Description

Functions for configuring and using the I2S peripheral.

The I2S peripheral has two clock units and two serializers. Clock units generate clocking signals (serial clock, frame sync, master clock). Serializers handle data transfer and can operate as transmitters or receivers.

On SAM D21, the two serializers are generic: either can be configured as TX, RX, or PDM2 (for PDM microphones). The data pin determines which serializer you use (SD0 for serializer 0, SD1 for serializer 1).

On SAM D51, the serializers are dedicated: one transmitter (on the SDO pin) and one receiver (on the SDI pin). The transmitter is hard-wired to clock unit 0; the receiver can use either clock unit.

This driver uses direction-based naming (TX/RX). On SAM D21, call i2s_set_rx_serializer() or i2s_set_tx_serializer() to specify which serializer index corresponds to each direction. Boards with known I2S wiring can define I2S_RX_SERIALIZER and/or I2S_TX_SERIALIZER in their pins.h, and i2s_init() will apply those defaults automatically. On SAM D51 the TX/RX assignment is fixed in hardware, so these calls are unnecessary (and are no-ops).

Enumeration Type Documentation

◆ i2s_bit_delay_t

Enumerator
I2S_BIT_DELAY_LJ 

Left justified (0-bit delay)

I2S_BIT_DELAY_I2S 

Standard I2S (1-bit delay)

◆ i2s_data_size_t

Enumerator
I2S_DATA_SIZE_16C 

16-bit compact stereo

I2S_DATA_SIZE_8C 

8-bit compact stereo

◆ i2s_frame_sync_width_t

Enumerator
I2S_FRAME_SYNC_WIDTH_SLOT 

Frame sync pulse is 1 slot wide.

I2S_FRAME_SYNC_WIDTH_HALF 

Frame sync pulse is half a frame wide.

I2S_FRAME_SYNC_WIDTH_BIT 

Frame sync pulse is 1 bit wide.

I2S_FRAME_SYNC_WIDTH_BURST 

Burst mode: 1-bit pulse per data sample.

◆ i2s_rx_mode_t

Enumerator
I2S_RX_MODE_NORMAL 

Standard I2S receive.

I2S_RX_MODE_PDM2 

PDM receive: one bit sampled on each clock edge.

Function Documentation

◆ i2s_configure_clock_unit()

void i2s_configure_clock_unit ( uint8_t clock_unit,
generic_clock_generator_t clocksource,
uint8_t mckdiv,
i2s_slot_size_t slot_size,
uint8_t num_slots )

Configures a clock unit's clock source and frame format.

Routes the specified generic clock generator to the clock unit and configures the clock division and frame format in a single register write. The serial clock (SCK) output frequency is: f_SCK = f_GCLK / (mckdiv + 1).

Parameters
clock_unitThe clock unit to configure (0 or 1).
clocksourceThe generic clock generator to use (e.g. GENERIC_CLOCK_0 for 8 MHz).
mckdivThe master clock division factor. SCK = GCLK / (mckdiv + 1). Valid range is 0-31 on SAM D21, 0-63 on SAM D51.
slot_sizeThe slot size: I2S_SLOT_SIZE_8, _16, _24, or _32.
num_slotsThe number of slots per frame, minus 1. Range: 0-7 (1-8 slots).

◆ i2s_configure_rx()

void i2s_configure_rx ( i2s_rx_mode_t mode,
uint8_t clock_unit,
i2s_data_size_t data_size )

Configures the RX serializer.

Parameters
modeThe receive mode (I2S_RX_MODE_NORMAL or I2S_RX_MODE_PDM2).
clock_unitThe clock unit to use (0 or 1).
data_sizeThe data word size (e.g. I2S_DATA_SIZE_32 for PDM, I2S_DATA_SIZE_16 for audio).

◆ i2s_configure_tx()

void i2s_configure_tx ( uint8_t clock_unit,
i2s_data_size_t data_size )

Configures the TX serializer.

Parameters
clock_unitThe clock unit to use (0 or 1). Ignored on SAM D51, where the TX serializer is hard-wired to clock unit 0.
data_sizeThe data word size (e.g. I2S_DATA_SIZE_16 for audio).

◆ i2s_disable_clock_unit()

void i2s_disable_clock_unit ( uint8_t clock_unit)

Disables a clock unit.

Parameters
clock_unitThe clock unit to disable (0 or 1).

◆ i2s_enable_clock_unit()

void i2s_enable_clock_unit ( uint8_t clock_unit)

Enables a clock unit.

Parameters
clock_unitThe clock unit to enable (0 or 1).

◆ i2s_enable_rx()

void i2s_enable_rx ( void )

Enables the RX serializer.

Note
On SAM D21, you must call i2s_set_rx_serializer() first (or define I2S_RX_SERIALIZER in pins.h) so the driver knows which serializer to enable.

◆ i2s_enable_tx()

void i2s_enable_tx ( void )

Enables the TX serializer.

Note
On SAM D21, you must call i2s_set_tx_serializer() first (or define I2S_TX_SERIALIZER in pins.h) so the driver knows which serializer to enable.

◆ i2s_init()

void i2s_init ( void )

Initializes the I2S peripheral, but does not enable it.

Enables the bus clock for the I2S peripheral and issues a software reset. On SAM D21, if the board defines I2S_RX_SERIALIZER or I2S_TX_SERIALIZER in its pins.h, those serializer assignments are applied automatically.

Note
You must configure pins yourself before enabling the I2S. The clock and data pins need to be muxed to the I2S peripheral.

◆ i2s_set_rx_serializer()

void i2s_set_rx_serializer ( uint8_t serializer)

Sets which serializer index to use for RX operations.

On SAM D21, the I2S has two generic serializers (0 and 1). Which one you use for receiving depends on your data pin: SD0 corresponds to serializer 0, SD1 to serializer 1. Call this before any i2s_set_rx_* or i2s_enable_rx() functions.

Parameters
serializerThe serializer index (0 or 1).
Note
Not needed if the board defines I2S_RX_SERIALIZER in pins.h. On SAM D51, which has a dedicated RX serializer, this is a no-op.

◆ i2s_set_tx_serializer()

void i2s_set_tx_serializer ( uint8_t serializer)

Sets which serializer index to use for TX operations.

On SAM D21, the I2S has two generic serializers (0 and 1). Which one you use for transmitting depends on your data pin: SD0 corresponds to serializer 0, SD1 to serializer 1. Call this before any i2s_set_tx_* or i2s_enable_tx() functions.

Parameters
serializerThe serializer index (0 or 1).
Note
Not needed if the board defines I2S_TX_SERIALIZER in pins.h. On SAM D51, which has a dedicated TX serializer, this is a no-op.