#[cfg(dma_can_access_psram)]

use core::{mem::MaybeUninit, ops::Range};

use core::{

    ops::{Deref, DerefMut},

    ptr::{NonNull, null_mut},

};

use super::*;

#[cfg(dma_can_access_psram)]

use crate::soc::{is_slice_in_psram, is_valid_psram_address, is_valid_ram_address};

use crate::{

    dma::aligned::{DmaAlignedMut, InternalMemory},

    soc::is_slice_in_dram,

};

pub(crate) mod scoped;

pub(crate) use scoped::*;

/// Error returned from Dma[Rx|Tx|RxTx]Buf operations.

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

pub enum DmaBufError {

    /// The buffer is smaller than the requested size.

    BufferTooSmall,

    /// More descriptors are needed for the buffer size.

    InsufficientDescriptors,

    /// Descriptors or buffers are not located in a supported memory region.

    UnsupportedMemoryRegion,

    /// Buffer address or size is not properly aligned.

    /// Invalid chunk size: must be > 0 and <= 4095.

    InvalidChunkSize,

}

impl core::fmt::Display for DmaBufError {

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

        match self {

            DmaBufError::BufferTooSmall => {

                write!(f, "The buffer is smaller than the requested size")

            }

            DmaBufError::InsufficientDescriptors => {

                write!(f, "More descriptors are needed for the buffer size")

            }

            DmaBufError::UnsupportedMemoryRegion => write!(

                f,

                "Descriptors or buffers are not located in a supported memory region"

            ),

            DmaBufError::InvalidAlignment(x) => write!(f, "{x}"),

            DmaBufError::InvalidChunkSize => {

                write!(f, "Invalid chunk size: must be > 0 and <= 4095")

            }

        }

    }

}

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

/// DMA buffer alignment errors.

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

pub enum DmaAlignmentError {

    /// Buffer address is not properly aligned.

    Address,

    /// Buffer size is not properly aligned.

    Size,

}

impl From<DmaAlignmentError> for DmaBufError {

    fn from(err: DmaAlignmentError) -> Self {

        DmaBufError::InvalidAlignment(err)

    }

}

impl core::fmt::Display for DmaAlignmentError {

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

        match self {

            DmaAlignmentError::Address => write!(f, "Buffer address is not properly aligned"),

            DmaAlignmentError::Size => write!(f, "Buffer size is not properly aligned"),

        }

    }

}

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

cfg_select! {

    dma_can_access_psram => {

        /// Burst size used when transferring to and from external memory.

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

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

        pub enum ExternalBurstConfig {

            /// 16 bytes

            Size16 = 16,

            /// 32 bytes

            Size32 = 32,

            /// 64 bytes

            // TODO: investigate why ext_mem_bk_size = 2 causes corruption on S2

            #[cfg(not(esp32s2))]

            Size64 = 64,

        }

        impl ExternalBurstConfig {

            /// The default external memory burst length.

            pub const DEFAULT: Self = Self::Size16;

        }

        impl Default for ExternalBurstConfig {

            fn default() -> Self {

                Self::DEFAULT

            }

        }

        /// Internal memory access burst mode.

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

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

        pub enum InternalBurstConfig {

            /// Burst mode is disabled.

            Disabled,

            /// Burst mode is enabled.

            Enabled,

        }

        impl InternalBurstConfig {

            /// The default internal burst mode configuration.

            pub const DEFAULT: Self = Self::Disabled;

        }

        impl Default for InternalBurstConfig {

            fn default() -> Self {

                Self::DEFAULT

            }

        }

        /// Burst transfer configuration.

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

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

        pub struct BurstConfig {

            /// Configures the burst size for PSRAM transfers.

            ///

            /// Burst mode is always enabled for PSRAM transfers.

            pub external_memory: ExternalBurstConfig,

            /// Enables or disables the burst mode for internal memory transfers.

            ///

            /// The burst size is not configurable.

            pub internal_memory: InternalBurstConfig,

        }

        impl BurstConfig {

            /// The default burst mode configuration.

            pub const DEFAULT: Self = Self {

                external_memory: ExternalBurstConfig::DEFAULT,

                internal_memory: InternalBurstConfig::DEFAULT,

            };

        }

        impl Default for BurstConfig {

            fn default() -> Self {

                Self::DEFAULT

            }

        }

        impl From<InternalBurstConfig> for BurstConfig {

            fn from(internal_memory: InternalBurstConfig) -> Self {

                Self {

                    external_memory: ExternalBurstConfig::DEFAULT,

                    internal_memory,

                }

            }

        }

        impl From<ExternalBurstConfig> for BurstConfig {

            fn from(external_memory: ExternalBurstConfig) -> Self {

                Self {

                    external_memory,

                    internal_memory: InternalBurstConfig::DEFAULT,

                }

            }

        }

    }

    _ => {

        /// Burst transfer configuration.

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

        pub enum BurstConfig {

            /// Burst mode is disabled.

            Disabled,

            /// Burst mode is enabled.

            Enabled,

        }

        impl BurstConfig {

            /// The default burst mode configuration.

            pub const DEFAULT: Self = Self::Disabled;

        }

        impl Default for BurstConfig {

            fn default() -> Self {

                Self::DEFAULT

            }

        }

        type InternalBurstConfig = BurstConfig;

    }

}

#[cfg(dma_can_access_psram)]

impl ExternalBurstConfig {

    const fn min_psram_alignment(self, direction: TransferDirection) -> usize {

        // S2 TRM: Specifically, size and buffer address pointer in receive descriptors

        // should be 16-byte, 32-byte or 64-byte aligned. For data frame whose

        // length is not a multiple of 16 bytes, 32 bytes, or 64 bytes, EDMA adds

        // padding bytes to the end.

        // S3 TRM: Size and Address for IN transfers must be block aligned. For receive

        // descriptors, if the data length received are not aligned with block size,

        // GDMA will pad the data received with 0 until they are aligned to

        // initiate burst transfer. You can read the length field in receive descriptors

        // to obtain the length of valid data received

        if matches!(direction, TransferDirection::In) {

            self as usize

        } else {

            // S2 TRM: Size, length and buffer address pointer in transmit descriptors are

            // not necessarily aligned with block size.

            // S3 TRM: Size, length, and buffer address pointer in transmit descriptors do

            // not need to be aligned.

            1

        }

    }

}

impl InternalBurstConfig {

    pub(super) const fn is_burst_enabled(self) -> bool {

        !matches!(self, Self::Disabled)

    }

    // Size and address alignment as those come in pairs on current hardware.

    const fn min_dram_alignment(self, direction: TransferDirection) -> usize {

            if cfg!(esp32) {

                // NOTE: The size must be word-aligned.

                // NOTE: The buffer address must be word-aligned

                4

                // As described in "Accessing Internal Memory" paragraphs in the various TRMs.

                4

            } else {

                1

            }

        } else {

            // OUT transfers have no alignment requirements, except for ESP32, which is

            // described below.

            if cfg!(esp32) {

                // SPI DMA: Burst transmission is supported. The data size for

                // a single transfer must be four bytes aligned.

                // I2S DMA: Burst transfer is supported. However, unlike the

                // SPI DMA channels, the data size for a single transfer is

                // one word, or four bytes.

                4

            } else {

                1

            }

        }

    }

}

const fn max(a: usize, b: usize) -> usize {

    if a > b { a } else { b }

}

impl BurstConfig {

    delegate::delegate! {

        to self.internal_memory {

            #[cfg(dma_can_access_psram)]

            pub(super) const fn min_dram_alignment(self, direction: TransferDirection) -> usize;

            #[cfg(all(dma_can_access_psram, not(esp32s31)))] // Burst always enabled

            pub(super) fn is_burst_enabled(self) -> bool;

        }

    }

    /// Calculates an alignment that is compatible with the current burst

    /// configuration.

    ///

    /// This is an over-estimation so that Descriptors can be safely used with

    /// any DMA channel in any direction.

    pub const fn min_compatible_alignment(self) -> usize {

        let in_alignment = self.min_dram_alignment(TransferDirection::In);

        let out_alignment = self.min_dram_alignment(TransferDirection::Out);

        let alignment = max(in_alignment, out_alignment);

        #[cfg(dma_can_access_psram)]

        let alignment = max(alignment, self.external_memory as usize);

        alignment

    }

    const fn chunk_size_for_alignment(alignment: usize) -> usize {

        // DMA descriptors have a 12-bit field for the size/length of the buffer they

        // point at. As there is no such thing as 0-byte alignment, this means the

        // maximum size is 4095 bytes.

        4096 - alignment

    }

    /// Calculates a chunk size that is compatible with the current burst

    /// configuration's alignment requirements.

    ///

    /// This is an over-estimation so that Descriptors can be safely used with

    /// any DMA channel in any direction.

    pub const fn max_compatible_chunk_size(self) -> usize {

        Self::chunk_size_for_alignment(self.min_compatible_alignment())

    }

    fn min_alignment(self, _buffer: &[u8], direction: TransferDirection) -> usize {

        let alignment = self.min_dram_alignment(direction);

        cfg_select! {

            dma_can_access_psram => {

                let mut alignment = alignment;

                if is_valid_psram_address(_buffer.as_ptr() as usize) {

                    alignment = max(

                        alignment,

                        self.external_memory.min_psram_alignment(direction),

                    );

                }

            }

            _ => {}

        }

        alignment

    }

    // Note: this function ignores address alignment as we assume the buffers are

    // aligned.

    fn max_chunk_size_for(self, buffer: &[u8], direction: TransferDirection) -> usize {

        Self::chunk_size_for_alignment(self.min_alignment(buffer, direction))

    }

    fn ensure_buffer_aligned(

        self,

        buffer: &[u8],

        direction: TransferDirection,

    ) -> Result<(), DmaAlignmentError> {

        let alignment = self.min_alignment(buffer, direction);

            return Err(DmaAlignmentError::Address);

        }

        // NB: the TRMs suggest that buffer length don't need to be aligned, but

        // for IN transfers, we configure the DMA descriptors' size field, which needs

        // to be aligned.

        if direction == TransferDirection::In && !buffer.len().is_multiple_of(alignment) {

            return Err(DmaAlignmentError::Size);

        }

        Ok(())

    }

    fn ensure_buffer_compatible(

        self,

        buffer: &[u8],

        direction: TransferDirection,

    ) -> Result<(), DmaBufError> {

            return Ok(());

        }

        // buffer can be either DRAM or PSRAM (if supported)

        let is_in_dram = is_slice_in_dram(buffer);

        cfg_select! {

            dma_can_access_psram => {

                let is_in_psram = is_slice_in_psram(buffer);

            }

            _ => {

                let is_in_psram = false;

            }

        }

            return Err(DmaBufError::UnsupportedMemoryRegion);

        }

        self.ensure_buffer_aligned(buffer, direction)?;

        Ok(())

    }

}

/// The direction of the DMA transfer.

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

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

pub enum TransferDirection {

    /// DMA transfer from peripheral or external memory to memory.

    In,

    /// DMA transfer from memory to peripheral or external memory.

    Out,

}

/// Holds all the information needed to configure a DMA channel for a transfer.

#[derive(PartialEq, Eq, Debug)]

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

pub struct Preparation {

    /// The descriptor the DMA will start from.

    pub start: *mut DmaDescriptor,

    /// Must be `true` if any of the DMA descriptors contain data in PSRAM.

    #[cfg(dma_can_access_psram)]

    pub accesses_psram: bool,

    /// Configures the DMA to transfer data in bursts.

    ///

    /// The implementation of the buffer must ensure that buffer size

    /// and alignment in each descriptor is compatible with the burst

    /// transfer configuration.

    ///

    /// For details on alignment requirements, refer to the chip's

    #[doc = crate::trm_markdown_link!()]

    pub burst_transfer: BurstConfig,

    /// Configures the "check owner" feature of the DMA channel.

    ///

    /// Most DMA channels allow software to configure whether the hardware

    /// checks that [DmaDescriptor::owner] is set to [Owner::Dma] before

    /// consuming the descriptor. If this check fails, the channel stops

    /// operating and fires

    /// [DmaRxInterrupt::DescriptorError]/[DmaTxInterrupt::DescriptorError].

    ///

    /// This field allows buffer implementation to configure this behavior.

    /// - `Some(true)`: DMA channel must check the owner bit.

    /// - `Some(false)`: DMA channel must NOT check the owner bit.

    /// - `None`: DMA channel should check the owner bit if it is supported.

    ///

    /// Some buffer implementations may require that the DMA channel performs

    /// this check before consuming the descriptor to ensure correct

    /// behavior. e.g. To prevent wrap-around in a circular transfer.

    ///

    /// Some buffer implementations may require that the DMA channel does NOT

    /// perform this check as the ownership bit will not be set before the

    /// channel tries to consume the descriptor.

    ///

    /// Most implementations do not have any such requirements and work

    /// correctly regardless of whether the DMA channel checks or not.

    ///

    /// If the DMA channel does not support the provided option, preparation

    /// fails.

    pub check_owner: Option<bool>,

    /// Configures whether the DMA channel automatically clears the

    /// [DmaDescriptor::owner] bit after it is done with the buffer pointed

    /// to by a descriptor.

    ///

    /// For RX transfers, this is always true and the value specified here is

    /// ignored.

    ///

    /// SPI_DMA on the ESP32 does not support this and panics if set

    /// to true.

    pub auto_write_back: bool,

}

/// [`DmaTxBuffer`] is a DMA descriptor + memory combo that can be used for

/// transmitting data from a DMA channel to a peripheral's FIFO.

///

/// # Safety

///

/// The implementing type must keep all its descriptors and the buffers they

/// point to valid while the buffer is being transferred.

pub unsafe trait DmaTxBuffer {

    /// A type providing operations that are safe to perform on the buffer

    /// while the DMA is actively using it.

    type View;

    /// The type returned when a transfer finishes.

    ///

    /// Some buffers do not need to be reconstructed.

    type Final;

    /// Prepares the buffer for an imminent transfer and returns

    /// information required to use this buffer.

    ///

    /// This operation is idempotent.

    fn prepare(&mut self) -> Preparation;

    /// This is called before the DMA starts using the buffer.

    fn into_view(self) -> Self::View;

    /// This is called after the DMA is done using the buffer.

    fn from_view(view: Self::View) -> Self::Final;

}

/// [`DmaRxBuffer`] is a DMA descriptor + memory combo that can be used for

/// receiving data from a peripheral's FIFO to a DMA channel.

///

/// Implementations of this trait may only support having a single EOF bit

/// which resides in the last descriptor. There will be a separate trait in

/// future to support multiple EOFs.

///

/// # Safety

///

/// The implementing type must keep all its descriptors and the buffers they

/// point to valid while the buffer is being transferred.

pub unsafe trait DmaRxBuffer {

    /// A type providing operations that are safe to perform on the buffer

    /// while the DMA is actively using it.

    type View;

    /// The type returned when a transfer finishes.

    ///

    /// Some buffers do not need to be reconstructed.

    type Final;

    /// Prepares the buffer for an imminent transfer and returns

    /// information required to use this buffer.

    ///

    /// This operation is idempotent.

    fn prepare(&mut self) -> Preparation;

    /// This is called before the DMA starts using the buffer.

    fn into_view(self) -> Self::View;

    /// This is called after the DMA is done using the buffer.

    fn from_view(view: Self::View) -> Self::Final;

}

/// An in-progress view into [`DmaRxBuf`]/[`DmaTxBuf`].

///

/// In the future, this could support peeking into state of the

/// descriptors/buffers.

pub struct BufView<T>(T);

/// DMA transmit buffer

///

/// This is a contiguous buffer linked together by DMA descriptors of length

/// 4095 at most. It can only be used for transmitting data to a peripheral's

/// FIFO. See [`DmaRxBuf`] for receiving data.

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

impl DmaTxBuf {

    /// Creates a new [`DmaTxBuf`] from some descriptors and a buffer.

        descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        buffer: DmaAlignedMut<'static, [u8]>,

    ) -> Result<Self, DmaBufError> {

        ScopedDmaTxBuf::new(descriptors, buffer).map(Self)

    /// Creates a new [`DmaTxBuf`] from some descriptors and a buffer.

    ///

    /// There must be enough descriptors for the provided buffer.

    /// Depending on alignment requirements, each descriptor can handle at most

    /// 4095 bytes worth of buffer.

    ///

    /// Both the descriptors and buffer must be in DMA-capable memory.

    /// Only DRAM is supported for descriptors.

    pub fn new_with_config(

        descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        buffer: DmaAlignedMut<'static, [u8]>,

        config: impl Into<BurstConfig>,

    ) -> Result<Self, DmaBufError> {

        ScopedDmaTxBuf::new_with_config(descriptors, buffer, config).map(Self)

    }

    /// Configures the DMA to use burst transfers to access this buffer.

    pub fn set_burst_config(&mut self, burst: BurstConfig) -> Result<(), DmaBufError> {

        self.0.set_burst_config(burst)

    }

    /// Consumes the buf, returning the descriptors and buffer.

    pub fn split(

        self,

    ) -> (

        DmaAlignedMut<'static, [DmaDescriptor]>,

        DmaAlignedMut<'static, [u8]>,

    ) {

        self.0.split()

    }

    /// Returns the size of the underlying buffer.

    pub fn capacity(&self) -> usize {

        self.0.capacity()

    }

    /// Returns the number of bytes that would be transmitted by this buf.

    #[allow(clippy::len_without_is_empty)]

    /// Resets the descriptors to only transmit `len` amount of bytes from this

    /// buf.

    ///

    /// The number of bytes in data must be less than or equal to the buffer

    /// size.

        self.0.set_length(len);

    /// Fills the TX buffer with the bytes provided in `data` and reset the

    /// descriptors to only cover the filled section.

    ///

    /// The number of bytes in data must be less than or equal to the buffer

    /// size.

        self.0.fill(data);

    }

    /// Returns the buf as a mutable slice that can be written.

    pub fn as_mut_slice(&mut self) -> &mut [u8] {

        self.0.as_mut_slice()

    }

    /// Returns the buf as a slice that can be read.

    pub fn as_slice(&self) -> &[u8] {

        self.0.as_slice()

    }

    /// Consumes the buffer and returns the scoped version.

    pub(crate) fn into_scoped(self) -> ScopedDmaTxBuf<'static> {

        self.0

    }

}

unsafe impl DmaTxBuffer for DmaTxBuf {

    type View = BufView<DmaTxBuf>;

    type Final = DmaTxBuf;

    fn prepare(&mut self) -> Preparation {

        self.0.prepare()

    }

    fn into_view(self) -> BufView<DmaTxBuf> {

        BufView(self)

    }

    fn from_view(view: Self::View) -> Self {

        view.0

    }

}

/// DMA receive buffer

///

/// This is a contiguous buffer linked together by DMA descriptors of length

/// 4092. It can only be used for receiving data from a peripheral's FIFO.

/// See [`DmaTxBuf`] for transmitting data.

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

impl DmaRxBuf {

    /// Creates a new [`DmaRxBuf`] from some descriptors and a buffer.

        descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        buffer: DmaAlignedMut<'static, [u8]>,

    ) -> Result<Self, DmaBufError> {

        ScopedDmaRxBuf::new(descriptors, buffer).map(Self)

    /// Creates a new [`DmaRxBuf`] from some descriptors and a buffer.

    ///

    /// There must be enough descriptors for the provided buffer.

    /// Depending on alignment requirements, each descriptor can handle at most

    /// 4092 bytes worth of buffer.

    ///

    /// Both the descriptors and buffer must be in DMA-capable memory.

    /// Only DRAM is supported for descriptors.

    pub fn new_with_config(

        descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        buffer: DmaAlignedMut<'static, [u8]>,

        config: impl Into<BurstConfig>,

    ) -> Result<Self, DmaBufError> {

        ScopedDmaRxBuf::new_with_config(descriptors, buffer, config).map(Self)

    }

    /// Configures the DMA to use burst transfers to access this buffer.

    pub fn set_burst_config(&mut self, burst: BurstConfig) -> Result<(), DmaBufError> {

        self.0.set_burst_config(burst)

    }

    /// Consumes the buf, returning the descriptors and buffer.

    pub fn split(

        self,

    ) -> (

        DmaAlignedMut<'static, [DmaDescriptor]>,

        DmaAlignedMut<'static, [u8]>,

    ) {

        self.0.split()

    }

    /// Returns the size of the underlying buffer.

    pub fn capacity(&self) -> usize {

        self.0.capacity()

    }

    /// Returns the maximum number of bytes that this buf has been configured to

    /// receive.

    #[allow(clippy::len_without_is_empty)]

    /// Resets the descriptors to only receive `len` amount of bytes into this

    /// buf.

    ///

    /// The number of bytes in data must be less than or equal to the buffer

    /// size.

        self.0.set_length(len)

    /// Returns the entire underlying buffer as a slice that can be read.

    pub fn as_slice(&self) -> &[u8] {

        self.0.as_slice()

    }

    /// Returns the entire underlying buffer as a slice that can be written.

    pub fn as_mut_slice(&mut self) -> &mut [u8] {

        self.0.as_mut_slice()

    }

    /// Returns the number of bytes that was received by this buf.

    pub fn number_of_received_bytes(&self) -> usize {

        self.0.number_of_received_bytes()

    }

    /// Reads the received data into the provided `buf`.

    ///

    /// If `buf.len()` is less than the amount of received data then only the

    /// first `buf.len()` bytes of received data is written into `buf`.

    ///

    /// Returns the number of bytes written to `buf`.

    /// Returns the received data as an iterator of slices.

    pub fn received_data(&self) -> impl Iterator<Item = &[u8]> {

        self.0.received_data()

    }

    /// Consumes the buffer and returns the scoped version.

    pub(crate) fn into_scoped(self) -> ScopedDmaRxBuf<'static> {

        self.0

    }

}

unsafe impl DmaRxBuffer for DmaRxBuf {

    type View = BufView<DmaRxBuf>;

    type Final = DmaRxBuf;

        self.0.prepare()

    fn into_view(self) -> BufView<DmaRxBuf> {

        BufView(self)

    }

    fn from_view(view: Self::View) -> Self {

        view.0

    }

}

/// DMA transmit and receive buffer.

///

/// This is a (single) contiguous buffer linked together by two sets of DMA

/// descriptors of length 4092 each.

/// It can be used for simultaneously transmitting to and receiving from a

/// peripheral's FIFO. These are typically full-duplex transfers.

#[derive(Debug)]

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

pub struct DmaRxTxBuf {

    rx_descriptors: DescriptorSet<'static>,

    tx_descriptors: DescriptorSet<'static>,

    buffer: DmaAlignedMut<'static, [u8]>,

    burst: BurstConfig,

}

impl DmaRxTxBuf {

    /// Creates a new [DmaRxTxBuf] from some descriptors and a buffer.

    pub fn new(

        rx_descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        tx_descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        buffer: DmaAlignedMut<'static, [u8]>,

    ) -> Result<Self, DmaBufError> {

        let mut buf = Self {

            rx_descriptors: DescriptorSet::new(rx_descriptors)?,

            tx_descriptors: DescriptorSet::new(tx_descriptors)?,

            buffer,

            burst: BurstConfig::default(),

        };

        let capacity = buf.capacity();

        buf.configure(buf.burst, capacity)?;

        Ok(buf)

    }

    fn configure(

        &mut self,

        burst: impl Into<BurstConfig>,

        length: usize,

    ) -> Result<(), DmaBufError> {

        let burst = burst.into();

        self.set_length_fallible(length, burst)?;

        let max_chunk_size_in = burst.max_chunk_size_for(&self.buffer, TransferDirection::In);

        let max_chunk_size_out = burst.max_chunk_size_for(&self.buffer, TransferDirection::Out);

        self.rx_descriptors

            .link_with_buffer(&mut self.buffer, max_chunk_size_in)?;

        self.tx_descriptors

            .link_with_buffer(&mut self.buffer, max_chunk_size_out)?;

        self.burst = burst;

        Ok(())

    }

    /// Configures the DMA to use burst transfers to access this buffer.

    pub fn set_burst_config(&mut self, burst: BurstConfig) -> Result<(), DmaBufError> {

        let len = self.len();

        self.configure(burst, len)

    }

    /// Consumes the buf, returning the rx descriptors, tx descriptors and

    /// buffer.

    #[allow(clippy::type_complexity)]

    pub fn split(

        self,

    ) -> (

        DmaAlignedMut<'static, [DmaDescriptor]>,

        DmaAlignedMut<'static, [DmaDescriptor]>,

        DmaAlignedMut<'static, [u8]>,

    ) {

        (

            self.rx_descriptors.into_inner(),

            self.tx_descriptors.into_inner(),

            self.buffer,

        )

    }

    /// Returns the size of the underlying buffer.

    pub fn capacity(&self) -> usize {

        self.buffer.len()

    }

    /// Returns the number of bytes that would be transmitted by this buf.

    #[allow(clippy::len_without_is_empty)]

    pub fn len(&self) -> usize {

        self.tx_descriptors

            .linked_iter()

            .map(|d| d.len())

            .sum::<usize>()

    }

    /// Returns the entire buf as a slice that can be read.

    pub fn as_slice(&self) -> &[u8] {

        &self.buffer

    }

    /// Returns the entire buf as a slice that can be written.

    pub fn as_mut_slice(&mut self) -> &mut [u8] {

        &mut self.buffer

    }

    fn set_length_fallible(&mut self, len: usize, burst: BurstConfig) -> Result<(), DmaBufError> {

        if len > self.capacity() {

            return Err(DmaBufError::BufferTooSmall);

        }

        burst.ensure_buffer_compatible(&self.buffer[..len], TransferDirection::In)?;

        burst.ensure_buffer_compatible(&self.buffer[..len], TransferDirection::Out)?;

        let max_chunk_size_in = burst.max_chunk_size_for(&self.buffer, TransferDirection::In);

        let max_chunk_size_out = burst.max_chunk_size_for(&self.buffer, TransferDirection::Out);

        self.rx_descriptors.set_rx_length(len, max_chunk_size_in)?;

        self.tx_descriptors.set_tx_length(len, max_chunk_size_out)?;

        Ok(())

    }

    /// Resets the descriptors to only transmit/receive `len` amount of bytes

    /// with this buf.

    ///

    /// `len` must be less than or equal to the buffer size.

    pub fn set_length(&mut self, len: usize) {

        unwrap!(self.set_length_fallible(len, self.burst));

    }

}

unsafe impl DmaTxBuffer for DmaRxTxBuf {

    type View = BufView<DmaRxTxBuf>;

    type Final = DmaRxTxBuf;

    fn prepare(&mut self) -> Preparation {

        for desc in self.tx_descriptors.linked_iter_mut() {

            // In non-circular mode, we only set `suc_eof` for the last descriptor to signal

            // the end of the transfer.

            desc.reset_for_tx(desc.next.is_null());

        }

        #[cfg(dma_can_access_psram)]

        let is_data_in_psram = !is_valid_ram_address(self.buffer.as_ptr() as usize);

        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

        self.buffer.writeback();

        Preparation {

            start: self.tx_descriptors.head(),

            #[cfg(dma_can_access_psram)]

            accesses_psram: is_data_in_psram,

            burst_transfer: self.burst,

            check_owner: None,

            auto_write_back: false,

        }

    }

    fn into_view(self) -> BufView<DmaRxTxBuf> {

        BufView(self)

    }

    fn from_view(view: Self::View) -> Self {

        view.0

    }

}

unsafe impl DmaRxBuffer for DmaRxTxBuf {

    type View = BufView<DmaRxTxBuf>;

    type Final = DmaRxTxBuf;

    fn prepare(&mut self) -> Preparation {

        for desc in self.rx_descriptors.linked_iter_mut() {

            desc.reset_for_rx();

        }

        cfg_select! {

            dma_can_access_psram => {

                // Optimization: avoid locking for PSRAM range.

                let is_data_in_psram = !is_valid_ram_address(self.buffer.as_ptr() as usize);

                if is_data_in_psram || cfg!(soc_internal_memory_cached) {

                    unsafe {

                        crate::soc::cache_invalidate_addr(

                            self.buffer.as_ptr() as u32,

                            self.buffer.len() as u32,

                        )

                    };

                }

            }

            _ => {}

        }

        Preparation {

            start: self.rx_descriptors.head(),

            #[cfg(dma_can_access_psram)]

            accesses_psram: is_data_in_psram,

            burst_transfer: self.burst,

            check_owner: None,

            auto_write_back: true,

        }

    }

    fn into_view(self) -> BufView<DmaRxTxBuf> {

        BufView(self)

    }

    fn from_view(view: Self::View) -> Self {

        view.0

    }

}

/// DMA Streaming Receive Buffer.

///

/// This is a contiguous buffer linked together by DMA descriptors, and the

/// buffer is evenly distributed between each descriptor provided.

///

/// It is used for continuously streaming data from a peripheral's FIFO.

///

/// It maintains a sliding window of descriptors that progresses when

/// [DmaRxStreamBufView::consume] is called.

///

/// The list starts out like so `A (empty) -> B (empty) -> C (empty) -> D

/// (empty) -> NULL`.

///

/// As the DMA writes to the buffers the list progresses like so:

/// - `A (empty) -> B (empty) -> C (empty) -> D (empty) -> NULL`

/// - `A (full)  -> B (empty) -> C (empty) -> D (empty) -> NULL`

/// - `A (full)  -> B (full)  -> C (empty) -> D (empty) -> NULL`

/// - `A (full)  -> B (full)  -> C (full)  -> D (empty) -> NULL`

///

/// As [DmaRxStreamBufView::consume] is called, the list (approximately)

/// progresses like so:

/// - `A (full)  -> B (full)  -> C (full)  -> D (empty) -> NULL`

/// - `B (full)  -> C (full)  -> D (empty) -> A (empty) -> NULL`

/// - `C (full)  -> D (empty) -> A (empty) -> B (empty) -> NULL`

/// - `D (empty) -> A (empty) -> B (empty) -> C (empty) -> NULL`

///

/// If all the descriptors fill up, the [DmaRxInterrupt::DescriptorEmpty]

/// interrupt fires and the DMA stops writing. The transfer must then be resumed

/// or restarted.

///

/// This buffer does not indicate when this condition occurs. Check with the

/// driver to see if the DMA has stopped.

///

/// When constructing this buffer, tune the ratio between the chunk size and

/// buffer size appropriately. Smaller chunk sizes mean data is received more

/// frequently, but the DMA interrupts ([DmaRxInterrupt::Done]) also fire more

/// frequently when they are used.

///

/// See [DmaRxStreamBufView] for APIs available while a transfer is in

/// progress.

#[derive(Debug)]

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

pub struct DmaRxStreamBuf {

    descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

    buffer: DmaAlignedMut<'static, [u8]>,

    burst: BurstConfig,

}

impl DmaRxStreamBuf {

    /// Creates a new [`DmaRxStreamBuf`] evenly distributing the buffer between

    /// the provided descriptors.

        mut descriptors: DmaAlignedMut<'static, [DmaDescriptor]>,

        mut buffer: DmaAlignedMut<'static, [u8]>,

    ) -> Result<Self, DmaBufError> {

        // see https://github.com/esp-rs/esp-hal/issues/2269#issuecomment-4397953660

        // we can lift that requirement once we sort out this issue

            return Err(DmaBufError::InsufficientDescriptors);

        }

        // Evenly distribute the buffer between the descriptors.

            .ok_or(DmaBufError::InsufficientDescriptors)?;

        let mut chunks = buffer.chunks_exact_mut(chunk_size);

        for (desc, chunk) in descriptors.iter_mut().zip(chunks.by_ref()) {

            desc.set_size(chunk.len());

        }

        let remainder = chunks.into_remainder();

            // Append any excess to the last descriptor.

            let last_descriptor = descriptors.last_mut().unwrap();

                return Err(DmaBufError::InsufficientDescriptors);

            }

            last_descriptor.set_size(size);

        }

            descriptors,

            buffer,

            burst: BurstConfig::default(),

        })

    /// Consumes the buf, returning the descriptors and buffer.

    pub fn split(

        self,

    ) -> (

        DmaAlignedMut<'static, [DmaDescriptor]>,

        DmaAlignedMut<'static, [u8]>,

    ) {

        (self.descriptors, self.buffer)

    }

}

unsafe impl DmaRxBuffer for DmaRxStreamBuf {

    type View = DmaRxStreamBufView;

    type Final = DmaRxStreamBuf;

        // Link up all the descriptors (but not in a circle).

        let mut next = null_mut();

            next = desc;

            desc.reset_for_rx();

        }

        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

        self.descriptors.writeback();

            start: self.descriptors.as_mut_ptr(),

            #[cfg(dma_can_access_psram)]

            accesses_psram: false,

            // Whilst we give ownership of the descriptors the DMA, the correctness of this buffer

            // implementation doesn't rely on the DMA checking for descriptor ownership.

            // No descriptor is added back to the end of the stream before it's ready for the DMA

            // to consume it.

            check_owner: None,

            auto_write_back: true,

        }

    fn into_view(self) -> DmaRxStreamBufView {

        DmaRxStreamBufView {

            buf: self,

            descriptor_idx: 0,

            descriptor_offset: 0,

        }

    }

    fn from_view(view: Self::View) -> Self {

    }

}

/// A view into a [DmaRxStreamBuf].

pub struct DmaRxStreamBufView {

    buf: DmaRxStreamBuf,

    descriptor_idx: usize,

    descriptor_offset: usize,

}

impl DmaRxStreamBufView {

    /// Returns the number of bytes that are available to read from the buf.

        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

        self.buf.descriptors.invalidate();

        let mut result = 0;

                break;

            }

        }

    /// Reads as much as possible into the buf from the available data.

            return 0;

        }

        let total_bytes = buf.len();

        let mut remaining = buf;

        loop {

            let available = self.peek();

                break;

            }

                remaining.copy_from_slice(&available[0..remaining.len()]);

                let consumed = remaining.len();

                remaining = &mut remaining[consumed..];

                break;

            } else {

                let to_consume = available.len();

                remaining[0..to_consume].copy_from_slice(available);

                remaining = &mut remaining[to_consume..];

            }

        }

    /// Returns a slice into the buffer containing available data.

    /// This will be the longest possible contiguous slice into the buffer that

    /// contains data that is available to read.

    ///

    /// Ignores EOFs. See [Self::peek_until_eof] for EOF support.

        slice

    /// Same as [Self::peek] but will not skip over any EOFs.

    ///

    /// It also returns a boolean indicating whether this slice ends with an EOF

    /// or not.

    /// Consumes the first `n` bytes from the available data, returning any

    /// fully consumed descriptors back to the DMA.

    /// This is typically called after [Self::peek]/[Self::peek_until_eof].

    ///

    /// Returns the number of bytes that were actually consumed.

        let mut remaining_bytes_to_consume = n;

        let mut descriptors_modified = false;

        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

        self.buf.descriptors.invalidate();

        loop {

                // Descriptor is still owned by DMA so it can't be read yet.

                // This should only happen when there is no more data available to read.

                break;

            }

                remaining_bytes_to_consume = 0;

                break;

            }

            // Reset the descriptor for reuse.

            desc.set_owner(Owner::Dma);

            desc.set_suc_eof(false);

            desc.set_length(0);

            // Before connecting this descriptor to the end of the list, the next descriptor

            // must be disconnected from this one to prevent the DMA from

            // overtaking.

            let desc_ptr: *mut _ = desc;

            let prev_descriptor_index = self

                .descriptor_idx

                .checked_sub(1)

                .unwrap_or(self.buf.descriptors.len() - 1);

            // Connect this consumed descriptor to the end of the chain.

            descriptors_modified = true;

                self.descriptor_idx = 0;

            }

        }

        if descriptors_modified {

            #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

            self.buf.descriptors.writeback();

        }

        #[cfg(any(soc_internal_memory_cached, dma_can_access_psram))]

        self.buf.descriptors.invalidate();

        // There must be at least one descriptor.

        if descriptors.len() == 1 {

            let last_descriptor = &descriptors[0];

                // No data available.

            } else {

                let chunk_size = last_descriptor.size();

                #[cfg(soc_internal_memory_cached)]

                if length != 0 {

                    unsafe {

                        crate::soc::cache_invalidate_addr(

                            self.buf.buffer.as_ptr().add(buffer_start) as u32,

                            length as u32,

                        );

                    }

                }

                    &self.buf.buffer[buffer_start..][..length],

                    last_descriptor.flags.suc_eof(),

                )

            }

        } else {

            let mut found_eof = false;

            let mut number_of_contiguous_bytes = 0;

            for desc in descriptors {

                    break;

                }

                    found_eof = true;

                    break;

                }

                // If the length is smaller than the size, the contiguous-ness ends here.

                    break;

                }

            }

            #[cfg(soc_internal_memory_cached)]

            {

                let buffer_start = chunk_size * self.descriptor_idx + self.descriptor_offset;

                let buffer_len = number_of_contiguous_bytes - self.descriptor_offset;

                if buffer_len != 0 {

                    unsafe {

                        crate::soc::cache_invalidate_addr(

                            self.buf.buffer.as_ptr().add(buffer_start) as u32,

                            buffer_len as u32,

                        );

                    }

                }

            }