esp-hal 1.2.0

//! EMAC DMA descriptor rings.
//!
//! Implements the chained-ring descriptor layout for the Synopsys DesignWare
//! GMAC as found on ESP32 and ESP32-P4. The driver always uses the **enhanced
//! 32-byte descriptor format** (`ALT_DESC_SIZE = 1` in `EMAC_DMA.dmabusmode`).

use core::sync::atomic::{Ordering, fence};

use crate::{dma::aligned::InternalMemory, reg_access::VolatileCell};

/// Maximum frame size supported per DMA buffer (1518 + FCS + rounding).
pub const MAX_FRAME_SIZE: usize = 1524;
/// Minimum accepted RX frame length.
pub const MIN_RX_FRAME_SIZE: usize = 14;

// ── TDES bits ──────────────────────────────────────────────────────────────

/// TX descriptor ownership bit: 1 = owned by DMA.
pub const TDES0_OWN: u32 = 1 << 31;
/// TX interrupt-on-completion.
pub const TDES0_IC: u32 = 1 << 30;
/// TX last-segment flag.
pub const TDES0_LS: u32 = 1 << 29;
/// TX first-segment flag.
pub const TDES0_FS: u32 = 1 << 28;
/// TX checksum insertion control: 3 = IP Header checksum and payload checksum calculation
/// and insertion are enabled, and pseudo-header checksum is calculated in hardware.
pub const TDES0_CIC_FULL: u32 = 3 << 22;
/// TX second-address-chained mode (next descriptor pointer in TDES3).
pub const TDES0_CHAINED: u32 = 1 << 20;

// ── RDES bits ──────────────────────────────────────────────────────────────

/// RX descriptor ownership bit: 1 = owned by DMA.
pub const RDES0_OWN: u32 = 1 << 31;
/// RX frame length field shift inside RDES0.
pub const RDES0_FL_SHIFT: u32 = 16;
/// RX frame length field mask inside RDES0.
pub const RDES0_FL_MASK: u32 = 0x3fff << RDES0_FL_SHIFT;
/// RX error-summary bit.
pub const RDES0_ES: u32 = 1 << 15;
/// RX first-segment flag.
pub const RDES0_FS: u32 = 1 << 9;
/// RX last-segment flag.
pub const RDES0_LS: u32 = 1 << 8;

/// RX buffer-1 size field mask in RDES1.
pub const RDES1_BUF1_SIZE_MASK: u32 = 0x1fff;
/// RX second-address-chained bit.
pub const RDES1_CHAINED: u32 = 1 << 14;

// ── RDES4 extended-status bits (Type-2 checksum offload) ─────────────────────
//
// Only consumed on chips whose RX FIFO runs in cut-through mode and therefore
// cannot rely on the DMA to auto-drop checksum-error frames (see `dma_start`).

cfg_select! {
    esp32p4 => {
        /// RDES0 extended-status-available bit: RDES4 holds valid COE status.
        pub const RDES0_ESA: u32 = 1 << 0;
        /// RDES4: IP header checksum error.
        pub const RDES4_IP_HEADER_ERROR: u32 = 1 << 3;
        /// RDES4: IP payload (TCP/UDP/ICMP) checksum error.
        pub const RDES4_IP_PAYLOAD_ERROR: u32 = 1 << 4;
        /// RDES4: IP checksum offload engine was bypassed (checksum not verified).
        pub const RDES4_IP_CHECKSUM_BYPASSED: u32 = 1 << 5;
        /// RDES4: IPv4 packet received.
        pub const RDES4_IPV4_PACKET: u32 = 1 << 6;
        /// RDES4: IPv6 packet received.
        pub const RDES4_IPV6_PACKET: u32 = 1 << 7;
    }
    _ => {}
}

// ── Descriptor types ────────────────────────────────────────────────────────

/// Current descriptor owner.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum OwnedBy {
    /// The CPU owns the descriptor.
    Cpu,
    /// The DMA engine owns the descriptor.
    Dma,
}

/// TX DMA descriptor (enhanced 32-byte format, `ALT_DESC_SIZE = 1`).
///
/// Layout matches the Synopsys DesignWare GMAC databook for enhanced mode.
/// Words 4–7 are reserved for hardware use (TX timestamp, etc.).
#[repr(C)]
pub struct TDes {
    pub(super) tdes0: VolatileCell<u32>,
    pub(super) tdes1: VolatileCell<u32>,
    pub(super) buf_addr: VolatileCell<u32>,
    pub(super) next_desc: VolatileCell<u32>,
    // Enhanced words — set to zero; hardware may write TX timestamp here.
    _tdes4: VolatileCell<u32>,
    _tdes5: VolatileCell<u32>,
    _tdes6: VolatileCell<u32>,
    _tdes7: VolatileCell<u32>,
}

impl TDes {
    /// Zero-initialized descriptor, suitable for `static` initializers.
    pub const fn new_zeroed() -> Self {
        Self {
            tdes0: VolatileCell::new(0),
            tdes1: VolatileCell::new(0),
            buf_addr: VolatileCell::new(0),
            next_desc: VolatileCell::new(0),
            _tdes4: VolatileCell::new(0),
            _tdes5: VolatileCell::new(0),
            _tdes6: VolatileCell::new(0),
            _tdes7: VolatileCell::new(0),
        }
    }

    /// Current ownership of this descriptor.
    pub fn owned_by(&self) -> OwnedBy {
        if self.tdes0.get() & TDES0_OWN != 0 {
            OwnedBy::Dma
        } else {
            OwnedBy::Cpu
        }
    }

    /// Sets the ownership bit.
    pub fn set_owned_by(&mut self, owner: OwnedBy) {
        let v = self.tdes0.get();
        self.tdes0.set(match owner {
            OwnedBy::Cpu => v & !TDES0_OWN,
            OwnedBy::Dma => v | TDES0_OWN,
        });
    }

    fn set_chained(&mut self) {
        self.tdes0.set(self.tdes0.get() | TDES0_CHAINED);
    }

    fn set_len_and_flags(&mut self, len: usize) {
        self.tdes1.set(len as u32 & RDES1_BUF1_SIZE_MASK);
        self.tdes0.set(
            (self.tdes0.get() & TDES0_CHAINED) | TDES0_FS | TDES0_LS | TDES0_IC | TDES0_CIC_FULL,
        );
    }

    fn set_buffer_addr(&mut self, addr: *const u8) {
        self.buf_addr.set(addr as u32);
    }

    fn set_next_desc(&mut self, addr: *const TDes) {
        self.next_desc.set(addr as u32);
    }
}

/// RX DMA descriptor (enhanced 32-byte format, `ALT_DESC_SIZE = 1`).
///
/// Words 4–7 are reserved for hardware use (RX timestamp, VLAN, etc.).
#[repr(C)]
pub struct RDes {
    pub(super) rdes0: VolatileCell<u32>,
    pub(super) rdes1: VolatileCell<u32>,
    pub(super) buf_addr: VolatileCell<u32>,
    pub(super) next_desc: VolatileCell<u32>,
    // Extended status; the GMAC writes IP checksum-offload results here.
    #[cfg_attr(
        not(esp32p4),
        allow(dead_code, reason = "only read for P4 RX checksum offload")
    )]
    rdes4: VolatileCell<u32>,
    _rdes5: VolatileCell<u32>,
    _rdes6: VolatileCell<u32>,
    _rdes7: VolatileCell<u32>,
}

impl RDes {
    /// Zero-initialized descriptor, suitable for `static` initializers.
    pub const fn new_zeroed() -> Self {
        Self {
            rdes0: VolatileCell::new(0),
            rdes1: VolatileCell::new(0),
            buf_addr: VolatileCell::new(0),
            next_desc: VolatileCell::new(0),
            rdes4: VolatileCell::new(0),
            _rdes5: VolatileCell::new(0),
            _rdes6: VolatileCell::new(0),
            _rdes7: VolatileCell::new(0),
        }
    }

    /// Current ownership of this descriptor.
    pub fn owned_by(&self) -> OwnedBy {
        if self.rdes0.get() & RDES0_OWN != 0 {
            OwnedBy::Dma
        } else {
            OwnedBy::Cpu
        }
    }

    fn set_rdes0(&mut self, value: u32) {
        self.rdes0.set(value);
    }

    fn set_owned_by(&mut self, owner: OwnedBy) {
        let v = self.rdes0.get();
        self.set_rdes0(match owner {
            OwnedBy::Cpu => v & !RDES0_OWN,
            OwnedBy::Dma => v | RDES0_OWN,
        });
    }

    fn is_complete_frame(&self) -> bool {
        let s = self.rdes0.get();
        s & RDES0_FS != 0 && s & RDES0_LS != 0
    }

    fn frame_len(&self) -> usize {
        ((self.rdes0.get() & RDES0_FL_MASK) >> RDES0_FL_SHIFT) as usize
    }

    /// Returns whether the hardware IP checksum-offload engine flagged a
    /// header or payload checksum error for this frame.
    ///
    /// These results live in the extended-status word (RDES4) rather than in
    /// `RDES0_ES`, so they must be inspected explicitly. Only meaningful on the
    /// last descriptor of a frame. Non-IP frames (e.g. ARP) and frames whose
    /// checksum the engine bypassed never report an error.
    #[cfg(esp32p4)]
    fn checksum_error(&self) -> bool {
        // The extended status is only valid when RDES0[0] (ESA) is set.
        if self.rdes0.get() & RDES0_ESA == 0 {
            return false;
        }

        let ext = self.rdes4.get();

        // The COE status bits only apply to IPv4/IPv6 frames.
        let is_ip = ext & (RDES4_IPV4_PACKET | RDES4_IPV6_PACKET) != 0;
        // If the engine bypassed the checksum, there is nothing to reject.
        let bypassed = ext & RDES4_IP_CHECKSUM_BYPASSED != 0;

        is_ip && !bypassed && ext & (RDES4_IP_HEADER_ERROR | RDES4_IP_PAYLOAD_ERROR) != 0
    }

    fn configure_buffer(&mut self, size: usize) {
        self.rdes1.set(
            (self.rdes1.get() & !RDES1_BUF1_SIZE_MASK)
                | (size as u32 & RDES1_BUF1_SIZE_MASK)
                | RDES1_CHAINED,
        );
    }

    fn set_buffer_addr(&mut self, addr: *const u8) {
        self.buf_addr.set(addr as u32);
    }

    fn set_next_desc(&mut self, addr: *const RDes) {
        self.next_desc.set(addr as u32);
    }
}

// ── Static DMA storage ──────────────────────────────────────────────────────

/// Static backing storage for all DMA descriptor rings and packet buffers.
///
/// `TX` is the number of transmit slots; `RX` is the number of receive slots.
/// Pass a mutable reference to [`Ethernet::new`][super::Ethernet::new].
pub struct EthernetDmaStorage<const RX: usize, const TX: usize> {
    pub(super) rx_descs: [InternalMemory<RDes>; RX],
    pub(super) tx_descs: [InternalMemory<TDes>; TX],
    pub(super) rx_bufs: [InternalMemory<[u8; MAX_FRAME_SIZE]>; RX],
    pub(super) tx_bufs: [InternalMemory<[u8; MAX_FRAME_SIZE]>; TX],
}

impl<const RX: usize, const TX: usize> Default for EthernetDmaStorage<RX, TX> {
    fn default() -> Self {
        Self::new()
    }
}

impl<const RX: usize, const TX: usize> EthernetDmaStorage<RX, TX> {
    /// Creates a new zero-initialized storage block, suitable for `static` placement.
    pub const fn new() -> Self {
        Self {
            rx_descs: [const { InternalMemory::new(RDes::new_zeroed()) }; RX],
            tx_descs: [const { InternalMemory::new(TDes::new_zeroed()) }; TX],
            rx_bufs: [const { InternalMemory::new([0u8; MAX_FRAME_SIZE]) }; RX],
            tx_bufs: [const { InternalMemory::new([0u8; MAX_FRAME_SIZE]) }; TX],
        }
    }
}

// SAFETY: `EthernetDmaStorage` is only accessed through the driver, which
// enforces exclusive access via `&mut` borrows.
unsafe impl<const RX: usize, const TX: usize> Send for EthernetDmaStorage<RX, TX> {}
unsafe impl<const RX: usize, const TX: usize> Sync for EthernetDmaStorage<RX, TX> {}

// ── TX ring ─────────────────────────────────────────────────────────────────

/// TX descriptor ring backed by references into `EthernetDmaStorage`.
pub struct TDesRing<'a> {
    descriptors: &'a mut [InternalMemory<TDes>],
    buffers: &'a mut [InternalMemory<[u8; MAX_FRAME_SIZE]>],
    index: usize,
}

impl<'a> TDesRing<'a> {
    /// Creates a new TX ring from the given descriptor and buffer slices.
    pub fn new(
        descriptors: &'a mut [InternalMemory<TDes>],
        buffers: &'a mut [InternalMemory<[u8; MAX_FRAME_SIZE]>],
    ) -> Self {
        assert!(!descriptors.is_empty());
        assert_eq!(descriptors.len(), buffers.len());

        let mut ring = Self {
            descriptors,
            buffers,
            index: 0,
        };
        ring.reset();
        ring
    }

    pub(crate) fn len(&self) -> usize {
        self.descriptors.len()
    }

    /// Rebuilds ring links and returns all descriptors to CPU ownership.
    ///
    /// Call once after `EMAC_DMA` soft-reset completes and before starting TX.
    pub fn reset(&mut self) {
        let n = self.descriptors.len();
        for i in 0..n {
            let next = self.descriptors[(i + 1) % n].as_ptr();
            let buf_addr = self.buffers[i].as_ptr().cast::<u8>();

            let mut desc = self.descriptors[i].get_mut();
            desc.tdes0.set(0);
            desc.tdes1.set(0);
            desc.set_chained();
            desc.set_buffer_addr(buf_addr);
            desc.set_next_desc(next);
            desc.set_owned_by(OwnedBy::Cpu);
            #[cfg(soc_internal_memory_cached)]
            self.descriptors[i].get_mut().writeback();
        }
        self.index = 0;
        fence(Ordering::Release);
    }

    /// Returns the address of the first descriptor (used to program `EMAC_DMA.dmatxbaseaddr`).
    pub fn base_ptr(&self) -> *const TDes {
        self.descriptors[0].as_ptr()
    }

    /// Copies `frame` into the next available TX buffer and hands it to DMA.
    ///
    /// Returns `Err(DescriptorError::RingFull)` if no CPU-owned slot is available.
    /// and `Err(DescriptorError::FrameTooLarge)` if the frame exceeds [`MAX_FRAME_SIZE`].
    pub fn transmit(&mut self, frame: &[u8]) -> Result<(), TxError> {
        if frame.len() > MAX_FRAME_SIZE {
            return Err(TxError::FrameTooLarge);
        }

        if let Some(buf) = self.available_buf() {
            buf[..frame.len()].copy_from_slice(frame);
            self.commit(frame.len());
            Ok(())
        } else {
            Err(TxError::RingFull)
        }
    }

    /// Returns whether the current slot is CPU-owned (ready to accept a frame).
    pub fn has_capacity(&self) -> bool {
        let desc = self.descriptors[self.index].get_ref();
        #[cfg(soc_internal_memory_cached)]
        desc.invalidate();
        fence(Ordering::Acquire);
        desc.owned_by() == OwnedBy::Cpu
    }

    /// Returns a mutable reference to the current TX DMA buffer when the slot is
    /// CPU-owned, which enables zero-copy frame construction.
    ///
    /// After writing the frame, call [`TDesRing::commit`] to hand it to DMA.
    /// Returns `None` when the slot is not CPU-owned.
    pub fn available_buf(&mut self) -> Option<&mut [u8; MAX_FRAME_SIZE]> {
        if self.has_capacity() {
            let idx = self.index;
            Some(self.buffers[idx].get_mut().into_inner())
        } else {
            None
        }
    }

    /// Commits the frame written into the buffer returned by [`TDesRing::available_buf`].
    ///
    /// Sets the frame length, hands the descriptor to DMA, and advances the
    /// ring index.  The caller must trigger a TX poll demand after this call
    /// (see `EmacRegs::demand_tx_poll`).
    pub fn commit(&mut self, len: usize) {
        let idx = self.index;
        let n = self.descriptors.len();

        #[cfg(soc_internal_memory_cached)]
        self.buffers[idx].get_mut().writeback();

        let mut desc = self.descriptors[idx].get_mut();
        desc.set_len_and_flags(len);
        desc.set_owned_by(OwnedBy::Dma);

        #[cfg(soc_internal_memory_cached)]
        desc.writeback();

        fence(Ordering::Release);
        self.index = (idx + 1) % n;
    }
}

/// Error returned by [`TDesRing::transmit`].
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum TxError {
    /// No CPU-owned descriptor is available right now.
    RingFull,
    /// Frame is larger than `MAX_FRAME_SIZE`.
    FrameTooLarge,
}

// ── RX ring ─────────────────────────────────────────────────────────────────

/// RX descriptor ring backed by references into `EthernetDmaStorage`.
pub struct RDesRing<'a> {
    descriptors: &'a mut [InternalMemory<RDes>],
    buffers: &'a mut [InternalMemory<[u8; MAX_FRAME_SIZE]>],
    index: usize,
}

impl<'a> RDesRing<'a> {
    /// Creates a new RX ring from the given descriptor and buffer slices.
    pub fn new(
        descriptors: &'a mut [InternalMemory<RDes>],
        buffers: &'a mut [InternalMemory<[u8; MAX_FRAME_SIZE]>],
    ) -> Self {
        assert!(!descriptors.is_empty());
        assert_eq!(descriptors.len(), buffers.len());

        let mut ring = Self {
            descriptors,
            buffers,
            index: 0,
        };
        ring.reset();
        ring
    }

    /// Rebuilds ring links and returns all descriptors to DMA ownership.
    ///
    /// Call once after `EMAC_DMA` soft-reset completes and before starting RX.
    pub fn reset(&mut self) {
        let n = self.descriptors.len();
        for i in 0..n {
            let next = self.descriptors[(i + 1) % n].as_ptr();
            let buf_addr = self.buffers[i].as_ptr().cast::<u8>();

            #[cfg(soc_internal_memory_cached)]
            self.buffers[i].get_mut().invalidate();

            let mut desc = self.descriptors[i].get_mut();
            desc.rdes0.set(0);
            desc.configure_buffer(MAX_FRAME_SIZE);
            desc.set_buffer_addr(buf_addr);
            desc.set_next_desc(next);
            desc.set_owned_by(OwnedBy::Dma);
            #[cfg(soc_internal_memory_cached)]
            desc.writeback();
        }
        self.index = 0;
        fence(Ordering::Release);
    }

    /// Returns the address of the first descriptor (used to program `EMAC_DMA.dmarxbaseaddr`).
    pub fn base_ptr(&self) -> *const RDes {
        self.descriptors[0].as_ptr()
    }

    /// Returns a mutable data slice for a ready frame, or `None` when no frame is ready.
    ///
    /// Loops past error/incomplete/oversized frames, recycling them back to DMA
    /// automatically. Returns `None` only when no CPU-owned descriptor remains.
    /// Call [`RDesRing::pop`] after the returned slice is no longer needed, to
    /// release the descriptor back to DMA.
    pub fn receive(&mut self) -> Option<&mut [u8]> {
        loop {
            let idx = self.index;

            // Inspect the descriptor. Returns `Some(len)` for a valid frame,
            // `None` if the slot must be recycled. The descriptor borrow ends
            // with this block so `recycle_current` can reborrow `self`.
            let len = {
                let desc = self.descriptors[idx].get_ref();
                #[cfg(soc_internal_memory_cached)]
                desc.invalidate();
                fence(Ordering::Acquire);
                if desc.owned_by() != OwnedBy::Cpu {
                    return None;
                }

                let status = desc.rdes0.get();
                let is_complete = desc.is_complete_frame();
                let frame_len = desc.frame_len();

                // On chips with cut-through RX the DMA can't auto-drop
                // checksum-error frames, so reject them here based on the
                // extended-status COE bits.
                let checksum_bad = cfg_select! {
                    esp32p4 => desc.checksum_error(),
                    _ => false,
                };

                if status & RDES0_ES != 0 || !is_complete || checksum_bad {
                    None
                } else {
                    // Strip the 4-byte FCS the GMAC appends to the frame length.
                    let len = frame_len.saturating_sub(4);
                    if (MIN_RX_FRAME_SIZE..=MAX_FRAME_SIZE).contains(&len) {
                        Some(len)
                    } else {
                        None
                    }
                }
            };

            let Some(len) = len else {
                self.recycle_current();
                continue;
            };

            #[cfg(soc_internal_memory_cached)]
            self.buffers[idx].get_mut().invalidate();
            fence(Ordering::Acquire);
            return Some(&mut self.buffers[idx].get_mut().into_inner()[..len]);
        }
    }

    /// Releases the current RX descriptor back to DMA ownership.
    ///
    /// Must be called after every successful [`RDesRing::receive`] call.
    pub fn pop(&mut self) {
        self.recycle_current();
    }

    /// Returns `true` when the current descriptor has been returned by DMA.
    pub fn has_packet(&self) -> bool {
        let desc = self.descriptors[self.index].get_ref();
        #[cfg(soc_internal_memory_cached)]
        desc.invalidate();
        fence(Ordering::Acquire);
        desc.owned_by() == OwnedBy::Cpu
    }

    fn recycle_current(&mut self) {
        let idx = self.index;
        let n = self.descriptors.len();
        let mut desc = self.descriptors[idx].get_mut();
        desc.set_rdes0(RDES0_OWN);
        #[cfg(soc_internal_memory_cached)]
        desc.writeback();
        fence(Ordering::Release);
        self.index = (idx + 1) % n;
    }
}