//! # Serial Peripheral Interface - Master Mode

//!

//! ## Overview

//!

//! In this mode, the SPI acts as master and initiates the SPI transactions.

//!

//! ## Configuration

//!

//! The peripheral can be used in full-duplex and half-duplex mode and can

//! leverage DMA for data transfers. It can also be used in blocking or async.

//!

//! ### Exclusive access to the SPI bus

//!

//! If all you want to do is to communicate to a single device, and you initiate

//! transactions yourself, there are a number of ways to achieve this:

//!

//! - Use the [`SpiBus`] or [`SpiBusAsync`] trait and its associated functions to initiate

//!   transactions with simultaneous reads and writes, or

//! - Use the `ExclusiveDevice` struct from [`embedded-hal-bus`] or `SpiDevice` from

//!   [`embassy-embedded-hal`].

//!

//! ### Shared SPI access

//!

//! If you have multiple devices on the same SPI bus that each have their own CS

//! line (and optionally, configuration), you may want to have a look at the

//! implementations provided by [`embedded-hal-bus`] and

//! [`embassy-embedded-hal`].

//!

//! ## Usage

//!

//! The module implements several third-party traits from embedded-hal@1.x.x

//! and [`embassy-embedded-hal`].

//!

//! [`embedded-hal-bus`]: https://docs.rs/embedded-hal-bus/latest/embedded_hal_bus/spi/index.html

//! [`embassy-embedded-hal`]: embassy_embedded_hal::shared_bus

use core::{marker::PhantomData, sync::atomic::Ordering};

#[cfg(spi_master_supports_dma)]

mod dma;

mod low_level;

#[instability::unstable]

#[cfg(spi_master_supports_dma)]

pub use dma::*;

use embedded_hal::spi::SpiBus;

use embedded_hal_async::spi::SpiBus as SpiBusAsync;

use enumset::EnumSetType;

use low_level::{Driver, SpiWrapper};

pub use low_level::{Info, Instance, QspiInstance, State};

use procmacros::doc_replace;

use super::{BitOrder, Error, Mode};

use crate::{

    Async,

    Blocking,

    DriverMode,

    gpio::{

        InputConfig,

        NoPin,

        OutputConfig,

        OutputSignal,

        PinGuard,

        interconnect::{self, PeripheralInput, PeripheralOutput},

    },

    interrupt::InterruptHandler,

    private::Sealed,

    spi::master::low_level::SpiClockGuard,

    time::Rate,

};

/// Enumeration of possible SPI interrupt events.

#[derive(Debug, Hash, EnumSetType)]

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

#[non_exhaustive]

#[instability::unstable]

pub enum SpiInterrupt {

    /// Indicates that the SPI transaction has completed successfully.

    ///

    /// This interrupt is triggered when an SPI transaction has finished

    /// transmitting and receiving data.

    TransferDone,

    /// Triggered at the end of configurable segmented transfer.

    #[cfg(spi_master_has_dma_segmented_transfer)]

    DmaSegmentedTransferDone,

    /// Used and triggered by software. Only used for user defined function.

    #[cfg(spi_master_has_app_interrupts)]

    App2,

    /// Used and triggered by software. Only used for user defined function.

    #[cfg(spi_master_has_app_interrupts)]

    App1,

}

/// The size of the FIFO buffer for SPI.

const FIFO_SIZE: usize = property!("spi_master.fifo_size");

/// Padding byte for empty write transfers

const EMPTY_WRITE_PAD: u8 = 0x00;

/// SPI commands, each consisting of a 16-bit command value and a data mode.

///

/// Used to define specific commands sent over the SPI bus.

/// Can be [Command::None] if command phase should be suppressed.

#[non_exhaustive]

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

#[instability::unstable]

pub enum Command {

    /// No command is sent.

    None,

    /// A 1-bit command.

    /// A 2-bit command.

    /// A 3-bit command.

    /// A 4-bit command.

    /// A 5-bit command.

    /// A 6-bit command.

    /// A 7-bit command.

    /// A 8-bit command.

    /// A 9-bit command.

    /// A 10-bit command.

    /// A 11-bit command.

    /// A 12-bit command.

    /// A 13-bit command.

    /// A 14-bit command.

    /// A 15-bit command.

    /// A 16-bit command.

}

impl Command {

    fn width(&self) -> usize {

        match self {

            Command::None => 0,

            Command::_1Bit(_, _) => 1,

            Command::_2Bit(_, _) => 2,

            Command::_3Bit(_, _) => 3,

            Command::_4Bit(_, _) => 4,

            Command::_5Bit(_, _) => 5,

            Command::_6Bit(_, _) => 6,

            Command::_7Bit(_, _) => 7,

            Command::_8Bit(_, _) => 8,

            Command::_9Bit(_, _) => 9,

            Command::_10Bit(_, _) => 10,

            Command::_11Bit(_, _) => 11,

            Command::_12Bit(_, _) => 12,

            Command::_13Bit(_, _) => 13,

            Command::_14Bit(_, _) => 14,

            Command::_15Bit(_, _) => 15,

            Command::_16Bit(_, _) => 16,

        }

    }

    fn value(&self) -> u16 {

        match self {

            Command::None => 0,

            Command::_1Bit(value, _)

            | Command::_2Bit(value, _)

            | Command::_3Bit(value, _)

            | Command::_4Bit(value, _)

            | Command::_5Bit(value, _)

            | Command::_6Bit(value, _)

            | Command::_7Bit(value, _)

            | Command::_8Bit(value, _)

            | Command::_9Bit(value, _)

            | Command::_10Bit(value, _)

            | Command::_11Bit(value, _)

            | Command::_12Bit(value, _)

            | Command::_13Bit(value, _)

            | Command::_14Bit(value, _)

            | Command::_15Bit(value, _)

            | Command::_16Bit(value, _) => *value,

        }

    }

    fn mode(&self) -> DataMode {

            Command::None => DataMode::SingleTwoDataLines,

            Command::_1Bit(_, mode)

            | Command::_2Bit(_, mode)

            | Command::_3Bit(_, mode)

            | Command::_4Bit(_, mode)

            | Command::_5Bit(_, mode)

            | Command::_6Bit(_, mode)

            | Command::_7Bit(_, mode)

            | Command::_8Bit(_, mode)

            | Command::_9Bit(_, mode)

            | Command::_10Bit(_, mode)

            | Command::_11Bit(_, mode)

            | Command::_12Bit(_, mode)

            | Command::_13Bit(_, mode)

            | Command::_14Bit(_, mode)

            | Command::_15Bit(_, mode)

            | Command::_16Bit(_, mode) => *mode,

        }

    }

    fn is_none(&self) -> bool {

        matches!(self, Command::None)

    }

}

/// SPI address, ranging from 1 to 32 bits, paired with a data mode.

///

/// This can be used to specify the address phase of SPI transactions.

/// Can be [Address::None] if address phase should be suppressed.

#[non_exhaustive]

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

#[instability::unstable]

pub enum Address {

    /// No address phase.

    None,

    /// A 1-bit address.

    /// A 2-bit address.

    /// A 3-bit address.

    /// A 4-bit address.

    /// A 5-bit address.

    /// A 6-bit address.

    /// A 7-bit address.

    /// A 8-bit address.

    /// A 9-bit address.

    /// A 10-bit address.

    /// A 11-bit address.

    /// A 12-bit address.

    /// A 13-bit address.

    /// A 14-bit address.

    /// A 15-bit address.

    /// A 16-bit address.

    /// A 17-bit address.

    /// A 18-bit address.

    /// A 19-bit address.

    /// A 20-bit address.

    /// A 21-bit address.

    /// A 22-bit address.

    /// A 23-bit address.

    /// A 24-bit address.

    /// A 25-bit address.

    /// A 26-bit address.

    /// A 27-bit address.

    /// A 28-bit address.

    /// A 29-bit address.

    /// A 30-bit address.

    /// A 31-bit address.

    /// A 32-bit address.

}

impl Address {

    fn width(&self) -> usize {

        match self {

            Address::None => 0,

            Address::_1Bit(_, _) => 1,

            Address::_2Bit(_, _) => 2,

            Address::_3Bit(_, _) => 3,

            Address::_4Bit(_, _) => 4,

            Address::_5Bit(_, _) => 5,

            Address::_6Bit(_, _) => 6,

            Address::_7Bit(_, _) => 7,

            Address::_8Bit(_, _) => 8,

            Address::_9Bit(_, _) => 9,

            Address::_10Bit(_, _) => 10,

            Address::_11Bit(_, _) => 11,

            Address::_12Bit(_, _) => 12,

            Address::_13Bit(_, _) => 13,

            Address::_14Bit(_, _) => 14,

            Address::_15Bit(_, _) => 15,

            Address::_16Bit(_, _) => 16,

            Address::_17Bit(_, _) => 17,

            Address::_18Bit(_, _) => 18,

            Address::_19Bit(_, _) => 19,

            Address::_20Bit(_, _) => 20,

            Address::_21Bit(_, _) => 21,

            Address::_22Bit(_, _) => 22,

            Address::_23Bit(_, _) => 23,

            Address::_24Bit(_, _) => 24,

            Address::_25Bit(_, _) => 25,

            Address::_26Bit(_, _) => 26,

            Address::_27Bit(_, _) => 27,

            Address::_28Bit(_, _) => 28,

            Address::_29Bit(_, _) => 29,

            Address::_30Bit(_, _) => 30,

            Address::_31Bit(_, _) => 31,

            Address::_32Bit(_, _) => 32,

        }

    }

    fn value(&self) -> u32 {

        match self {

            Address::None => 0,

            Address::_1Bit(value, _)

            | Address::_2Bit(value, _)

            | Address::_3Bit(value, _)

            | Address::_4Bit(value, _)

            | Address::_5Bit(value, _)

            | Address::_6Bit(value, _)

            | Address::_7Bit(value, _)

            | Address::_8Bit(value, _)

            | Address::_9Bit(value, _)

            | Address::_10Bit(value, _)

            | Address::_11Bit(value, _)

            | Address::_12Bit(value, _)

            | Address::_13Bit(value, _)

            | Address::_14Bit(value, _)

            | Address::_15Bit(value, _)

            | Address::_16Bit(value, _)

            | Address::_17Bit(value, _)

            | Address::_18Bit(value, _)

            | Address::_19Bit(value, _)

            | Address::_20Bit(value, _)

            | Address::_21Bit(value, _)

            | Address::_22Bit(value, _)

            | Address::_23Bit(value, _)

            | Address::_24Bit(value, _)

            | Address::_25Bit(value, _)

            | Address::_26Bit(value, _)

            | Address::_27Bit(value, _)

            | Address::_28Bit(value, _)

            | Address::_29Bit(value, _)

            | Address::_30Bit(value, _)

            | Address::_31Bit(value, _)

            | Address::_32Bit(value, _) => *value,

        }

    }

    fn is_none(&self) -> bool {

        matches!(self, Address::None)

    }

    fn mode(&self) -> DataMode {

            Address::None => DataMode::SingleTwoDataLines,

            Address::_1Bit(_, mode)

            | Address::_2Bit(_, mode)

            | Address::_3Bit(_, mode)

            | Address::_4Bit(_, mode)

            | Address::_5Bit(_, mode)

            | Address::_6Bit(_, mode)

            | Address::_7Bit(_, mode)

            | Address::_8Bit(_, mode)

            | Address::_9Bit(_, mode)

            | Address::_10Bit(_, mode)

            | Address::_11Bit(_, mode)

            | Address::_12Bit(_, mode)

            | Address::_13Bit(_, mode)

            | Address::_14Bit(_, mode)

            | Address::_15Bit(_, mode)

            | Address::_16Bit(_, mode)

            | Address::_17Bit(_, mode)

            | Address::_18Bit(_, mode)

            | Address::_19Bit(_, mode)

            | Address::_20Bit(_, mode)

            | Address::_21Bit(_, mode)

            | Address::_22Bit(_, mode)

            | Address::_23Bit(_, mode)

            | Address::_24Bit(_, mode)

            | Address::_25Bit(_, mode)

            | Address::_26Bit(_, mode)

            | Address::_27Bit(_, mode)

            | Address::_28Bit(_, mode)

            | Address::_29Bit(_, mode)

            | Address::_30Bit(_, mode)

            | Address::_31Bit(_, mode)

            | Address::_32Bit(_, mode) => *mode,

        }

    }

}

/// SPI clock source.

#[instability::unstable]

pub use crate::soc::clocks::SpiFunctionClockConfig as ClockSource;

/// SPI peripheral configuration

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

#[non_exhaustive]

pub struct Config {

    /// The precomputed clock configuration register value.

    ///

    /// Clock divider calculations are relatively expensive, and the SPI

    /// peripheral is commonly expected to be used in a shared bus

    /// configuration, where different devices may need different bus clock

    /// frequencies. To reduce the time required to reconfigure the bus, the

    /// clock register value is cached here for each configuration.

    ///

    /// This field is not intended to be set from application code, and is only used

    /// internally.

    #[builder_lite(skip)]

    reg: Result<u32, ConfigError>,

    /// The target frequency.

    #[builder_lite(skip_setter)]

    frequency: Rate,

    /// The clock source.

    #[builder_lite(unstable)]

    #[builder_lite(skip_setter)]

    clock_source: ClockSource,

    /// SPI sample/shift mode.

    mode: Mode,

    /// Bit order of the read data.

    read_bit_order: BitOrder,

    /// Bit order of the written data.

    write_bit_order: BitOrder,

    /// Minimum transfer size in bytes below which CPU-driven (blocking) I/O

    /// is used instead of async or DMA transfers.

    ///

    /// This can reduce overhead for small transfers where DMA setup or

    /// async context-switch cost exceeds the benefit. For

    /// [`SpiDma`][crate::spi::master::dma::SpiDma], the threshold applies in

    /// both blocking and async DMA modes: when met, DMA is disabled and the

    /// transfer is performed by the CPU. This applies to both full-duplex and

    /// half-duplex transfers.

    ///

    /// A value of `0` (the default) disables the threshold — all transfers use

    /// the driver's default method.

    #[builder_lite(unstable)]

    min_async_transfer_size: usize,

}

impl Default for Config {

        let mut this = Config {

            reg: Ok(0),

            frequency: Rate::from_mhz(1),

            clock_source: ClockSource::default(),

            mode: Mode::_0,

            read_bit_order: BitOrder::MsbFirst,

            write_bit_order: BitOrder::MsbFirst,

            min_async_transfer_size: 0,

        };

}

impl Config {

    /// Sets the frequency of the SPI bus clock.

    ///

    /// The closest available frequency that does not exceed `frequency` is used,

    /// so the bus never runs faster than requested.

    /// Sets the clock source of the SPI bus.

    #[instability::unstable]

    fn clock_source_freq_hz(&self) -> Rate {

        Rate::from_hz(

        )

    }

        // TODO: model peripheral-side clock divider, allow the user to directly configure it

        // taken from https://github.com/apache/incubator-nuttx/blob/8267a7618629838231256edfa666e44b5313348e/arch/risc-v/src/esp32c3/esp32c3_spi.c#L496

        let source_freq = self.clock_source_freq_hz();

        // In HW, n, h and l fields range from 1 to 64, pre ranges from 1 to 8K.

        // The value written to register is one lower than the used value.

            // Bypass the divider, which is exactly the source frequency.

            // Set the SPI_CLK_EQU_SYSCLK bit.

            return Ok(1 << 31);

        }

        let (n, pre) = Self::divider_pair(source_freq.as_hz(), self.frequency.as_hz());

        // In master mode, L == N

        let l = n;

        // In master mode, this field must be floor((SPI_CLKCNT_N + 1)/2 - 1)

    /// Finds the `(n, pre)` pair producing the highest bus frequency that does

    /// not exceed `target_freq_hz`, where `n` is `SPI_CLKCNT_N + 1` and `pre` is

    /// `SPI_CLKDIV_PRE + 1`.

    ///

    /// The peripheral divides the source clock by `pre * n`, so this is the

    /// smallest divider that does not overshoot. `n` also determines the duty

    /// cycle resolution, so among pairs forming that divider the one with the

    /// largest `n` is preferred.

    ///

    /// Out-of-range frequencies (see [`Config::validate`]) yield the slowest pair

    /// available rather than an error.

    fn divider_pair(source_freq_hz: u32, target_freq_hz: u32) -> (u32, u32) {

        // A zero target is rejected by `validate`, but must not divide by zero

        // here.

            return (64, 16);

        }

        // Any smaller divider would run the bus faster than requested. `n` starts

        // at 2 so that h/l can describe at least one high and one low pulse.

        let min_divider = source_freq_hz.div_ceil(target_freq_hz).max(2);

        // A `pre` of 1 offers every divider up to 64, so if the smallest usable

        // divider is in that range we can form it directly, with the largest `n`

        // that produces it.

            return (min_divider, 1);

        }

        // `n` maxes out at 64, so a smaller `pre` cannot bring the source clock

        // down to the target. As `n` shrinks when `pre` grows, walking `pre`

        // upwards visits the candidates in order of decreasing duty cycle

        // resolution, which lets us keep the first of several that share a

        // divider.

        //

        // The seed is the slowest pair, which also answers requests below the

        // supported range.

        let mut best = (64, 16);

        let mut best_divider = 64 * 16;

        // A `for` loop over a range would leave a divide-by-zero check on `pre`

        // in the generated code, as the lower bound is not visible through the

        // range iterator on all targets.

        let mut pre = min_divider.div_ceil(64);

            // The smallest `n` that keeps `pre * n` from overshooting. The lower

            // bound on `pre` keeps this at or below 64.

            let n = min_divider.div_ceil(pre);

                best = (n, pre);

                best_divider = divider;

                // Nothing can beat hitting the smallest usable divider exactly.

                    break;

                }

            }

        }

        best

    }

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

    }

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

        let source_freq = self.clock_source_freq_hz();

        let min_divider = 1;

        // FIXME: while ESP32 and S2 support pre dividers as large as 8192,

        // those values are not currently supported by the divider calculation.

        let max_divider = 16 * 64; // n * pre

        {

            return Err(ConfigError::FrequencyOutOfRange);

        }

        Ok(())

    }

}

const SIO_PIN_COUNT: usize = 4 + cfg!(spi_master_has_octal) as usize * 4;

#[derive(Debug)]

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

struct SpiPinGuard {

    sclk_pin: PinGuard,

    cs_pin: PinGuard,

    sio_pins: [PinGuard; SIO_PIN_COUNT],

}

impl SpiPinGuard {

    const fn new_unconnected() -> Self {

        Self {

            sclk_pin: PinGuard::new_unconnected(),

            cs_pin: PinGuard::new_unconnected(),

            sio_pins: [const { PinGuard::new_unconnected() }; SIO_PIN_COUNT],

        }

    }

}

/// Configuration errors.

#[non_exhaustive]

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

pub enum ConfigError {

    /// The requested frequency is not in the supported range.

    FrequencyOutOfRange,

}

impl core::error::Error for ConfigError {}

impl core::fmt::Display for ConfigError {

    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {

        match self {

            ConfigError::FrequencyOutOfRange => {

                write!(f, "The requested frequency is not in the supported range")

            }

        }

    }

}

#[procmacros::doc_replace]

/// SPI peripheral driver

///

/// # Examples

///

/// ```rust, no_run

/// # {before_snippet}

/// use esp_hal::spi::{

///     Mode,

///     master::{Config, Spi},

/// };

/// let mut spi = Spi::new(

///     peripherals.SPI2,

///     Config::default()

///         .with_frequency(Rate::from_khz(100))

///         .with_mode(Mode::_0),

/// )?

/// .with_sck(peripherals.GPIO0)

/// .with_mosi(peripherals.GPIO1)

/// .with_miso(peripherals.GPIO2);

/// # {after_snippet}

/// ```

#[derive(Debug)]

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

pub struct Spi<'d, Dm: DriverMode> {

    spi: SpiWrapper<'d>,

    _mode: PhantomData<Dm>,

}

impl<Dm: DriverMode> Sealed for Spi<'_, Dm> {}

impl<'d> Spi<'d, Blocking> {

    #[procmacros::doc_replace]

    /// Creates a new SPI instance in 8-bit data-frame mode.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2);

    /// # {after_snippet}

    /// ```

    ///

    /// # Errors

    ///

    /// See [`Spi::apply_config`]

            _mode: PhantomData,

            spi: SpiWrapper::new(spi),

        };

        this.apply_config(&config)?;

        let this = this.with_sck(NoPin).with_cs(NoPin);

        for sio in 0..8 {

            if let Some(signal) = this.driver().info.opt_sio_input(sio) {

                signal.connect_to(&NoPin);

            }

            if let Some(signal) = this.driver().info.opt_sio_output(sio) {

                signal.connect_to(&NoPin);

            }

        }

        Ok(this)

    /// Reconfigures the driver to operate in [`Async`] mode.

    ///

    /// See the [`Async`] documentation for an example on how to use this

    /// method.

        self.set_interrupt_handler(self.spi.info().async_handler);

        Spi {

            spi: self.spi,

            _mode: PhantomData,

        }

    #[doc_replace(

        "peripheral_on" => {

            cfg(multi_core) => "peripheral on the current core",

            _ => "peripheral",

        }

    )]

    /// Registers an interrupt handler for the __peripheral_on__.

    ///

    /// Replaces any previously registered interrupt handlers.

    ///

    /// The default/unhandled interrupt handler can be restored with

    /// [crate::interrupt::DEFAULT_INTERRUPT_HANDLER]

    ///

    /// # Panics

    ///

    /// Panics if passed interrupt handler is invalid (e.g. has priority

    /// `None`)

    #[instability::unstable]

    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {

        self.spi.set_interrupt_handler(handler);

    }

}

#[instability::unstable]

impl crate::interrupt::InterruptConfigurable for Spi<'_, Blocking> {

    /// Sets the interrupt handler.

    ///

    /// Interrupts are not enabled at the peripheral level here.

    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {

        self.set_interrupt_handler(handler);

    }

}

impl<'d> Spi<'d, Async> {

    /// Reconfigures the driver to operate in [`Blocking`] mode.

    ///

    /// See the [`Blocking`] documentation for an example on how to use this

    /// method.

    pub fn into_blocking(self) -> Spi<'d, Blocking> {

        self.spi.disable_peri_interrupt_on_all_cores();

        Spi {

            spi: self.spi,

            _mode: PhantomData,

        }

    }

    #[procmacros::doc_replace]

    /// Waits for the completion of previous operations.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2)

    ///     .into_async();

    ///

    /// let mut buffer = [0; 10];

    /// spi.transfer_in_place_async(&mut buffer).await?;

    /// spi.flush_async().await?;

    ///

    /// # {after_snippet}

    /// ```

    pub async fn flush_async(&mut self) -> Result<(), Error> {

        Ok(())

    }

    #[procmacros::doc_replace]

    /// Sends `words` to the slave. Returns the `words` received from the slave.

    ///

    /// Aborts the transfer when its Future is dropped. Some amount of data may have

    /// been transferred before the Future is dropped. Dropping the future may block

    /// for a short while to ensure the transfer is aborted.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2)

    ///     .into_async();

    ///

    /// let mut buffer = [0; 10];

    /// spi.transfer_in_place_async(&mut buffer).await?;

    ///

    /// # {after_snippet}

    /// ```

        }

    /// Half-duplex read.

    ///

    /// Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across

    /// chunks, but the clock pauses while the CPU prepares each subsequent chunk.

    ///

    /// Aborts the transfer when its Future is dropped. Some amount of data may have

    /// been transferred before the Future is dropped. Dropping the future may block

    /// for a short while to ensure the transfer is aborted.

    ///

    /// # Errors

    ///

    /// [`Error::Unsupported`] when the buffer is empty (currently unsupported).

    /// `DataMode::Single` cannot be combined with any other [`DataMode`], otherwise

    /// [`Error::Unsupported`].

    #[instability::unstable]

    pub async fn half_duplex_read_async(

        &mut self,

            return self

        }

            .half_duplex_read_async(data_mode, cmd, address, dummy, buffer)

    /// Half-duplex write.

    ///

    /// Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across

    /// chunks, but the clock pauses while the CPU prepares each subsequent chunk.

    ///

    /// Aborts the transfer when its Future is dropped. Some amount of data may have

    /// been transferred before the Future is dropped. Dropping the future may block

    /// for a short while to ensure the transfer is aborted.

    ///

    /// # Errors

    ///

    /// [`Error::Unsupported`] for unsupported combinations of command, address,

    /// dummy, and data modes.

    #[cfg_attr(

        esp32,

        doc = "Dummy phase configuration is currently not supported, only value `0` is valid (see issue [#2240](https://github.com/esp-rs/esp-hal/issues/2240))."

    )]

    #[instability::unstable]

    pub async fn half_duplex_write_async(

        &mut self,

        data_mode: DataMode,

        cmd: Command,

        address: Address,

        dummy: u8,

        buffer: &[u8],

    ) -> Result<(), Error> {

        let _clock = SpiClockGuard::new(self.spi.info());

        if self.use_blocking_transfer(buffer.len()) {

            return self

                .driver()

                .half_duplex_write(data_mode, cmd, address, dummy, buffer);

        }

        self.driver()

            .half_duplex_write_async(data_mode, cmd, address, dummy, buffer)

            .await

    }

    // TODO: These inherent methods should be public

    async fn read_async(&mut self, words: &mut [u8]) -> Result<(), Error> {

        let _clock = SpiClockGuard::new(self.spi.info());

        self.driver().setup_full_duplex()?;

        if self.use_blocking_transfer(words.len()) {

            return self.driver().read(words);

        }

        self.driver().read_async(words).await

    }

    async fn write_async(&mut self, words: &[u8]) -> Result<(), Error> {

        let _clock = SpiClockGuard::new(self.spi.info());

        self.driver().setup_full_duplex()?;

        if self.use_blocking_transfer(words.len()) {

            return self.driver().write(words);

        }

        self.driver().write_async(words).await

    }

}

macro_rules! def_with_sio_pin {

    ($fn:ident, $n:literal) => {

        #[doc = concat!(" Assign the SIO", stringify!($n), " pin for the SPI instance.")]

        #[doc = " "]

        #[doc = " Enables both input and output functionality for the pin, and connects it"]

        #[doc = concat!(" to the SIO", stringify!($n), " output and input signals.")]

        #[instability::unstable]

        pub fn $fn(mut self, sio: impl PeripheralInput<'d> + PeripheralOutput<'d>) -> Self {

            self

        }

    };

}

impl<'d, Dm> Spi<'d, Dm>

where

    Dm: DriverMode,

{

        pin.apply_input_config(&InputConfig::default());

        pin.apply_output_config(&OutputConfig::default());

        pin.set_input_enable(true);

        pin.set_output_enable(false);

        in_signal.connect_to(&pin);

    fn connect_sio_output_pin(&self, pin: interconnect::OutputSignal<'d>, n: usize) -> PinGuard {

    }

        &self,

        pin: interconnect::OutputSignal<'d>,

        signal: OutputSignal,

    ) -> PinGuard {

        pin.apply_output_config(&OutputConfig::default());

        pin.set_output_enable(true); // TODO turn this bool into a Yes/No/PeripheralControl trio

    }

    #[procmacros::doc_replace]

    /// Assigns the SCK (Serial Clock) pin for the SPI instance.

    ///

    /// Configures the specified pin to push-pull output and connects it to the

    /// SPI clock signal.

    ///

    /// Disconnects the previous pin that was assigned with `with_sck`.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_sck(peripherals.GPIO0);

    ///

    /// # {after_snippet}

    /// ```

    pub fn with_sck(mut self, sclk: impl PeripheralOutput<'d>) -> Self {

        let info = self.spi.info();

        self

    }

    #[procmacros::doc_replace]

    /// Assigns the MOSI (Master Out Slave In) pin for the SPI instance.

    ///

    /// Enables output functionality for the pin, and connects it as the MOSI

    /// signal. Use this for full-duplex SPI or

    /// when using [DataMode::SingleTwoDataLines].

    ///

    /// Disconnects the previous pin that was assigned with `with_mosi` or

    /// `with_sio0`.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_mosi(peripherals.GPIO1);

    ///

    /// # {after_snippet}

    /// ```

    pub fn with_mosi(mut self, mosi: impl PeripheralOutput<'d>) -> Self {

        self

    }

    #[procmacros::doc_replace]

    /// Assigns the MISO (Master In Slave Out) pin for the SPI instance.

    ///

    /// Enables input functionality for the pin, and connects it to the MISO

    /// signal.

    ///

    /// Use this for full-duplex SPI or

    /// [DataMode::SingleTwoDataLines]

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_miso(peripherals.GPIO2);

    ///

    /// # {after_snippet}

    /// ```

    pub fn with_miso(self, miso: impl PeripheralInput<'d>) -> Self {

        miso.apply_input_config(&InputConfig::default());

        miso.set_input_enable(true);

        self

    }

    /// Assigns the SIO0 pin for the SPI instance.

    ///

    /// Enables both input and output functionality for the pin, and connects it

    /// to the MOSI output signal and SIO0 input signal.

    ///

    /// Disconnects the previous pin that was assigned with `with_sio0` or

    /// `with_mosi`.

    ///

    /// Use this if any of the devices on the bus use half-duplex SPI.

    ///

    /// See also [Self::with_mosi] for a one-directional MOSI

    /// signal.

    #[instability::unstable]

    pub fn with_sio0(mut self, mosi: impl PeripheralInput<'d> + PeripheralOutput<'d>) -> Self {

        self

    }

    /// Assigns the SIO1/MISO pin for the SPI instance.

    ///

    /// Enables both input and output functionality for the pin, and connects it

    /// to the MISO input signal and SIO1 output signal.

    ///

    /// Disconnects the previous pin that was assigned with `with_sio1`.

    ///

    /// Use this if any of the devices on the bus use half-duplex SPI.

    ///

    /// See also [Self::with_miso] for a one-directional MISO

    /// signal.

    #[instability::unstable]

    pub fn with_sio1(mut self, sio1: impl PeripheralInput<'d> + PeripheralOutput<'d>) -> Self {

        self

    }

    def_with_sio_pin!(with_sio2, 2);

    def_with_sio_pin!(with_sio3, 3);

    #[cfg(spi_master_has_octal)]

    def_with_sio_pin!(with_sio4, 4);

    #[cfg(spi_master_has_octal)]

    def_with_sio_pin!(with_sio5, 5);

    #[cfg(spi_master_has_octal)]

    def_with_sio_pin!(with_sio6, 6);

    #[cfg(spi_master_has_octal)]

    def_with_sio_pin!(with_sio7, 7);

    /// Assigns the CS (Chip Select) pin for the SPI instance.

    ///

    /// Configures the specified pin to push-pull output and connects it to the

    /// SPI CS signal.

    ///

    /// Disconnects the previous pin that was assigned with `with_cs`.

    ///

    /// # Current Stability Limitations

    /// The hardware chip select functionality is limited; only one CS line can

    /// be set, regardless of the total number available. There is no

    /// mechanism to select which CS line to use.

    #[instability::unstable]

    pub fn with_cs(mut self, cs: impl PeripheralOutput<'d>) -> Self {

        let info = self.spi.info();

        self

    }

    #[doc_replace(

        "max_frequency" => {

            cfg(esp32h2) => "48MHz",

            _ => "80MHz",

        }

    )]

    /// Changes the bus configuration.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?;

    ///

    /// spi.apply_config(&Config::default().with_frequency(Rate::from_khz(100)));

    /// #

    /// # {after_snippet}

    /// ```

    ///

    /// # Errors

    ///

    /// [`ConfigError::FrequencyOutOfRange`] when frequency passed in config exceeds

    /// __max_frequency__ or is below 70 kHz.

    pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {

    }

    #[procmacros::doc_replace]

    /// Writes bytes to SPI. After writing, flush is called to ensure all data

    /// has been transmitted.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2)

    ///     .into_async();

    ///

    /// let buffer = [0; 10];

    /// spi.write(&buffer)?;

    ///

    /// # {after_snippet}

    /// ```

    pub fn write(&mut self, words: &[u8]) -> Result<(), Error> {

        let _clock = SpiClockGuard::new(self.spi.info());

        self.driver().setup_full_duplex()?;

        self.driver().write(words)

    }

    #[procmacros::doc_replace]

    /// Reads bytes from SPI. The provided slice is filled with data received

    /// from the slave.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2)

    ///     .into_async();

    ///

    /// let mut buffer = [0; 10];

    /// spi.read(&mut buffer)?;

    ///

    /// # {after_snippet}

    /// ```

    pub fn read(&mut self, words: &mut [u8]) -> Result<(), Error> {

        let _clock = SpiClockGuard::new(self.spi.info());

        self.driver().setup_full_duplex()?;

        self.driver().read(words)

    }

    #[procmacros::doc_replace]

    /// Sends `words` to the slave. The received data will be written to

    /// `words`, overwriting its contents.

    ///

    /// # Examples

    ///

    /// ```rust, no_run

    /// # {before_snippet}

    /// use esp_hal::spi::{

    ///     Mode,

    ///     master::{Config, Spi},

    /// };

    /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?

    ///     .with_sck(peripherals.GPIO0)

    ///     .with_mosi(peripherals.GPIO1)

    ///     .with_miso(peripherals.GPIO2)

    ///     .into_async();

    ///

    /// let mut buffer = [0; 10];

    /// spi.transfer(&mut buffer)?;

    ///

    /// # {after_snippet}

    /// ```

    pub fn transfer(&mut self, words: &mut [u8]) -> Result<(), Error> {

    }

    /// Half-duplex read.

    ///

    /// Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across

    /// chunks, but the clock pauses while the CPU prepares each subsequent chunk.

    ///

    /// # Errors

    ///

    /// [`Error::Unsupported`] when the buffer is empty (currently unsupported).

    /// `DataMode::Single` cannot be combined with any other [`DataMode`], otherwise

    /// [`Error::Unsupported`].

    #[instability::unstable]

    pub fn half_duplex_read(

        &mut self,

        data_mode: DataMode,

        cmd: Command,

        address: Address,

        dummy: u8,

        buffer: &mut [u8],

    ) -> Result<(), Error> {

        self.driver()

    }

    /// Half-duplex write.

    ///

    /// Transfers larger than the hardware FIFO are split into chunks. CS remains asserted across

    /// chunks, but the clock pauses while the CPU prepares each subsequent chunk.

    ///

    /// # Errors

    ///

    /// [`Error::Unsupported`] for unsupported combinations of command, address,

    /// dummy, and data modes.