#![cfg_attr(docsrs, procmacros::doc_replace(

    "dma_channel" => {

        cfg(i2s_dma_engine = "I2S_DMA")  => "DMA_I2S0",

        _ => "DMA_CH0",

    },

    "mclk" => {

        cfg(not(esp32)) => "let i2s = i2s.with_mclk(peripherals.GPIO0);",

        _ => ""

    },

    "tdm_slot_philips" => include_str!("../tdm_slot_philips.svg"),

    "tdm_slot_msb" => include_str!("../tdm_slot_msb.svg"),

    "tdm_slot_pcm_short" => include_str!("../tdm_slot_pcm_short.svg"),

    "tdm_slot_pcm_long" => include_str!("../tdm_slot_pcm_long.svg"),

))]

//! # Inter-IC Sound (I2S)

//!

//! ## Overview

//!

//! I2S (Inter-IC Sound) is a synchronous serial communication protocol usually

//! used for transmitting audio data between two digital audio devices.

//! Espressif devices may contain more than one I2S peripheral(s). These

//! peripherals can be configured to input and output sample data via the I2S

//! driver.

//!

//! ## Configuration

//!

//! I2S supports different data formats, including varying data and channel

//! widths, different standards, such as the Philips standard and configurable

//! pin mappings for I2S clock (BCLK), word select (WS), and data input/output

//! (DOUT/DIN).

//!

//! The driver uses DMA (Direct Memory Access) for efficient data transfer and

//! supports various configurations, such as different data formats, standards

//! (e.g., Philips) and pin configurations. It relies on other peripheral

//! modules, such as

//!   - `GPIO`

//!   - `DMA`

//!   - `system` (to configure and enable the I2S peripheral)

//!

//! ### Standards

//!

//! I2S supports different standards, which you can access using [`TdmConfig::new_tdm_philips`]

//! and related helpers. You can also configure custom data formats using methods such as

//! [`TdmConfig::with_msb_shift`], [`TdmConfig::with_ws_width`], [`TdmConfig::with_ws_polarity`],

//! etc.

//!

//! In TDM mode, WS (word select, sometimes called LRCLK or left/right clock) becomes a frame

//! synchronization signal that signals the first slot of a frame. The two sides of the TDM link

//! must agree on the number of channels, data bit width, and frame synchronization pattern; this

//! cannot be determined by examining the signal itself.

//!

//! #### TDM Philips Standard

//!

//! TDM Philips mode pulls the WS line low one BCK period before the first data bit of the first

//! slot is sent and holds it low for 50% of the frame.

//!

//! # {tdm_slot_philips}

//!

//! #### TDM MSB Standard

//!

//! MSB (most-significant bit) mode is similar to Philips mode, except the WS line is pulled low at

//! the same time the first data bit of the first slot is sent. It is held low for 50% of the frame.

//!

//! # {tdm_slot_msb}

//!

//! #### TDM PCM Short Standard

//!

//! PCM (pulse-code modulation) short mode pulls the WS line *high* one BCK period before the first

//! data bit of the first slot is sent, keeps it high for one BCK, then pulls it low for the

//! remainder of the frame.

//!

//! # {tdm_slot_pcm_short}

//!

//! #### TDM PCM Long Standard

//!

//! PCM long mode pulls the WS line *high* one BCK period before the first data bit of the first

//! slot is sent, keeps it high until just before the last data bit of the first slot is sent, then

//! pulls it low for the remainder of the frame.

//!

//! # {tdm_slot_pcm_long}

//!

//! Diagrams from _ESP-IDF Programming Guide_; rendered by Wavedrom.

//!

//! ## Examples

//!

//! ### I2S Read

//!

//! ```rust, no_run

//! # {before_snippet}

//! # use esp_hal::i2s::master::{I2s, Channels, DataFormat, TdmConfig};

//! # use esp_hal::dma_rx_stream_buffer;

//! let rx_buffer = dma_rx_stream_buffer!(4 * 4092, 1024);

//!

//! let i2s = I2s::new(

//!     peripherals.I2S0,

//!     peripherals.__dma_channel__,

//!     TdmConfig::new_tdm_philips()

//!         .with_sample_rate(Rate::from_hz(44100))

//!         .with_data_format(DataFormat::Data16Channel16)

//!         .with_channels(Channels::STEREO),

//! )?;

//! # {mclk}

//! let mut i2s_rx = i2s

//!     .i2s_rx

//!     .with_bclk(peripherals.GPIO1)

//!     .with_ws(peripherals.GPIO2)

//!     .with_din(peripherals.GPIO5)

//!     .build();

//!

//! let mut transfer = i2s_rx.read(rx_buffer)?;

//!

//! loop {

//!     let avail = transfer.available_bytes();

//!

//!     if avail > 0 {

//!         let mut rcv = [0u8; 5000];

//!         transfer.pop(&mut rcv[..avail]);

//!     }

//! }

//! # }

//! ```

#![cfg_attr(

    any(i2s_supports_pdm_tx, i2s_supports_pdm_rx),

    doc = r"## PDM mode

PDM (pulse-density modulation) is supported on I2S instances where the hardware

provides PDM (see per-instance metadata). Use [`I2s::new_pdm`] with [`PdmConfig`].

Hardware PCM-to-PDM / PDM-to-PCM conversion is only available on instances that

support it (typically I2S0); other instances require [`PdmDataFormat::Raw`].

PDM uses a single clock pin (`with_clk` on [`I2s::i2s_tx`] / [`I2s::i2s_rx`])

instead of separate BCLK and WS lines. Only simplex operation (TX *or* RX) is

supported.

```rust, no_run

# {before_snippet}

use esp_hal::i2s::master::{I2s, PdmSlotMode, PdmTxConfig, PdmConfig};

use esp_hal::time::Rate;

let pdm = PdmConfig::tx_only(PdmTxConfig::new_codec_default(

    Rate::from_hz(16_000),

    PdmSlotMode::Mono,

));

let i2s = I2s::new_pdm(peripherals.I2S0, peripherals.__dma_channel__, pdm)?;

# {after_snippet}

```

"

)]

use core::mem::ManuallyDrop;

use enumset::{EnumSet, EnumSetType, enum_set};

use private::*;

mod low_level;

#[doc(hidden)]

pub use low_level::Info;

#[cfg(any(i2s_supports_pdm_tx, i2s_supports_pdm_rx))]

pub use super::pdm::{

    PdmConfig,

    PdmDataFormat,

    PdmError,

    PdmInstance,

    PdmRxConfig,

    PdmSlotMode,

    PdmTxConfig,

};

/// Clock source for the I2S TX/RX module clocks (after the source mux and MCLK divider).

#[cfg(not(i2s_version = "1"))]

pub use crate::clock::ll::I2sClkSclk as I2sClockSource;

/// Selects whether the MCLK pad outputs the TX or RX module clock.

#[cfg(not(i2s_version = "1"))]

pub use crate::clock::ll::I2sMclkOutConfig as MclkOut;

/// Clock source for the I2S module clock (after the source mux and MCLK divider).

#[cfg(i2s_version = "1")]

pub use crate::clock::ll::I2sMclkSclk as I2sClockSource;

use crate::{

    Async,

    Blocking,

    DriverMode,

    clock::dividers::FractionalDivider,

    dma::{

        Channel,

        ChannelRx,

        ChannelTx,

        DmaChannel,

        DmaEligiblePeripheral,

        DmaError,

        DmaRxBuffer,

        DmaRxInterrupt,

        DmaTxBuffer,

        DmaTxInterrupt,

        asynch::{DmaRxFuture, DmaTxFuture},

    },

    gpio::{

        InputConfig,

        InputSignal,

        OutputConfig,

        OutputSignal,

        interconnect::{PeripheralInput, PeripheralOutput},

    },

    i2s::{AnyI2s, any::Inner as AnyI2sInner},

    interrupt::{InterruptConfigurable, InterruptHandler},

    pac::i2s0::RegisterBlock,

    system::PeripheralGuard,

    time::Rate,

};

/// Returns the frequency of a module clock source, in Hz.

///

/// The transmitter and the receiver select their source from the same set of clocks, so one

/// lookup describes both directions.

pub(crate) fn source_frequency(source: I2sClockSource) -> u32 {

    cfg_select! {

        i2s_version = "1" => crate::clock::ll::I2sInstance::mclk_source_frequency(source),

        _ => crate::clock::ll::I2sInstance::tx_clk_source_frequency(source),

    }

}

/// Returns the largest A coefficient the module-clock divider can hold.

pub(crate) fn mclk_max_denominator() -> u32 {

    cfg_select! {

        i2s_version = "1" => {

            let (_, max) = property!("clock_tree.i2s.mclk.div_a");

            max

        }

        _ => {

            let (_, max) = property!("clock_tree.i2s.tx_clk.div_a");

            max

        }

    }

}

#[derive(Debug, EnumSetType)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

/// Represents the various interrupt types for the I2S peripheral.

pub enum I2sInterrupt {

    /// Receive buffer hung, indicating a stall in data reception.

    RxHung,

    /// Transmit buffer hung, indicating a stall in data transmission.

    TxHung,

    #[cfg(not(i2s_version = "1"))]

    /// Reception of data is complete.

    RxDone,

    #[cfg(not(i2s_version = "1"))]

    /// Transmission of data is complete.

    TxDone,

}

with_i2s_dma_engine! {

    ($engine:tt, $any_channel:ident) => {

        /// DMA channel trait for I2S master peripherals.

        ///

        /// Implemented for each channel type that can serve a particular I2S instance `S`.

        #[instability::unstable]

        #[diagnostic::on_unimplemented(

            message = "The DMA channel cannot be used with this I2S peripheral",

            label = "This DMA channel",

            note = "Use a channel that matches the I2S instance."

        )]

        pub trait I2sMasterDmaChannel<'d, S>: crate::private::Sealed + Into<crate::dma::$any_channel<'d>> {}

        crate::macros::impl_dma_channel_trait! {

            $engine,

            any_peri = AnyI2s<'d>,

            peris = for_each_i2s,

            ($peri:path, $ch:path) => {

                impl<'d> I2sMasterDmaChannel<'d, $peri> for $ch {}

            }

        }

        // Proxy type so that the type-erased DMA channel can be named in the driver, regardless of the DMA engine.

        type I2sMasterErased<'d> = crate::dma::$any_channel<'d>;

    };

}

impl<'d> I2s<'d, crate::Blocking> {

    /// Creates a new I2S instance in TDM mode.

    pub fn new<I: Instance + 'd>(

        i2s: I,

        channel: impl I2sMasterDmaChannel<'d, I>,

        config: TdmConfig,

    ) -> Result<Self, ConfigError> {

    }

    /// Creates a new I2S instance in PDM mode.

    #[cfg(any(i2s_supports_pdm_tx, i2s_supports_pdm_rx))]

    pub fn new_pdm<I: Instance + PdmInstance + 'd>(

        i2s: I,

        channel: impl I2sMasterDmaChannel<'d, I>,

        config: PdmConfig,

    ) -> Result<Self, ConfigError> {

    }

}

/// A structure representing a DMA transfer.

///

/// Holds references to the driver instance, DMA buffers, and transfer status.

#[instability::unstable]

pub struct I2sTxDmaTransfer<'d, Dm, Buf>

where

    Dm: DriverMode,

    Buf: DmaTxBuffer,

{

    i2s_tx: ManuallyDrop<I2sTx<'d, Dm>>,

    buffer_view: ManuallyDrop<Buf::View>,

    completed: bool,

}

impl<'d, Dm, Buf> I2sTxDmaTransfer<'d, Dm, Buf>

where

    Dm: DriverMode,

    Buf: DmaTxBuffer,

{

    /// Returns whether [`Self::wait`] will not block.

    pub fn is_done(&self) -> bool {

    }

    /// Waits for the transfer to finish and returns the peripheral and buffer.

    pub fn wait(self) -> (Result<(), DmaError>, I2sTx<'d, Dm>, Buf::Final) {

            (Err(DmaError::DescriptorError), i2s_tx, buf)

        } else {

            (Ok(()), i2s_tx, buf)

        }

    }

    /// Immediately stops the transfer and returns the peripheral and buffer.

    pub fn stop(mut self) -> (I2sTx<'d, Dm>, Buf::Final) {

        self.i2s_tx.tx_channel.stop_transfer();

    }

    fn release(mut self) -> (I2sTx<'d, Dm>, Buf::View) {

        let (i2s_tx, buffer_view) = unsafe {

            (

                ManuallyDrop::take(&mut self.i2s_tx),

                ManuallyDrop::take(&mut self.buffer_view),

            )

        };

        core::mem::forget(self);

        (i2s_tx, buffer_view)

    }

}

impl<'d, Buf> I2sTxDmaTransfer<'d, Async, Buf>

where

    Buf: DmaTxBuffer,

{

    /// Waits for the transfer to finish and returns the peripheral and buffer.

            }

        }

            (Err(DmaError::DescriptorError), i2s_tx, buf)

        } else {

            (Ok(()), i2s_tx, buf)

        }

    /// Waits for the transfer to finish.

        }

        Ok(())

    }

    /// Waits for a condition that might indicate more data is available.

            enum_set!(DmaTxInterrupt::Eof),

            enum_set!(DmaTxInterrupt::DescriptorError | DmaTxInterrupt::TotalEof),

        )

    }

}

impl<Dm: DriverMode, BUF: DmaTxBuffer> core::ops::Deref for I2sTxDmaTransfer<'_, Dm, BUF> {

    type Target = BUF::View;

    fn deref(&self) -> &Self::Target {

        &self.buffer_view

    }

}

impl<Dm: DriverMode, BUF: DmaTxBuffer> core::ops::DerefMut for I2sTxDmaTransfer<'_, Dm, BUF> {

    fn deref_mut(&mut self) -> &mut Self::Target {

        &mut self.buffer_view

    }

}

impl<Dm: DriverMode, BUF: DmaTxBuffer> Drop for I2sTxDmaTransfer<'_, Dm, BUF> {

    fn drop(&mut self) {

        self.i2s_tx.tx_channel.stop_transfer();

        // SAFETY: This is Drop, we know that the parts are no longer used

        let view = unsafe {

            ManuallyDrop::drop(&mut self.i2s_tx);

            ManuallyDrop::take(&mut self.buffer_view)

        };

        let _ = BUF::from_view(view);

    }

}

/// A structure representing a DMA transfer.

///

/// Holds references to the driver instance, DMA buffers, and transfer status.

#[instability::unstable]

pub struct I2sRxDmaTransfer<'d, Dm, Buf>

where

    Dm: DriverMode,

    Buf: DmaRxBuffer,

{

    i2s_rx: ManuallyDrop<I2sRx<'d, Dm>>,

    buffer_view: ManuallyDrop<Buf::View>,

    completed: bool,

}

impl<'d, Dm, Buf> I2sRxDmaTransfer<'d, Dm, Buf>

where

    Dm: DriverMode,

    Buf: DmaRxBuffer,

{

    /// Returns whether [`Self::wait`] will not block.

    pub fn is_done(&self) -> bool {

    }

    /// Waits for the transfer to finish and returns the peripheral and buffer.

    pub fn wait(self) -> (Result<(), DmaError>, I2sRx<'d, Dm>, Buf::Final) {

        if i2s_rx.rx_channel.has_error() {

            (Err(DmaError::DescriptorError), i2s_rx, buf)

        } else {

            (Ok(()), i2s_rx, buf)

        }

    }

    /// Immediately stops the transfer and returns the peripheral and buffer.

    pub fn stop(mut self) -> (I2sRx<'d, Dm>, Buf::Final) {

        self.i2s_rx.rx_channel.stop_transfer();

        (i2s_rx, Buf::from_view(buf))

    }

    fn release(mut self) -> (I2sRx<'d, Dm>, Buf::View) {

        let (i2s_rx, buffer_view) = unsafe {

            (

                ManuallyDrop::take(&mut self.i2s_rx),

                ManuallyDrop::take(&mut self.buffer_view),

            )

        };

        core::mem::forget(self);

        (i2s_rx, buffer_view)

    }

}

impl<'d, Buf> I2sRxDmaTransfer<'d, Async, Buf>

where

    Buf: DmaRxBuffer,

{

    /// Waits for the transfer to finish and returns the peripheral and buffer.

            // we treat DescriptorEmpty as rx transfer is done

                &mut self.i2s_rx.rx_channel,

                enum_set!(DmaRxInterrupt::DescriptorEmpty),

                enum_set!(DmaRxInterrupt::ErrorEof | DmaRxInterrupt::DescriptorError),

            )

            {

                self.completed = true;

                self.i2s_rx.rx_channel.stop_transfer();

            }

            self.completed = true;

        }

            (Err(DmaError::DescriptorError), i2s_rx, buf)

        } else {

            (Ok(()), i2s_rx, buf)

        }

    /// Waits for the transfer to finish and returns the peripheral and buffer.

            // we treat DescriptorEmpty as rx transfer is done

                enum_set!(DmaRxInterrupt::DescriptorEmpty),

                enum_set!(DmaRxInterrupt::ErrorEof | DmaRxInterrupt::DescriptorError),

            )

        }

        Ok(())

    }

    /// Waits for a condition that might indicate more data is available.

            enum_set!(DmaRxInterrupt::SuccessfulEof | DmaRxInterrupt::Done),

            enum_set!(

                DmaRxInterrupt::ErrorEof

                    | DmaRxInterrupt::DescriptorError

                    | DmaRxInterrupt::DescriptorEmpty

            ),

        )

    }

}

impl<Dm: DriverMode, BUF: DmaRxBuffer> core::ops::Deref for I2sRxDmaTransfer<'_, Dm, BUF> {

    type Target = BUF::View;

    fn deref(&self) -> &Self::Target {

        &self.buffer_view

    }

}

impl<Dm: DriverMode, BUF: DmaRxBuffer> core::ops::DerefMut for I2sRxDmaTransfer<'_, Dm, BUF> {

    fn deref_mut(&mut self) -> &mut Self::Target {

        &mut self.buffer_view

    }

}

impl<Dm: DriverMode, BUF: DmaRxBuffer> Drop for I2sRxDmaTransfer<'_, Dm, BUF> {

    fn drop(&mut self) {

        self.i2s_rx.rx_channel.stop_transfer();

        // SAFETY: This is Drop, we know that the parts are no longer used

        let view = unsafe {

            ManuallyDrop::drop(&mut self.i2s_rx);

            ManuallyDrop::take(&mut self.buffer_view)

        };

        let _ = BUF::from_view(view);

    }

}

/// I2S Error

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[allow(clippy::enum_variant_names, reason = "peripheral is unstable")]

pub enum Error {

    /// An unspecified or unknown error occurred during an I2S operation.

    Unknown,

    /// A DMA-related error occurred during I2S operations.

    /// An illegal or invalid argument was passed to an I2S function or method.

    IllegalArgument,

}

impl From<DmaError> for Error {

    fn from(value: DmaError) -> Self {

        Error::DmaError(value)

    }

}

/// Supported I2S data formats.

///

/// Each format defines two dimensions:

///

/// - **`Data{X}` (on-wire slot width)**: The number of bit-clock (BCLK) cycles allocated to each

///   channel slot on the physical line ([`Self::data_bits`]). This determines the BCLK frequency

///   (`BCLK = sample_rate * channels * data_bits`) and the time duration of each channel slot.

/// - **`Channel{Y}` (in-memory sample width)**: The number of active audio data bits per sample

///   transferred to or from memory via DMA ([`Self::channel_bits`]).

///

/// ### In-Memory Representation

///

/// In the DMA memory buffer, samples are stored with a size corresponding to `Channel{Y}`:

/// - 32-bit (`Channel32`): 4 bytes per sample (e.g. `i32` / `u32`).

/// - 24-bit (`Channel24`): 3 bytes per sample (packed 24-bit PCM).

/// - 16-bit (`Channel16`): 2 bytes per sample (e.g. `i16` / `u16`).

/// - 8-bit (`Channel8`): 1 byte per sample (e.g. `i8` / `u8`).

///

/// ### On-Wire Representation and Padding

///

/// On the physical I2S lines, each channel occupies `Data{X}` clock cycles:

/// - When `X == Y` (e.g. [`Data16Channel16`], [`Data32Channel32`]), the entire slot carries sample

///   data with no padding.

/// - When `X > Y` (e.g. [`Data32Channel16`]), the `Y`-bit sample occupies `Y` bits of the `X`-bit

///   slot on the wire, and the remaining `X - Y` bits are padded or discarded according to

///   [`Alignment`]:

///   - [`Alignment::Left`] (default):

///     - **TX**: The `Y` sample bits are transmitted first (MSB-aligned within the slot), followed

///       by `X - Y` zero bits.

///     - **RX**: The first `Y` bits from the wire are captured into memory; trailing bits in the

///       slot are discarded.

///   - [`Alignment::Right`]:

///     - **TX**: `X - Y` zero bits are transmitted first, followed by the `Y` sample bits

///       (LSB-aligned within the slot).

///     - **RX**: The leading `X - Y` bits are discarded; the last `Y` bits of the slot are captured

///       into memory.

///

/// Note: In this driver's naming scheme, `Data{X}` refers to the on-wire slot width, and

/// `Channel{Y}` refers to the in-memory sample data width. (This differs from some datasheets where

/// the on-wire slot is called "slot width" or "channel width", and the sample size is called "data

/// width".)

///

/// [`Data16Channel16`]: DataFormat::Data16Channel16

/// [`Data32Channel16`]: DataFormat::Data32Channel16

/// [`Data32Channel32`]: DataFormat::Data32Channel32

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[cfg(not(i2s_version = "1"))]

pub enum DataFormat {

    /// 32-bit on-wire slot width (32 BCLK cycles) and 32-bit in-memory sample width (4 bytes per

    /// sample).

    Data32Channel32,

    /// 32-bit on-wire slot width (32 BCLK cycles) and 24-bit in-memory sample width (3 bytes packed

    /// per sample).

    ///

    /// In TX, 24-bit samples from memory are padded to 32 bits on the wire according to

    /// [`Alignment`]. In RX, 24 bits are extracted from each 32-bit slot on the wire into

    /// memory.

    Data32Channel24,

    /// 32-bit on-wire slot width (32 BCLK cycles) and 16-bit in-memory sample width (2 bytes per

    /// sample).

    ///

    /// In TX, 16-bit samples from memory are padded to 32 bits on the wire according to

    /// [`Alignment`]. In RX, 16 bits are extracted from each 32-bit slot on the wire into

    /// memory.

    Data32Channel16,

    /// 32-bit on-wire slot width (32 BCLK cycles) and 8-bit in-memory sample width (1 byte per

    /// sample).

    ///

    /// In TX, 8-bit samples from memory are padded to 32 bits on the wire according to

    /// [`Alignment`]. In RX, 8 bits are extracted from each 32-bit slot on the wire into

    /// memory.

    Data32Channel8,

    /// 16-bit on-wire slot width (16 BCLK cycles) and 16-bit in-memory sample width (2 bytes per

    /// sample).

    Data16Channel16,

    /// 16-bit on-wire slot width (16 BCLK cycles) and 8-bit in-memory sample width (1 byte per

    /// sample).

    ///

    /// In TX, 8-bit samples from memory are padded to 16 bits on the wire according to

    /// [`Alignment`]. In RX, 8 bits are extracted from each 16-bit slot on the wire into

    /// memory.

    Data16Channel8,

    /// 8-bit on-wire slot width (8 BCLK cycles) and 8-bit in-memory sample width (1 byte per

    /// sample).

    Data8Channel8,

}

/// Supported I2S data formats.

///

/// Each format defines the on-wire slot width (`Data{X}`) and the in-memory sample width

/// (`Channel{Y}`). On the ESP32-S2, each slot on the wire matches the sample data width in memory

/// (`X == Y`).

///

/// - **`Data{X}` (on-wire slot width)**: The number of bit-clock (BCLK) cycles allocated to each

///   channel slot on the physical line ([`Self::data_bits`]).

/// - **`Channel{Y}` (in-memory sample width)**: The number of audio data bits per sample

///   transferred to or from memory via DMA ([`Self::channel_bits`]).

///

/// In the DMA memory buffer, samples occupy:

/// - 32-bit ([`Data32Channel32`]): 4 bytes per sample.

/// - 24-bit ([`Data24Channel24`]): 3 bytes per sample.

/// - 16-bit ([`Data16Channel16`]): 2 bytes per sample.

/// - 8-bit ([`Data8Channel8`]): 1 byte per sample.

///

/// [`Data32Channel32`]: DataFormat::Data32Channel32

/// [`Data24Channel24`]: DataFormat::Data24Channel24

/// [`Data16Channel16`]: DataFormat::Data16Channel16

/// [`Data8Channel8`]: DataFormat::Data8Channel8

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[cfg(esp32s2)]

pub enum DataFormat {

    /// 32-bit on-wire slot width (32 BCLK cycles) and 32-bit in-memory sample width (4 bytes per

    /// sample).

    Data32Channel32,

    /// 24-bit on-wire slot width (24 BCLK cycles) and 24-bit in-memory sample width (3 bytes packed

    /// per sample).

    Data24Channel24,

    /// 16-bit on-wire slot width (16 BCLK cycles) and 16-bit in-memory sample width (2 bytes per

    /// sample).

    Data16Channel16,

    /// 8-bit on-wire slot width (8 BCLK cycles) and 8-bit in-memory sample width (1 byte per

    /// sample).

    Data8Channel8,

}

/// Supported I2S data formats.

///

/// Each format defines the on-wire slot width (`Data{X}`) and the in-memory sample width

/// (`Channel{Y}`). On the ESP32, each slot on the wire matches the sample data width in memory (`X

/// == Y`).

///

/// - **`Data{X}` (on-wire slot width)**: The number of bit-clock (BCLK) cycles allocated to each

///   channel slot on the physical line ([`Self::data_bits`]).

/// - **`Channel{Y}` (in-memory sample width)**: The number of audio data bits per sample

///   transferred to or from memory via DMA ([`Self::channel_bits`]).

///

/// In the DMA memory buffer, samples occupy:

/// - 32-bit ([`Data32Channel32`]): 4 bytes per sample.

/// - 16-bit ([`Data16Channel16`]): 2 bytes per sample.

///

/// [`Data32Channel32`]: DataFormat::Data32Channel32

/// [`Data16Channel16`]: DataFormat::Data16Channel16

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[cfg(esp32)]

pub enum DataFormat {

    /// 32-bit on-wire slot width (32 BCLK cycles) and 32-bit in-memory sample width (4 bytes per

    /// sample).

    Data32Channel32,

    /// 16-bit on-wire slot width (16 BCLK cycles) and 16-bit in-memory sample width (2 bytes per

    /// sample).

    Data16Channel16,

}

#[cfg(not(i2s_version = "1"))]

impl DataFormat {

    /// Returns the on-wire slot width in bits (number of BCLK cycles per channel slot).

    pub fn data_bits(&self) -> u8 {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data32Channel24 => 32,

            DataFormat::Data32Channel16 => 32,

            DataFormat::Data32Channel8 => 32,

            DataFormat::Data16Channel16 => 16,

            DataFormat::Data16Channel8 => 16,

        }

    }

    /// Returns the in-memory sample width in bits (active audio data bits per sample transferred

    /// via DMA).

    pub fn channel_bits(&self) -> u8 {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data32Channel24 => 24,

            DataFormat::Data32Channel16 => 16,

            DataFormat::Data32Channel8 => 8,

            DataFormat::Data16Channel16 => 16,

            DataFormat::Data16Channel8 => 8,

            DataFormat::Data8Channel8 => 8,

        }

    }

}

#[cfg(esp32s2)]

impl DataFormat {

    /// Returns the on-wire slot width in bits (number of BCLK cycles per channel slot).

    pub fn data_bits(&self) -> u8 {

        match self {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data24Channel24 => 24,

            DataFormat::Data16Channel16 => 16,

            DataFormat::Data8Channel8 => 8,

        }

    }

    /// Returns the in-memory sample width in bits (active audio data bits per sample transferred

    /// via DMA).

    pub fn channel_bits(&self) -> u8 {

        match self {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data24Channel24 => 24,

            DataFormat::Data16Channel16 => 16,

            DataFormat::Data8Channel8 => 8,

        }

    }

}

#[cfg(esp32)]

impl DataFormat {

    /// Returns the on-wire slot width in bits (number of BCLK cycles per channel slot).

    pub fn data_bits(&self) -> u8 {

        match self {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data16Channel16 => 16,

        }

    }

    /// Returns the in-memory sample width in bits (active audio data bits per sample transferred

    /// via DMA).

    pub fn channel_bits(&self) -> u8 {

        match self {

            DataFormat::Data32Channel32 => 32,

            DataFormat::Data16Channel16 => 16,

        }

    }

}

/// I2S bit order

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum BitOrder {

    /// Most Significant Bit (MSB) is transmitted first.

    #[default]

    MsbFirst,

    /// Least Significant Bit (LSB) is transmitted first.

    LsbFirst,

}

/// I2S endianness

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum Endianness {

    /// Most Significant Byte (MSB) is transmitted first.

    #[default]

    LittleEndian,

    /// Least Significant Byte (LSB) is transmitted first.

    BigEndian,

}

/// I2S word select signal width

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum WsWidth {

    /// Word select signal will be kept active for half of the frame.

    #[default]

    HalfFrame,

    /// Word select signal will be kept active for the length of the first channel (PCM long frame

    /// standard)

    #[cfg(not(i2s_version = "1"))]

    OneChannel,

    /// Word select signal will be kept active for a single BCLK cycle (PCM short frame standard)

    Bit,

    /// Word select signal will be kept active for the specified amount of bits(BCLK cycles)

    #[cfg(not(i2s_version = "1"))]

    Bits(u16),

}

/// Represents the polarity of a signal.

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum Polarity {

    /// The signal is high when active.

    #[default]

    ActiveHigh,

    /// The signal is low when active.

    ActiveLow,

}

/// Alignment of sample data within the on-wire slot when the in-memory sample width is less than

/// the on-wire slot width.

///

/// See [`DataFormat`] for more details on padding and on-wire slot alignment.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum Alignment {

    #[default]

    /// Left aligned (MSB-aligned within the on-wire slot).

    Left,

    /// Right aligned (LSB-aligned within the on-wire slot).

    Right,

}

/// I2S channels configuration

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub struct Channels {

    count: u8,

    mask: u16,

    fill: Option<u32>,

}

impl Channels {

    /// Two channels will use different data.

    pub const STEREO: Channels = Channels::new_impl(2, 0b11, None);

    /// Two channels will use the same data.

    pub const MONO: Channels = Channels::new_impl(2, 0b01, None);

    /// Two channels. Left(first) channel will contain data. Right(second) channel will contain

    /// zeros.

    pub const LEFT: Channels = Channels::new_impl(2, 0b01, Some(0));

    /// Two channels. Right(second) channel will contain data. Left(first) channel will contain

    /// zeros.

    pub const RIGHT: Channels = Channels::new_impl(2, 0b10, Some(0));

    #[procmacros::doc_replace]

    /// Creates arbitrary configuration for I2S channels.

    ///

    /// - `count` the total number of channels. Must be at least 1 and no more than 16.

    /// - `mask` determines which channels will be active, with the least significant bit

    ///   representing first channel. Setting the bit at the nth position means nth channel is

    ///   active. Inactive channels do not consume or write data in the DMA buffer.

    /// - `fill` determines the behavior of inactive channels. `Some(n)` will make all inactive

    ///   channel send out specified value, truncated to the channel width. `None` will make

    ///   disabled channels repeat the data from the last active channel. This field is ignored in

    ///   the receiver unit.

    ///

    /// # Examples

    ///

    /// The following example prepares configuration for 6 channels. Only 1st and 4th channels

    /// are active. Channels 2-3 will use the same data as the 1st, and channels 5-6 will use the

    /// data from the 4th.

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::i2s::master::Channels;

    ///

    /// let channels = Channels::new(6, 0b_001_001, None);

    /// # {after_snippet}

    /// ```

    #[cfg(not(i2s_version = "1"))]

    pub const fn new(count: u8, mask: u16, fill: Option<u32>) -> Self {

        Self::new_impl(count, mask, fill)

    }

    const fn new_impl(count: u8, mut mask: u16, fill: Option<u32>) -> Self {

        mask &= (1 << count) - 1;

        Self { count, mask, fill }

    }

    #[cfg(not(i2s_version = "1"))]

    fn active_count(&self) -> u8 {

    }

}

/// Internal I2S peripheral configuration (TDM or PDM mode).

#[derive(Clone, Copy, Debug, PartialEq)]

#[cfg_attr(not(any(i2s_supports_pdm_tx, i2s_supports_pdm_rx)), derive(Eq, Hash))]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[non_exhaustive]

pub(crate) enum Config {

    /// Time-division multiplexed (TDM) configuration.

    Tdm(TdmConfig),

    /// Pulse-density modulation (PDM) configuration.

    #[cfg(any(i2s_supports_pdm_tx, i2s_supports_pdm_rx))]

    Pdm(PdmConfig),

}

/// TDM mode peripheral configuration.

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[non_exhaustive]

pub struct TdmConfig {

    /// Receiver unit config.

    rx_config: TdmUnitConfig,

    /// Transmitter unit config.

    tx_config: TdmUnitConfig,

    /// Sets `I2S_SIG_LOOPBACK`: TX and RX share the same WS and BCK.

    signal_loopback: bool,

    /// The target sample rate.

    #[cfg(i2s_version = "1")]

    sample_rate: Rate,

    /// Source clock for the shared module clock.

    #[cfg(i2s_version = "1")]

    clock_source: I2sClockSource,

    /// Selects which module clock is routed to the MCLK pad.

    #[cfg(not(i2s_version = "1"))]

    mclk_out: MclkOut,

    /// Data format configuring on-wire slot width and in-memory sample width.

    #[cfg(i2s_version = "1")]

    data_format: DataFormat,

}

impl Config {

    fn validate(&self, _info: &Info) -> Result<(), ConfigError> {

            Self::Tdm(c) => c.validate(),

            #[cfg(any(i2s_supports_pdm_tx, i2s_supports_pdm_rx))]

            Self::Pdm(c) => c.validate(_info).map_err(ConfigError::Pdm),

        }

    }

}

impl TdmConfig {

    /// TDM Philips standard configuration with two 16-bit active channels.

            rx_config: TdmUnitConfig::new_tdm_philips(),

            tx_config: TdmUnitConfig::new_tdm_philips(),

            ..Default::default()

        }

    /// TDM MSB standard configuration with two 16-bit active channels.

    pub fn new_tdm_msb() -> Self {

        Self {

            rx_config: TdmUnitConfig::new_tdm_msb(),

            tx_config: TdmUnitConfig::new_tdm_msb(),

            ..Default::default()

        }

    }

    /// TDM PCM short frame standard configuration with two 16-bit active channels.

    pub fn new_tdm_pcm_short() -> Self {

        Self {

            rx_config: TdmUnitConfig::new_tdm_pcm_short(),

            tx_config: TdmUnitConfig::new_tdm_pcm_short(),

            ..Default::default()

        }

    }

    /// TDM PCM long frame standard configuration with two 16-bit active channels.

    #[cfg(not(i2s_version = "1"))]

    pub fn new_tdm_pcm_long() -> Self {

        Self {

            rx_config: TdmUnitConfig::new_tdm_pcm_long(),

            tx_config: TdmUnitConfig::new_tdm_pcm_long(),

            ..Default::default()

        }

    }

        self.rx_config.validate()?;

        self.tx_config.validate()?;

        Ok(())

    }

    #[cfg(i2s_version = "1")]

    fn calculate_clock(&self) -> I2sClockDividers {

        I2sClockDividers::new(

            self.sample_rate,

            2,

            self.data_format.data_bits(),

            self.clock_source,

        )

    }

    /// Assigns the given value to the `sample_rate` field in both units.

    #[must_use]

    #[cfg(not(i2s_version = "1"))]

    pub fn with_sample_rate(self, sample_rate: Rate) -> Self {

            ..self

        }

    }

    /// Assigns the given value to the `channels` field in both units.

    #[must_use]

    pub fn with_channels(self, channels: Channels) -> Self {

            rx_config: self.rx_config.with_channels(channels),

            tx_config: self.tx_config.with_channels(channels),

            ..self

        }

    }

    /// Assigns the given data format to both units.

    ///

    /// See [`DataFormat`] for details on on-wire slot width and in-memory sample width.

    #[must_use]

    #[cfg(not(i2s_version = "1"))]

    pub fn with_data_format(self, data_format: DataFormat) -> Self {

        Self {

            ..self

        }

    }

    /// Assigns the given value to the `ws_width` field in both units.

    #[must_use]

    pub fn with_ws_width(self, ws_width: WsWidth) -> Self {

        Self {

            rx_config: self.rx_config.with_ws_width(ws_width),

            tx_config: self.tx_config.with_ws_width(ws_width),

            ..self

        }

    }

    /// Assigns the given value to the `ws_polarity` field in both units.

    #[must_use]

    pub fn with_ws_polarity(self, ws_polarity: Polarity) -> Self {

        Self {

            rx_config: self.rx_config.with_ws_polarity(ws_polarity),

            tx_config: self.tx_config.with_ws_polarity(ws_polarity),

            ..self

        }

    }

    /// Assigns the given value to the `msb_shift` field in both units.

    #[must_use]

    pub fn with_msb_shift(self, msb_shift: bool) -> Self {

        Self {

            rx_config: self.rx_config.with_msb_shift(msb_shift),

            tx_config: self.tx_config.with_msb_shift(msb_shift),

            ..self

        }

    }

    /// Assigns the given value to the `endianness` field in both units.

    #[cfg(not(esp32))]

    #[must_use]

    pub fn with_endianness(self, endianness: Endianness) -> Self {

        Self {

            rx_config: self.rx_config.with_endianness(endianness),

            tx_config: self.tx_config.with_endianness(endianness),

            ..self

        }

    }

    /// Assigns the given value to the `bit_order` field in both units.

    #[cfg(not(i2s_version = "1"))]

    #[must_use]

    pub fn with_bit_order(self, bit_order: BitOrder) -> Self {

        Self {

            rx_config: self.rx_config.with_bit_order(bit_order),

            tx_config: self.tx_config.with_bit_order(bit_order),

            ..self

        }

    }

    /// Assigns the given value to the `alignment` field in both units.

    #[cfg(not(i2s_version = "1"))]

    #[must_use]

    pub fn with_alignment(self, alignment: Alignment) -> Self {

        Self {

            rx_config: self.rx_config.with_alignment(alignment),

            tx_config: self.tx_config.with_alignment(alignment),

            ..self

        }

    }

}

#[allow(clippy::derivable_impls)]

impl Default for TdmConfig {

    fn default() -> Self {

        Self {

            rx_config: TdmUnitConfig::new_tdm_philips(),

            tx_config: TdmUnitConfig::new_tdm_philips(),

            signal_loopback: false,

            #[cfg(i2s_version = "1")]

            sample_rate: Rate::from_hz(44100),

            #[cfg(i2s_version = "1")]

            clock_source: I2sClockSource::default(),

            #[cfg(not(i2s_version = "1"))]

            mclk_out: MclkOut::default(),

            #[cfg(i2s_version = "1")]

            data_format: DataFormat::Data16Channel16,

        }

    }

}

/// I2S receiver/transmitter unit configuration (TDM mode).

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

#[non_exhaustive]

pub struct TdmUnitConfig {

    /// The target sample rate.

    #[cfg(not(i2s_version = "1"))]

    sample_rate: Rate,

    /// Source clock for this unit's module clock.

    #[cfg(not(i2s_version = "1"))]

    clock_source: I2sClockSource,

    /// I2S channels configuration.

    channels: Channels,

    /// Data format configuring on-wire slot width and in-memory sample width.

    #[cfg(not(i2s_version = "1"))]

    data_format: DataFormat,

    /// Duration for which WS signal is kept active.

    ws_width: WsWidth,

    /// Polarity of WS signal.

    ws_polarity: Polarity,

    /// Data signal will lag by one bit relative to the WS signal.

    msb_shift: bool,

    /// Byte order of the data.

    #[cfg(not(esp32))]

    endianness: Endianness,

    /// Bit order of the data.

    #[cfg(not(i2s_version = "1"))]

    bit_order: BitOrder,

    /// Alignment of sample data within the on-wire slot. Only relevant when sample width is less

    /// than slot width.

    #[cfg(not(i2s_version = "1"))]

    alignment: Alignment,

}

/// Alias for [`TdmUnitConfig`] (TDM mode unit configuration).

pub type UnitConfig = TdmUnitConfig;

impl TdmUnitConfig {

    /// TDM Philips standard configuration with two 16-bit active channels.

            #[cfg(not(i2s_version = "1"))]

            sample_rate: Rate::from_hz(44100),

            #[cfg(not(i2s_version = "1"))]

            clock_source: I2sClockSource::default(),

            channels: Channels::STEREO,

            #[cfg(not(i2s_version = "1"))]

            data_format: DataFormat::Data16Channel16,

            ws_width: WsWidth::HalfFrame,

            ws_polarity: Polarity::ActiveLow,

            msb_shift: true,

            #[cfg(not(esp32))]

            endianness: Endianness::LittleEndian,

            #[cfg(not(i2s_version = "1"))]

            bit_order: BitOrder::MsbFirst,

            #[cfg(not(i2s_version = "1"))]

            alignment: Alignment::Left,

        }

    /// TDM MSB standard configuration with two 16-bit active channels.

    pub fn new_tdm_msb() -> Self {

        Self::new_tdm_philips().with_msb_shift(false)

    }

    /// TDM PCM short frame standard configuration with two 16-bit active channels.

    pub fn new_tdm_pcm_short() -> Self {

        Self::new_tdm_philips()

            .with_ws_width(WsWidth::Bit)

            .with_ws_polarity(Polarity::ActiveHigh)

    }

    /// TDM PCM long frame standard configuration with two 16-bit active channels.

    #[cfg(not(i2s_version = "1"))]

    pub fn new_tdm_pcm_long() -> Self {

        Self::new_tdm_philips()

            .with_ws_width(WsWidth::OneChannel)

            .with_ws_polarity(Polarity::ActiveHigh)

    }

    fn validate(&self) -> Result<(), ConfigError> {

        #[cfg(not(i2s_version = "1"))]

            return Err(ConfigError::ChannelsOutOfRange);

        }

        Ok(())

    }

    #[cfg(not(i2s_version = "1"))]

    fn calculate_ws_width(&self) -> Result<u16, ConfigError> {

            WsWidth::HalfFrame => {

            }

            WsWidth::Bit => 1,

            WsWidth::OneChannel => self.data_format.data_bits() as u16,

        };

        const MAX_WS_WIDTH: u16 = property!("i2s.max_ws_width");

        if !(1..=MAX_WS_WIDTH).contains(&ws_width)

        {

            return Err(ConfigError::WsWidthOutOfRange);

        }

        Ok(ws_width)

    }

    #[cfg(not(i2s_version = "1"))]

    fn calculate_clock(&self) -> I2sClockDividers {

        I2sClockDividers::new(

            self.channels.count,

            self.data_format.data_bits(),

            self.clock_source,

        )

    }

}

impl Default for TdmUnitConfig {

    fn default() -> Self {

        Self::new_tdm_philips()

    }

}

/// Configuration errors.

#[non_exhaustive]

#[cfg_attr(feature = "defmt", derive(defmt::Format))]

pub enum ConfigError {

    /// Provided [Channels] configuration has no active channels or has over 16 total channels.

    #[cfg(not(i2s_version = "1"))]

    ChannelsOutOfRange,