//! Standard mode driver for the ESP32 I2S peripheral.
//!
//! # Microcontroller support for Standard mode
//!
//! | Microcontroller    | Standard Rx     | Standard Tx     |
//! |--------------------|-----------------|-----------------|
//! | ESP32              | I2S0, I2S1      | I2S0, I2S11     |
//! | ESP32-S2           | I2S0            | I2S0            |
//! | ESP32-S3           | I2S0, I2S1      | I2S0, I2S1      |
//! | ESP32-C2 (ESP8684) | _not supported_ | _not supported_ |
//! | ESP32-C3           | I2S0            | I2S0            |
//! | ESP32-C6           | I2S0            | I2S0            |
//! | ESP32-H2           | I2S0            | I2S0            |

use super::*;
use crate::{gpio::*, peripheral::*};

use esp_idf_sys::*;

pub(super) mod config {
    #[allow(unused)]
    use crate::{gpio::*, i2s::config::*, peripheral::*};
    use esp_idf_sys::*;

    /// Standard mode configuration for the I2S peripheral.
    pub struct StdConfig {
        /// The base channel configuration.
        #[allow(dead_code)]
        pub(super) channel_cfg: Config,

        /// Standard mode channel clock configuration.
        #[allow(dead_code)]
        clk_cfg: StdClkConfig,

        /// Standard mode channel slot configuration.
        #[allow(dead_code)]
        slot_cfg: StdSlotConfig,

        /// Standard mode channel GPIO configuration.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[allow(dead_code)]
        gpio_cfg: StdGpioConfig,
    }

    impl StdConfig {
        /// Create a new standard mode channel configuration from the given clock configuration, slot configuration,
        /// and GPIO configuration.
        pub fn new(
            channel_cfg: Config,
            clk_cfg: StdClkConfig,
            slot_cfg: StdSlotConfig,
            #[cfg(not(esp_idf_version_major = "4"))] gpio_cfg: StdGpioConfig,
        ) -> Self {
            Self {
                channel_cfg,
                clk_cfg,
                slot_cfg,
                #[cfg(not(esp_idf_version_major = "4"))]
                gpio_cfg,
            }
        }

        /// Create a new standard mode channel configuration for the Philips I2S protocol with the specified sample
        /// rate and bits per sample, in stereo mode, with MCLK set to 256 times the sample rate.
        #[inline(always)]
        pub fn philips(sample_rate_hz: u32, bits_per_sample: DataBitWidth) -> Self {
            Self {
                channel_cfg: Config::default(),
                clk_cfg: StdClkConfig::from_sample_rate_hz(sample_rate_hz),
                slot_cfg: StdSlotConfig::philips_slot_default(bits_per_sample, SlotMode::Stereo),
                #[cfg(not(esp_idf_version_major = "4"))]
                gpio_cfg: StdGpioConfig::default(),
            }
        }

        /// Create a new standard mode channel configuration for the PCM I2S protocol with the specified sample rate
        /// and bits per sample, in stereo mode, with MCLK set to 256 times the sample rate.
        #[inline(always)]
        pub fn pcm(sample_rate_hz: u32, bits_per_sample: DataBitWidth) -> Self {
            Self {
                channel_cfg: Config::default(),
                clk_cfg: StdClkConfig::from_sample_rate_hz(sample_rate_hz),
                slot_cfg: StdSlotConfig::pcm_slot_default(bits_per_sample, SlotMode::Stereo),
                #[cfg(not(esp_idf_version_major = "4"))]
                gpio_cfg: StdGpioConfig::default(),
            }
        }

        /// Create a new standard mode channel configuration for the MSB I2S protocol with the specified sample rate
        /// and bits per sample, in stereo mode, with MCLK set to 256 times the sample rate.
        #[inline(always)]
        pub fn msb(sample_rate_hz: u32, bits_per_sample: DataBitWidth) -> Self {
            Self {
                channel_cfg: Config::default(),
                clk_cfg: StdClkConfig::from_sample_rate_hz(sample_rate_hz),
                slot_cfg: StdSlotConfig::msb_slot_default(bits_per_sample, SlotMode::Stereo),
                #[cfg(not(esp_idf_version_major = "4"))]
                gpio_cfg: StdGpioConfig::default(),
            }
        }

        /// Convert to the ESP-IDF SDK `i2s_std_config_t` representation.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[inline(always)]
        pub(crate) fn as_sdk<'d>(
            &self,
            bclk: PeripheralRef<'d, impl InputPin + OutputPin>,
            din: Option<PeripheralRef<'d, impl InputPin>>,
            dout: Option<PeripheralRef<'d, impl OutputPin>>,
            mclk: Option<PeripheralRef<'d, impl InputPin + OutputPin>>,
            ws: PeripheralRef<'d, impl InputPin + OutputPin>,
        ) -> i2s_std_config_t {
            i2s_std_config_t {
                clk_cfg: self.clk_cfg.as_sdk(),
                slot_cfg: self.slot_cfg.as_sdk(),
                gpio_cfg: self.gpio_cfg.as_sdk(bclk, din, dout, mclk, ws),
            }
        }

        /// Convert to the ESP-IDF SDK `i2s_driver_config_t` representation.
        ///
        /// # Note
        /// The mode field is not fully set by this function. Only the controller/target field is set. Before using,
        /// the following bits must be considered: `I2S_MODE_TX`, `I2S_MODE_RX`, `I2S_MODE_DAC_BUILT_IN`, and
        /// `I2S_MODE_ADC_BUILT_IN`. (`I2S_MODE_PDM` should not be used here.)
        #[cfg(esp_idf_version_major = "4")]
        pub(crate) fn as_sdk(&self) -> i2s_driver_config_t {
            let chan_fmt = match self.slot_cfg.slot_mode {
                SlotMode::Stereo => i2s_channel_fmt_t_I2S_CHANNEL_FMT_RIGHT_LEFT,
                SlotMode::Mono => match self.slot_cfg.slot_mask {
                    StdSlotMask::Both => i2s_channel_fmt_t_I2S_CHANNEL_FMT_RIGHT_LEFT,
                    StdSlotMask::Left => i2s_channel_fmt_t_I2S_CHANNEL_FMT_ONLY_LEFT,
                    StdSlotMask::Right => i2s_channel_fmt_t_I2S_CHANNEL_FMT_ONLY_RIGHT,
                },
            };

            i2s_driver_config_t {
                mode: self.channel_cfg.role.as_sdk(),
                sample_rate: self.clk_cfg.sample_rate_hz,
                bits_per_sample: self.slot_cfg.data_bit_width.as_sdk(),
                channel_format: chan_fmt,
                communication_format: self.slot_cfg.comm_fmt.as_sdk(),
                intr_alloc_flags: 1 << 1, // ESP_INTR_FLAG_LEVEL1
                dma_buf_count: self.channel_cfg.dma_buffer_count as i32,
                dma_buf_len: self.channel_cfg.frames_per_buffer as i32,
                #[cfg(any(esp32, esp32s2))]
                use_apll: matches!(self.clk_cfg.clk_src, ClockSource::Apll),
                #[cfg(not(any(esp32, esp32s2)))]
                use_apll: false,
                tx_desc_auto_clear: self.channel_cfg.auto_clear,
                fixed_mclk: 0,
                mclk_multiple: self.clk_cfg.mclk_multiple.as_sdk(),
                bits_per_chan: self.slot_cfg.slot_bit_width.as_sdk(),

                // The following are TDM-only fields and are not present on chips that don't support TDM mode.
                // There's no cfg option for this (it's a constant in esp-idf-sys).
                #[cfg(not(any(esp32, esp32s2)))]
                chan_mask: 0,
                #[cfg(not(any(esp32, esp32s2)))]
                total_chan: 0,
                #[cfg(not(any(esp32, esp32s2)))]
                left_align: self.slot_cfg.left_align,
                #[cfg(not(any(esp32, esp32s2)))]
                big_edin: self.slot_cfg.big_endian,
                #[cfg(not(any(esp32, esp32s2)))]
                bit_order_msb: !self.slot_cfg.bit_order_lsb,
                #[cfg(not(any(esp32, esp32s2)))]
                skip_msk: true,
            }
        }
    }

    /// Standard mode channel clock configuration.
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub struct StdClkConfig {
        /// I2S sample rate.
        sample_rate_hz: u32,

        /// Clock source.
        clk_src: ClockSource,

        /// The multiple of MCLK to the sample rate.
        mclk_multiple: MclkMultiple,
    }

    impl StdClkConfig {
        /// Create a standard clock configuration with the specified rate (in Hz), clock source, and MCLK multiple of
        /// the sample rate.
        #[inline(always)]
        pub fn new(sample_rate_hz: u32, clk_src: ClockSource, mclk_multiple: MclkMultiple) -> Self {
            Self {
                sample_rate_hz,
                clk_src,
                mclk_multiple,
            }
        }

        /// Create a standard clock configuration with the specified rate in Hz. This will set the clock source to
        /// PLL_F160M and the MCLK multiple to 256 times the sample rate.
        ///
        /// # Note
        /// Set the mclk_multiple to [MclkMultiple::M384] when using 24-bit data width. Otherwise, the sample rate
        /// might be imprecise since the BCLK division is not an integer.
        #[inline(always)]
        pub fn from_sample_rate_hz(rate: u32) -> Self {
            Self {
                sample_rate_hz: rate,
                clk_src: ClockSource::default(),
                mclk_multiple: MclkMultiple::M256,
            }
        }

        /// Set the clock source on this standard clock configuration.
        #[inline(always)]
        pub fn clk_src(mut self, clk_src: ClockSource) -> Self {
            self.clk_src = clk_src;
            self
        }

        /// Set the MCLK multiple on this standard clock configuration.
        #[inline(always)]
        pub fn mclk_multiple(mut self, mclk_multiple: MclkMultiple) -> Self {
            self.mclk_multiple = mclk_multiple;
            self
        }

        /// Convert to the ESP-IDF SDK `i2s_std_clk_config_t` representation.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[allow(clippy::needless_update)]
        #[inline(always)]
        pub(crate) fn as_sdk(&self) -> i2s_std_clk_config_t {
            i2s_std_clk_config_t {
                sample_rate_hz: self.sample_rate_hz,
                clk_src: self.clk_src.as_sdk(),
                mclk_multiple: self.mclk_multiple.as_sdk(),
                ..Default::default()
            }
        }
    }

    /// The communication format used by the v4 driver.
    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
    pub enum StdCommFormat {
        /// Standard I2S/Philips format.
        #[default]
        Philips,

        /// MSB-aligned format (data present at first bit clock).
        Msb,

        /// PCM short standard. Word select is one bit clock.
        PcmShort,

        /// PCM long standard. Word select is the same as the data bit width.
        PcmLong,
    }

    impl StdCommFormat {
        #[cfg(esp_idf_version_major = "4")]
        #[inline(always)]
        pub(in crate::i2s) fn as_sdk(&self) -> i2s_comm_format_t {
            match self {
                Self::Philips => i2s_comm_format_t_I2S_COMM_FORMAT_STAND_I2S,
                Self::Msb => i2s_comm_format_t_I2S_COMM_FORMAT_STAND_MSB,
                Self::PcmShort => i2s_comm_format_t_I2S_COMM_FORMAT_PCM_SHORT,
                Self::PcmLong => i2s_comm_format_t_I2S_COMM_FORMAT_PCM_LONG,
            }
        }
    }

    /// Standard mode GPIO (general purpose input/output) configuration.
    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
    pub struct StdGpioConfig {
        /// Invert the BCLK signal.
        bclk_invert: bool,

        /// Invert the MCLK signal.
        mclk_invert: bool,

        /// Invert the WS signal.
        ws_invert: bool,
    }

    impl StdGpioConfig {
        /// Create a new standard mode GPIO configuration with the specified inversion flags for BCLK, MCLK, and WS.
        pub fn new(bclk_invert: bool, mclk_invert: bool, ws_invert: bool) -> Self {
            Self {
                bclk_invert,
                mclk_invert,
                ws_invert,
            }
        }

        /// Set the BCLK inversion flag on this standard GPIO configuration.
        #[inline(always)]
        pub fn bclk_invert(mut self, bclk_invert: bool) -> Self {
            self.bclk_invert = bclk_invert;
            self
        }

        /// Set the MCLK inversion flag on this standard GPIO configuration.
        #[inline(always)]
        pub fn mclk_invert(mut self, mclk_invert: bool) -> Self {
            self.mclk_invert = mclk_invert;
            self
        }

        /// Set the WS inversion flag on this standard GPIO configuration.
        #[inline(always)]
        pub fn ws_invert(mut self, ws_invert: bool) -> Self {
            self.ws_invert = ws_invert;
            self
        }

        /// Convert to the ESP-IDF SDK `i2s_std_gpio_config_t` representation.
        #[cfg(not(esp_idf_version_major = "4"))]
        pub(crate) fn as_sdk<'d>(
            &self,
            bclk: PeripheralRef<'d, impl InputPin + OutputPin>,
            din: Option<PeripheralRef<'d, impl InputPin>>,
            dout: Option<PeripheralRef<'d, impl OutputPin>>,
            mclk: Option<PeripheralRef<'d, impl InputPin + OutputPin>>,
            ws: PeripheralRef<'d, impl InputPin + OutputPin>,
        ) -> i2s_std_gpio_config_t {
            let invert_flags = i2s_std_gpio_config_t__bindgen_ty_1 {
                _bitfield_1: i2s_std_gpio_config_t__bindgen_ty_1::new_bitfield_1(
                    self.mclk_invert as u32,
                    self.bclk_invert as u32,
                    self.ws_invert as u32,
                ),
                ..Default::default()
            };

            i2s_std_gpio_config_t {
                bclk: bclk.pin(),
                din: if let Some(din) = din { din.pin() } else { -1 },
                dout: if let Some(dout) = dout {
                    dout.pin()
                } else {
                    -1
                },
                mclk: if let Some(mclk) = mclk {
                    mclk.pin()
                } else {
                    -1
                },
                ws: ws.pin(),
                invert_flags,
            }
        }
    }

    /// Standard mode channel slot configuration.
    ///
    /// To create a slot configuration, use [`StdSlotConfig::philips_slot_default`], [`StdSlotConfig::pcm_slot_default`], or
    /// [`StdSlotConfig::msb_slot_default`], then customize it as needed.
    ///
    /// # Note
    /// The `slot_mode` and `slot_mask` cause the data to be interpreted in different ways, as noted below.
    /// WS is the "word select" signal, sometimes called LRCLK (left/right clock).
    ///
    /// ## Transmit
    ///
    /// Assuming the buffered data contains the following samples (where a sample may be 1, 2, 3, or 4 bytes, depending
    /// on `data_bit_width`):
    ///
    /// | **`d[0]`** | **`d[1]`** | **`d[2]`** | **`d[3]`** | **`d[4]`** | **`d[5]`** | **`d[6]`** | **`d[7]`** |
    /// |------------|------------|------------|------------|------------|------------|------------|------------|
    /// |  11        | 12         | 13         | 14         | 15         | 16         | 17         | 18         |
    ///
    /// The actual data on the line will be:
    ///
    /// <table>
    ///   <thead>
    ///     <tr><th><code>slot_mode</code></th><th><code>slot_mask</code></th><th colspan=8>Transmitted Data</th></tr>
    ///     <tr><th></th><th></th><th>WS Low</th><th>WS High</th><th>WS Low</th><th>WS High</th><th>WS Low</th><th>WS High</th><th>WS Low</th><th>WS High</th></tr>
    ///   </thead>
    ///   <tbody>
    ///     <tr><td rowspan=3><code>Mono</code></td><td><code>Left</code></td> <td>11</td><td><font color="red">0</font></td><td>12</td><td><font color="red">0</font></td><td>13</td><td><font color="red">0</font></td><td>14</td><td><font color="red">0</font></td></tr>
    ///     <tr>                                    <td><code>Right</code></td><td><font color="red">0</font></td><td>11</td><td><font color="red">0</font></td><td>12</td><td><font color="red">0</font></td><td>13</td><td><font color="red">0</font></td><td>14</td></tr>
    ///     <tr>                                    <td><code>Both</code></td> <td>11</td><td>11</td><td>12</td><td>12</td><td>13</td><td>13</td><td>14</td><td>14</td></tr>
    ///     <tr><td rowspan=3><code>Stereo</code></td><td><code>Left</code></td> <td>11</td><td><font color="red">0</font></td><td>13</td><td><font color="red">0</font></td><td>15</td><td><font color="red">0</font></td><td>17</td><td><font color="red">0</font></td></tr>
    ///     <tr>                                      <td><code>Right</code></td><td><font color="red">0</font></td><td>12</td><td><font color="red">0</font></td><td>14</td><td><font color="red">0</font></td><td>16</td><td><font color="red">0</font></td><td>18</td></tr>
    ///     <tr>                                      <td><code>Both</code></td> <td>11</td><td>12</td><td>13</td><td>14</td><td>15</td><td>16</td><td>17</td><td>18</td></tr>
    ///   </tbody>
    /// </table>
    ///
    ///
    /// ## Receive
    ///
    /// Assuming the received data contains the following samples (where a sample may be 8, 16, 24, or 32 bits, depending on `data_bit_width`):
    ///
    /// | **WS Low**  | **WS High** | **WS Low**  | **WS High** | **WS Low**  | **WS High** | **WS Low**  | **WS High** |     |
    /// |-------------|-------------|-------------|-------------|-------------|-------------|-------------|-------------|-----|
    /// | 11          | 12          | 13          | 14          | 15          | 16          | 17          | 18          | ... |
    ///
    /// The actual data in the buffer will be (1-4 bytes, depending on `data_bit_width`):
    ///
    /// <table>
    ///   <thead>
    ///     <tr><th><code>slot_mode</code></th><th><code>slot_mask</code></th><th colspan=8>Buffer Contents</th></tr>
    ///     <tr><th></th><th></th><th><code>d[0]</code></th><th><code>d[1]</code></th><th><code>d[2]</code></th><th><code>d[3]</code></th><th><code>d[4]</code></th><th><code>d[5]</code></th><th><code>d[6]</code></th><th><code>d[7]</code></th></tr>
    ///   </thead>
    ///   <tbody>
    ///     <tr><td rowspan=3><code>Mono</code></td>  <td><code>Left</code></td> <td>11</td><td>13</td><td>15</td><td>17</td><td>19</td><td>21</td><td>23</td><td>25</td></tr>
    ///     <tr>                                      <td><code>Right</code></td><td>12</td><td>14</td><td>16</td><td>18</td><td>20</td><td>22</td><td>24</td><td>26</td></tr>
    ///     <tr>                                      <td><code>Both</code></td> <td colspan=8><i>Unspecified behavior</i></td></tr>
    ///     <tr><td rowspan=2><code>Stereo</code></td><td><i>Any</i></td>        <td>11</td><td>12</td><td>13</td><td>14</td><td>15</td><td>16</td><td>17</td><td>18</td></tr>
    ///   </tbody>
    /// </table>
    ///
    /// For details, refer to the
    /// _ESP-IDF Programming Guide_ details for your specific microcontroller:
    /// * ESP32: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/i2s.html#std-rx-mode).
    /// * ESP32-S2: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/api-reference/peripherals/i2s.html#std-tx-mode)
    /// * ESP32-S3: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/i2s.html#std-tx-mode)
    /// * ESP32-C3: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-reference/peripherals/i2s.html#std-tx-mode).
    /// * ESP32-C6: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/peripherals/i2s.html#std-tx-mode).
    /// * ESP32-H2: [STD Tx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-reference/peripherals/i2s.html#std-tx-mode) / [STD Rx Mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-reference/peripherals/i2s.html#std-tx-mode).
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub struct StdSlotConfig {
        /// I2S sample data bit width (valid data bits per sample).
        data_bit_width: DataBitWidth,

        /// I2S slot bit width (total bits per slot).
        slot_bit_width: SlotBitWidth,

        /// Mono or stereo mode operation.
        slot_mode: SlotMode,

        /// Are we using the left, right, or both data slots?
        slot_mask: StdSlotMask,

        /// The word select (WS) signal width, in terms of the bit clock (BCK) periods.
        #[cfg(not(esp_idf_version_major = "4"))]
        ws_width: u32,

        /// The word select signal polarity; true enables the light lever first.
        #[cfg(not(esp_idf_version_major = "4"))]
        ws_polarity: bool,

        /// Set to enable the additional bit-shift needed in Philips mode.
        #[cfg(not(esp_idf_version_major = "4"))]
        bit_shift: bool,

        /// ESP32/ESP32S2 only: place the right slot data in the MSB in the FIFO.
        #[cfg(all(any(esp32, esp32s2), not(esp_idf_version_major = "4")))]
        msb_right: bool,

        /// The communication format used by the driver.
        #[cfg(esp_idf_version_major = "4")]
        comm_fmt: StdCommFormat,

        /// Non-ESP32/ESP32S2: enable left-alignment
        #[cfg(not(any(esp32, esp32s2)))]
        left_align: bool,

        /// Non-ESP32/ESP32S2: Enable big-endian.
        #[cfg(not(any(esp32, esp32s2)))]
        big_endian: bool,

        /// Non-ESP32/ESP32S2: Enable LSB-first.
        #[cfg(not(any(esp32, esp32s2)))]
        bit_order_lsb: bool,
    }

    impl StdSlotConfig {
        /// Update the data bit width on this standard slot configuration.
        #[inline(always)]
        pub fn data_bit_width(mut self, data_bit_width: DataBitWidth) -> Self {
            self.data_bit_width = data_bit_width;
            self
        }

        /// Update the slot bit width on this standard slot configuration.
        #[inline(always)]
        pub fn slot_bit_width(mut self, slot_bit_width: SlotBitWidth) -> Self {
            self.slot_bit_width = slot_bit_width;
            self
        }

        /// Update the slot mode and mask on this standard slot configuration.
        #[inline(always)]
        pub fn slot_mode_mask(mut self, slot_mode: SlotMode, slot_mask: StdSlotMask) -> Self {
            self.slot_mode = slot_mode;
            self.slot_mask = slot_mask;
            self
        }

        /// Update the word select signal width on this standard slot configuration.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[inline(always)]
        pub fn ws_width(mut self, ws_width: u32) -> Self {
            self.ws_width = ws_width;
            self
        }

        /// Update the word select signal polarity on this standard slot configuration.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[inline(always)]
        pub fn ws_polarity(mut self, ws_polarity: bool) -> Self {
            self.ws_polarity = ws_polarity;
            self
        }

        /// Update the bit shift flag on this standard slot configuration.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[inline(always)]
        pub fn bit_shift(mut self, bit_shift: bool) -> Self {
            self.bit_shift = bit_shift;
            self
        }

        /// Update the MSB-right flag on this standard slot configuration.
        #[cfg(all(any(esp32, esp32s2), not(esp_idf_version_major = "4")))]
        #[inline(always)]
        pub fn msb_right(mut self, msb_right: bool) -> Self {
            self.msb_right = msb_right;
            self
        }

        /// Update the communication format on this standard slot configuration.
        #[cfg(esp_idf_version_major = "4")]
        #[inline(always)]
        pub fn comm_fmt(mut self, comm_fmt: StdCommFormat) -> Self {
            self.comm_fmt = comm_fmt;
            self
        }

        /// Update the left-alignment flag on this standard slot configuration.
        #[cfg(not(any(esp32, esp32s2)))]
        #[inline(always)]
        pub fn left_align(mut self, left_align: bool) -> Self {
            self.left_align = left_align;
            self
        }

        /// Update the big-endian flag on this standard slot configuration.
        #[cfg(not(any(esp32, esp32s2)))]
        #[inline(always)]
        pub fn big_endian(mut self, big_endian: bool) -> Self {
            self.big_endian = big_endian;
            self
        }

        /// Update the LSB-first flag on this standard slot configuration.
        #[cfg(not(any(esp32, esp32s2)))]
        #[inline(always)]
        pub fn bit_order_lsb(mut self, bit_order_lsb: bool) -> Self {
            self.bit_order_lsb = bit_order_lsb;
            self
        }

        /// Configure in Philips format in 2 slots.
        pub fn philips_slot_default(bits_per_sample: DataBitWidth, slot_mode: SlotMode) -> Self {
            let slot_mask = if slot_mode == SlotMode::Mono {
                StdSlotMask::Left
            } else {
                StdSlotMask::Both
            };

            Self {
                data_bit_width: bits_per_sample,
                slot_bit_width: SlotBitWidth::Auto,
                slot_mode,
                slot_mask,
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_width: bits_per_sample.into(),
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_polarity: false,
                #[cfg(not(esp_idf_version_major = "4"))]
                bit_shift: true,
                #[cfg(all(esp32, not(esp_idf_version_major = "4")))]
                msb_right: bits_per_sample <= DataBitWidth::Bits16,
                #[cfg(all(esp32s2, not(esp_idf_version_major = "4")))]
                msb_right: true,
                #[cfg(esp_idf_version_major = "4")]
                comm_fmt: StdCommFormat::Philips,
                #[cfg(not(any(esp32, esp32s2)))]
                left_align: false,
                #[cfg(not(any(esp32, esp32s2)))]
                big_endian: false,
                #[cfg(not(any(esp32, esp32s2)))]
                bit_order_lsb: false,
            }
        }

        /// Configure in PCM (short) format in 2 slots.
        pub fn pcm_slot_default(bits_per_sample: DataBitWidth, slot_mode: SlotMode) -> Self {
            let slot_mask = if slot_mode == SlotMode::Mono {
                StdSlotMask::Left
            } else {
                StdSlotMask::Both
            };

            Self {
                data_bit_width: bits_per_sample,
                slot_bit_width: SlotBitWidth::Auto,
                slot_mode,
                slot_mask,
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_width: 1,
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_polarity: true,
                #[cfg(not(esp_idf_version_major = "4"))]
                bit_shift: true,
                #[cfg(all(esp32, not(esp_idf_version_major = "4")))]
                msb_right: bits_per_sample <= DataBitWidth::Bits16,
                #[cfg(all(esp32s2, not(esp_idf_version_major = "4")))]
                msb_right: true,
                #[cfg(esp_idf_version_major = "4")]
                comm_fmt: StdCommFormat::PcmShort,
                #[cfg(not(any(esp32, esp32s2)))]
                left_align: false,
                #[cfg(not(any(esp32, esp32s2)))]
                big_endian: false,
                #[cfg(not(any(esp32, esp32s2)))]
                bit_order_lsb: false,
            }
        }

        /// Configure in MSB format in 2 slots.
        pub fn msb_slot_default(bits_per_sample: DataBitWidth, slot_mode: SlotMode) -> Self {
            let slot_mask = if slot_mode == SlotMode::Mono {
                StdSlotMask::Left
            } else {
                StdSlotMask::Both
            };

            Self {
                data_bit_width: bits_per_sample,
                slot_bit_width: SlotBitWidth::Auto,
                slot_mode,
                slot_mask,
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_width: bits_per_sample.into(),
                #[cfg(not(esp_idf_version_major = "4"))]
                ws_polarity: false,
                #[cfg(not(esp_idf_version_major = "4"))]
                bit_shift: false,
                #[cfg(all(esp32, not(esp_idf_version_major = "4")))]
                msb_right: bits_per_sample <= DataBitWidth::Bits16,
                #[cfg(all(esp32s2, not(esp_idf_version_major = "4")))]
                msb_right: true,
                #[cfg(esp_idf_version_major = "4")]
                comm_fmt: StdCommFormat::Msb,
                #[cfg(not(any(esp32, esp32s2)))]
                left_align: false,
                #[cfg(not(any(esp32, esp32s2)))]
                big_endian: false,
                #[cfg(not(any(esp32, esp32s2)))]
                bit_order_lsb: false,
            }
        }

        /// Convert to the ESP-IDF SDK `i2s_std_slot_config_t` representation.
        #[cfg(not(esp_idf_version_major = "4"))]
        pub(crate) fn as_sdk(&self) -> i2s_std_slot_config_t {
            i2s_std_slot_config_t {
                data_bit_width: self.data_bit_width.as_sdk(),
                slot_bit_width: self.slot_bit_width.as_sdk(),
                slot_mode: self.slot_mode.as_sdk(),
                slot_mask: self.slot_mask.as_sdk(),
                ws_width: self.ws_width,
                ws_pol: self.ws_polarity,
                bit_shift: self.bit_shift,
                #[cfg(any(esp32, esp32s2))]
                msb_right: self.msb_right,
                #[cfg(not(any(esp32, esp32s2)))]
                left_align: self.left_align,
                #[cfg(not(any(esp32, esp32s2)))]
                big_endian: self.big_endian,
                #[cfg(not(any(esp32, esp32s2)))]
                bit_order_lsb: self.bit_order_lsb,
            }
        }
    }

    /// I2S slot selection in standard mode.
    ///
    /// The default is `StdSlotMask::Both`.
    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
    pub enum StdSlotMask {
        /// I2S transmits or receives the left slot.
        Left,

        /// I2S transmits or receives the right slot.
        Right,

        /// I2S transmits or receives both slots.
        #[default]
        Both,
    }

    impl StdSlotMask {
        /// Convert to the ESP-IDF SDK `i2s_std_slot_mask_t` representation.
        #[cfg(not(esp_idf_version_major = "4"))]
        #[inline(always)]
        pub(crate) fn as_sdk(&self) -> i2s_std_slot_mask_t {
            match self {
                Self::Left => 1 << 0,
                Self::Right => 1 << 1,
                Self::Both => (1 << 0) | (1 << 1),
            }
        }
    }
}

impl<'d, Dir> I2sDriver<'d, Dir> {
    #[cfg(not(esp_idf_version_major = "4"))]
    #[allow(clippy::too_many_arguments)]
    fn internal_new_std<I2S: I2s>(
        _i2s: impl Peripheral<P = I2S> + 'd,
        config: &config::StdConfig,
        rx: bool,
        tx: bool,
        bclk: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
        din: Option<impl Peripheral<P = impl InputPin> + 'd>,
        dout: Option<impl Peripheral<P = impl OutputPin> + 'd>,
        mclk: Option<impl Peripheral<P = impl InputPin + OutputPin> + 'd>,
        ws: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
    ) -> Result<Self, EspError> {
        let chan_cfg = config.channel_cfg.as_sdk(I2S::port());

        let this = Self::internal_new::<I2S>(&chan_cfg, rx, tx)?;

        // Create the channel configuration.
        let std_config = config.as_sdk(
            bclk.into_ref(),
            din.map(|d_in| d_in.into_ref()),
            dout.map(|d_out| d_out.into_ref()),
            mclk.map(|m_clk| m_clk.into_ref()),
            ws.into_ref(),
        );

        if rx {
            unsafe {
                // Open the RX channel.
                esp!(i2s_channel_init_std_mode(this.rx_handle, &std_config))?;
            }
        }

        if tx {
            unsafe {
                // Open the TX channel.
                esp!(i2s_channel_init_std_mode(this.tx_handle, &std_config))?;
            }
        }

        Ok(this)
    }

    #[cfg(esp_idf_version_major = "4")]
    #[allow(clippy::too_many_arguments)]
    pub fn internal_new_std<I2S: I2s>(
        _i2s: impl Peripheral<P = I2S> + 'd,
        config: &config::StdConfig,
        rx: bool,
        tx: bool,
        bclk: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
        din: Option<impl Peripheral<P = impl InputPin> + 'd>,
        dout: Option<impl Peripheral<P = impl OutputPin> + 'd>,
        mclk: Option<impl Peripheral<P = impl InputPin + OutputPin> + 'd>,
        ws: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
    ) -> Result<Self, EspError> {
        let mut driver_cfg = config.as_sdk();

        if rx {
            driver_cfg.mode |= i2s_mode_t_I2S_MODE_RX;
        }

        if tx {
            driver_cfg.mode |= i2s_mode_t_I2S_MODE_TX;
        }

        let this = Self::internal_new::<I2S>(&driver_cfg)?;

        // Set the pin configuration.
        let pin_cfg = i2s_pin_config_t {
            bck_io_num: bclk.into_ref().pin(),
            data_in_num: din.map(|din| din.into_ref().pin()).unwrap_or(-1),
            data_out_num: dout.map(|dout| dout.into_ref().pin()).unwrap_or(-1),
            mck_io_num: mclk.map(|mclk| mclk.into_ref().pin()).unwrap_or(-1),
            ws_io_num: ws.into_ref().pin(),
        };

        // Safety: &pin_cfg is a valid pointer to an i2s_pin_config_t.
        unsafe {
            esp!(i2s_set_pin(I2S::port(), &pin_cfg))?;
        }

        Ok(this)
    }
}

impl<'d> I2sDriver<'d, I2sBiDir> {
    /// Create a new standard mode driver for the given I2S peripheral with both the receive and transmit channels open.
    #[allow(clippy::too_many_arguments)]
    pub fn new_std_bidir<I2S: I2s>(
        i2s: impl Peripheral<P = I2S> + 'd,
        config: &config::StdConfig,
        bclk: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
        din: impl Peripheral<P = impl InputPin> + 'd,
        dout: impl Peripheral<P = impl OutputPin> + 'd,
        mclk: Option<impl Peripheral<P = impl InputPin + OutputPin> + 'd>,
        ws: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
    ) -> Result<Self, EspError> {
        Self::internal_new_std(
            i2s,
            config,
            true,
            true,
            bclk,
            Some(din),
            Some(dout),
            mclk,
            ws,
        )
    }
}

impl<'d> I2sDriver<'d, I2sRx> {
    /// Create a new standard mode driver for the given I2S peripheral with only the receive channel open.
    #[allow(clippy::too_many_arguments)]
    pub fn new_std_rx<I2S: I2s>(
        i2s: impl Peripheral<P = I2S> + 'd,
        config: &config::StdConfig,
        bclk: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
        din: impl Peripheral<P = impl InputPin> + 'd,
        mclk: Option<impl Peripheral<P = impl InputPin + OutputPin> + 'd>,
        ws: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
    ) -> Result<Self, EspError> {
        Self::internal_new_std(
            i2s,
            config,
            true,
            false,
            bclk,
            Some(din),
            AnyIOPin::none(),
            mclk,
            ws,
        )
    }
}

impl<'d> I2sDriver<'d, I2sTx> {
    /// Create a new standard mode driver for the given I2S peripheral with only the transmit channel open.
    #[allow(clippy::too_many_arguments)]
    pub fn new_std_tx<I2S: I2s>(
        i2s: impl Peripheral<P = I2S> + 'd,
        config: &config::StdConfig,
        bclk: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
        dout: impl Peripheral<P = impl OutputPin> + 'd,
        mclk: Option<impl Peripheral<P = impl InputPin + OutputPin> + 'd>,
        ws: impl Peripheral<P = impl InputPin + OutputPin> + 'd,
    ) -> Result<Self, EspError> {
        Self::internal_new_std(
            i2s,
            config,
            false,
            true,
            bclk,
            AnyIOPin::none(),
            Some(dout),
            mclk,
            ws,
        )
    }
}