rpi-hal-embassy 0.10.0

//! `embassy-net` adapter over `rpi-hal`'s USB-Ethernet drivers: a queue
//! pair for the stack
//! ([`EthernetDriver`](crate::ethernet::EthernetDriver)) and a task that
//! moves frames between those queues and the chip's bulk endpoints
//! ([`EthernetRunner`](crate::ethernet::EthernetRunner)). Build both with
//! [`new`](crate::ethernet::new).
//!
//! Generic over
//! [`EthernetAsync`](rpi_hal::usb::ethernet::EthernetAsync), so the same
//! adapter serves a Pi 2B/3B's LAN9514 and a 3B+'s LAN7800 — which are
//! different chips with nothing in common below that trait. A board that
//! names its chip can keep doing so through
//! [`crate::lan9514`], which is this module under the older spelling.
//!
//! # Why it is split in two
//!
//! `embassy_net_driver::Driver`'s `receive`/`transmit` are synchronous —
//! they return tokens and take a `Context`, so there is nowhere inside
//! them to `.await`. A `Driver` implemented directly over the chip
//! therefore could not use the driver's `async` methods at all, however
//! async those methods were; it would have to do its USB work with the
//! blocking ones, holding the executor for the length of every transfer.
//!
//! `embassy-net-driver-channel` is the way out, and the one `cyw43` and
//! friends take: the `Driver` the stack sees becomes a pair of packet
//! queues, which need no `.await` to serve, and the USB work moves into a
//! task on the far side of them, free to await as much as it likes.
//!
//! # Why two host channels
//!
//! [`new`](crate::ethernet::new) takes two `Channel`s, and the runner
//! keeps a receive parked on one for as long as the network is idle. A
//! single channel would have to be taken away from that parked receive
//! every time the stack wanted to transmit — cancelling a transfer the
//! chip may be part-way through answering, and losing the frame with it.
//! Two channels let the directions proceed independently, which is how
//! the endpoints are meant to be driven: they are separate pipes, and the
//! controller schedules eight of them.
//!
//! # What an application must provide
//!
//! The runner resolves nothing without the USB controller's interrupt.
//! On top of the wiring the crate root already asks for, an application
//! using this must enable that interrupt (`Lic::enable_usb_irq`,
//! `rpi_hal::irq::enable_irq`) and dispatch it from its `__irq_handler`
//! to `rpi_hal::usb::dwc2::on_irq`. Without it the runner's receive parks
//! forever and no frame is ever delivered.
//!
//! That is the whole of the contract. In particular there is nothing to
//! poll: the receive is interrupt-driven, so no ticker, no wake-up
//! interval, and no latency-versus-wake-ups trade for the application to
//! guess at.
//!
//! Available only with the `embassy-net-driver` feature enabled.

use core::sync::atomic::{AtomicU8, AtomicU32, Ordering};
use embassy_futures::join::join;
use embassy_net_driver::{HardwareAddress, LinkState};
use embassy_net_driver_channel as ch;
use rpi_hal::timer::Timer;
use rpi_hal::usb::dwc2::{Channel, TransferError};
use rpi_hal::usb::ethernet::{EthernetAsync, EthernetRx, EthernetTx};

/// How long the runner waits for the link after bringing the chip up,
/// in microseconds, before telling the stack it has one anyway.
///
/// Five seconds: auto-negotiation from a reset is two or three, and the
/// cost of overrunning is only that a board with no cable takes this long
/// to start failing DHCP — which it was going to do regardless.
const LINK_WAIT_US: u64 = 5_000_000;

/// Largest Ethernet frame the queues carry, in bytes.
///
/// Fixed here rather than taken from each driver's
/// [`Ethernet::MTU`](rpi_hal::usb::ethernet::Ethernet::MTU),
/// because `ch::State` takes it as a const generic and `E::MTU` is not
/// usable in that position on stable Rust. Every driver this adapter
/// serves declares the same 1514, and [`new`] asserts it — so the
/// constraint is checked rather than assumed, and a future chip with a
/// different frame size fails loudly here instead of quietly truncating.
///
/// It is also what makes a board able to swap one interface for another
/// under a live stack: `ch::Device<'_, MTU>` differs by this parameter, so
/// a shared value is what keeps the two interchangeable.
pub const MTU: usize = 1514;

/// The packet queues [`new`] builds a
/// [`EthernetDriver`] and [`EthernetRunner`] out of, with room for `N_RX`
/// received and `N_TX` outbound frames.
///
/// An application owns this — typically in a `StaticCell` — because both
/// halves borrow from it for as long as the network stack runs. Depth is
/// the application's call: more buffers absorb a longer burst, at one
/// [`MTU`] each.
pub struct EthernetState<const N_RX: usize, const N_TX: usize> {
    inner: ch::State<MTU, N_RX, N_TX>,
}

impl<const N_RX: usize, const N_TX: usize> EthernetState<N_RX, N_TX> {
    /// Creates the queues, empty. `const`, so it can initialise a
    /// `static` directly.
    pub const fn new() -> Self {
        Self {
            inner: ch::State::new(),
        }
    }
}

impl<const N_RX: usize, const N_TX: usize> Default for EthernetState<N_RX, N_TX> {
    /// The same as [`EthernetState::new`].
    fn default() -> Self {
        Self::new()
    }
}

/// The `embassy_net_driver::Driver` half — what goes to
/// `embassy_net::new`.
///
/// It is the queue pair itself, and is synchronous by design: the frames
/// it hands the stack were fetched by [`EthernetRunner`] before the stack
/// ever asked, which is the whole reason the split exists.
pub type EthernetDriver<'d> = ch::Device<'d, MTU>;

/// The half that talks to the hardware: an endless task moving frames
/// between [`EthernetDriver`]'s queues and the chip's bulk endpoints.
///
/// Created by [`new`] and driven by [`run`](EthernetRunner::run), which an
/// application spawns as its own task.
pub struct EthernetRunner<'d, 'c, E: EthernetAsync> {
    runner: ch::Runner<'d, MTU>,
    ethernet: E,
    rx_channel: Channel<'c>,
    tx_channel: Channel<'c>,
    timer: &'d Timer,
    config: EthernetConfig,
}

/// What the interface should be brought up as.
///
/// The runner does the bring-up itself (see [`new`]), so anything the
/// caller used to set on the driver beforehand has to arrive here instead.
///
/// Named for the module rather than called `Config`, which would collide
/// with `embassy_net::Config` in every file that uses both — and every
/// consumer of this adapter uses both.
#[derive(Clone, Copy, Debug)]
pub struct EthernetConfig {
    /// The station MAC address, programmed into the chip and reported to
    /// `embassy-net` so it can answer ARP.
    ///
    /// A Raspberry Pi keeps its in firmware rather than on the chip —
    /// `rpi_hal::mailbox::Mailbox::mac_address` is where it comes from.
    pub mac: [u8; 6],

    /// Whether to pass every multicast frame up to the stack.
    ///
    /// **`false` is the chip's reset state and it is not a neutral
    /// choice.** The receiver comes up taking unicast for its own address
    /// plus broadcast, and dropping multicast before the stack sees it.
    /// Anything speaking only unicast or broadcast never notices — DHCP is
    /// broadcast, so an interface gets an address and looks entirely
    /// healthy — and anything else fails completely rather than partially.
    /// mDNS is the one that catches people: a responder binds its socket,
    /// joins its group, announces, and is never once queried, with nothing
    /// anywhere reporting an error.
    ///
    /// Set it if anything above the stack speaks multicast.
    pub all_multicast: bool,
}

impl EthernetConfig {
    /// The chip's own defaults with `mac` programmed in: broadcast and
    /// matched unicast only. See [`Self::all_multicast`] before keeping
    /// it.
    pub fn new(mac: [u8; 6]) -> Self {
        Self {
            mac,
            all_multicast: false,
        }
    }
}

/// Wraps an Ethernet controller as an `embassy-net` device, returning the
/// [`EthernetDriver`] to hand to `embassy_net::new` and the
/// [`EthernetRunner`] to spawn.
///
/// **`ethernet` must be enumerated and configured but *not* started.**
/// The runner calls [`EthernetAsync::start_async`] itself, on its first
/// pass, which is why [`EthernetConfig`] exists to carry what the caller would
/// otherwise have set beforehand.
///
/// That is deliberate and worth the awkwardness of handing over an
/// unfinished thing. A driver may configure the chip's answer to an empty
/// bulk IN differently between its blocking and awaited bring-ups —
/// parking a receive needs a NAK, polling one needs the opposite — and
/// starting it with the blocking
/// [`Ethernet::start`](rpi_hal::usb::ethernet::Ethernet::start) and then
/// running it here is neither a compile error nor a failure. It is a
/// receive that never parks, so this runner spins the executor for the
/// life of the interface while every frame still arrives. Owning the
/// bring-up is what makes that unreachable rather than documented.
///
/// `rx_channel` and `tx_channel` are two host channels the runner takes
/// for itself, one per direction — see this module's documentation for
/// why it is two and not one. They are owned rather than borrowed so the
/// controller's remaining channels stay free for other endpoints (a
/// keyboard polled from another task, say) while the stack runs.
pub fn new<'d, 'c, E: EthernetAsync, const N_RX: usize, const N_TX: usize>(
    state: &'d mut EthernetState<N_RX, N_TX>,
    ethernet: E,
    rx_channel: Channel<'c>,
    tx_channel: Channel<'c>,
    timer: &'d Timer,
    config: EthernetConfig,
) -> (EthernetDriver<'d>, EthernetRunner<'d, 'c, E>) {
    // The queues are sized by this module's `MTU`, not the driver's, for
    // the reason that constant gives. Checked rather than assumed: a chip
    // that carried a different frame would otherwise have every oversized
    // frame silently truncated to fit.
    assert!(
        E::MTU == MTU,
        "this adapter's queues are sized for a 1514-byte MTU"
    );

    let (runner, device) = ch::new(&mut state.inner, HardwareAddress::Ethernet(config.mac));
    (
        device,
        attach(runner, ethernet, rx_channel, tx_channel, timer, config),
    )
}

/// Puts a chip behind a queue pair somebody else built, returning the
/// runner to spawn.
///
/// [`new`] is this with the queue pair built for you, and is what a board
/// with one fixed interface wants. This exists for a board that has more
/// than one and picks between them — Ethernet if a cable is in, Wi-Fi
/// otherwise. There the [`EthernetState`] has to outlive any particular
/// choice, so it is created once, up where the choosing happens, and
/// whichever interface wins is attached to it.
///
/// That matters because the queue pair is where the stack's world ends.
/// `embassy_net::Stack` is built around the [`EthernetDriver`] half and
/// holds its sockets and buffers on that side; everything chip-specific is
/// on this one. A board that owns the pair can therefore keep one stack
/// across a change of interface, where a board that let each adapter build
/// its own would have to tear the stack down and lose every socket with
/// it.
///
/// `runner` comes from `embassy_net_driver_channel::new` with the same MAC
/// [`EthernetConfig::mac`] carries — one is what the stack answers ARP
/// with, the other is what gets programmed into the chip, and they have to
/// agree.
pub fn attach<'d, 'c, E: EthernetAsync>(
    runner: ch::Runner<'d, MTU>,
    ethernet: E,
    rx_channel: Channel<'c>,
    tx_channel: Channel<'c>,
    timer: &'d Timer,
    config: EthernetConfig,
) -> EthernetRunner<'d, 'c, E> {
    EthernetRunner {
        runner,
        ethernet,
        rx_channel,
        tx_channel,
        timer,
        config,
    }
}

impl<E: EthernetAsync> EthernetRunner<'_, '_, E> {
    /// Runs the two frame loops until the end of time.
    ///
    /// Receive and transmit are joined rather than selected between:
    /// each owns its own host channel, so neither has to be cancelled to
    /// let the other proceed, and a receive parked on a quiet network
    /// costs nothing while transmits go out past it.
    pub async fn run(self) -> ! {
        let Self {
            runner,
            mut ethernet,
            mut rx_channel,
            mut tx_channel,
            timer,
            config,
        } = self;

        let (state_runner, rx_runner, tx_runner) = runner.split();

        // Bring the chip up here rather than expecting it started, for the
        // reason `new` gives. Over the receive channel and on endpoint 0:
        // this is control transfers, and happens before either channel
        // takes up its frame duties.
        if let Err(error) = ethernet
            .start_async(&mut rx_channel, timer, config.mac)
            .await
        {
            // Tried once, not retried. A chip that fails here has already
            // answered enumeration and a descriptor read, so this is not a
            // device still waking up — and retrying needs a delay, which
            // needs a time source this module deliberately does not have
            // (see the `embassy-time` note in Cargo.toml: the frame path
            // awaits USB transfers and nothing else).
            //
            // Parking rather than looping, so a dead interface costs
            // nothing instead of spinning the executor forever. The stack
            // sees a link that never comes up, which is the honest outward
            // signal; `start_error` says why.
            START_LAST_ERROR.store(error_code(error), Ordering::Relaxed);
            state_runner.set_link_state(LinkState::Down);
            core::future::pending::<()>().await;
        }

        if config.all_multicast {
            // Reported through the same channel as a bring-up failure but
            // not fatal: an interface that filters multicast still carries
            // everything else, and taking it down entirely would turn a
            // degraded mDNS into no network at all.
            if let Err(error) = ethernet
                .set_all_multicast_async(&mut rx_channel, timer, true)
                .await
            {
                START_LAST_ERROR.store(error_code(error), Ordering::Relaxed);
            }
        }

        // Wait for the link before telling the stack it has one.
        //
        // The bring-up above reset the chip, which takes the link down and
        // costs a fresh auto-negotiation — two or three seconds. Reporting
        // `Up` immediately, as this used to, hands `embassy-net` an
        // interface it believes is ready: it sends a DHCP DISCOVER into a
        // link that is still negotiating, hears nothing, and backs off.
        // Measured on a Pi 3B+, that turned a lease that arrives in under a
        // second into one that took eleven, and nothing anywhere reported a
        // fault — the address simply appeared late.
        //
        // Paced by the transfers themselves rather than by a delay: each
        // check is a pair of USB control transfers that park on the
        // controller's interrupt, so the core sleeps between them and this
        // is not a busy loop. The deadline is read from the free-running
        // System Timer, which is why this needs no `embassy-time` (kept off
        // this path deliberately — see Cargo.toml).
        let deadline = timer.now_micros() + LINK_WAIT_US;
        loop {
            match ethernet.is_link_up_async(&mut rx_channel, timer).await {
                Ok(true) => break,
                // A chip that cannot answer about its own PHY is not going
                // to be diagnosed here; let the frame loops report it.
                Err(_) => break,
                Ok(false) => {}
            }
            if timer.now_micros() >= deadline {
                break;
            }
        }

        // Reported up once and left there, however the wait above ended.
        // The real state stays readable — `is_link_up_async` asks the PHY
        // over MII — but `embassy-net` would want it on every pass of its
        // runner, and register access needs the driver whole, which it is
        // not once the two directions are split below. So a cable unplugged
        // *later* surfaces as transfers failing rather than as a link-down
        // transition, and an application that needs better calls
        // `is_link_up_async` on its own schedule — which is also the only
        // place that knows how often is often enough.
        //
        // Up rather than down when the wait timed out, because nothing
        // revisits this: reporting down would leave the stack permanently
        // convinced there is no interface, where reporting up costs only
        // the DHCP retries that were the old behaviour anyway.
        state_runner.set_link_state(LinkState::Up);

        let (rx, tx) = ethernet.split();
        join(
            receive_forever(rx_runner, rx, &mut rx_channel, timer),
            transmit_forever(tx_runner, tx, &mut tx_channel, timer),
        )
        .await
        .0
    }
}

/// Hands every frame the chip produces to the stack's receive queue.
///
/// A transfer that yields nothing usable — an empty answer, or an error —
/// is simply asked again. The stack's recovery is the same either way, and
/// stopping the loop would take the interface down for what is routinely a
/// transient.
///
/// Both outcomes are counted rather than merely ignored; see [`rx_stats`].
async fn receive_forever<R: EthernetRx>(
    mut runner: ch::RxRunner<'_, MTU>,
    mut rx: R,
    channel: &mut Channel<'_>,
    timer: &Timer,
) -> ! {
    // When the previous transfer completed. Between that instant and the
    // next submission below, no bulk IN is pending and an arriving frame
    // has nowhere to go but the chip's FIFO. Timed because a wide window
    // there is packet loss nothing else reports — and because it is a
    // question that gets asked whenever a board loses frames, so it is
    // worth being able to answer in one reading rather than by reasoning.
    // See [`RxStats::gap_max_us`], which records what it measures at.
    let mut completed_at: Option<u64> = None;

    loop {
        if let Some(previous) = completed_at {
            record_gap(timer.now_micros().wrapping_sub(previous));
        }

        // One transfer, then every frame out of it. The slot is claimed
        // per frame rather than once before the transfer, because the
        // number of frames is not known until it arrives — and claiming
        // one in advance would cover only the first, leaving the rest to
        // be dropped exactly as they were before this loop was a loop.
        //
        // Backpressure still lands in the right place. A full queue parks
        // this task in `rx_buf`, no further transfer is issued while it
        // waits, and frames accumulate in the chip's FIFO — one
        // transfer's worth later than they used to, which is the whole
        // difference.
        let outcome = rx.receive_frames_async(channel, timer).await;
        completed_at = Some(timer.now_micros());

        match outcome {
            Ok(frames) => {
                let mut delivered = 0u32;
                for frame in frames {
                    let buf = runner.rx_buf().await;
                    let len = frame.len().min(buf.len());
                    buf[..len].copy_from_slice(&frame[..len]);
                    runner.rx_done(len);
                    delivered += 1;
                }
                if delivered == 0 {
                    RX_UNUSABLE.fetch_add(1, Ordering::Relaxed);
                } else {
                    RX_FRAMES.fetch_add(delivered, Ordering::Relaxed);
                    if delivered > 1 {
                        RX_BATCHED.fetch_add(1, Ordering::Relaxed);
                    }
                }
            }
            Err(error) => {
                RX_FAILURES.fetch_add(1, Ordering::Relaxed);
                RX_LAST_ERROR.store(error_code(error), Ordering::Relaxed);
            }
        }
    }
}

/// Frames [`receive_forever`] has delivered to the stack since boot.
static RX_FRAMES: AtomicU32 = AtomicU32::new(0);

/// Transfers that produced no usable frame — see [`RxStats::unusable`].
static RX_UNUSABLE: AtomicU32 = AtomicU32::new(0);

/// Transfers that carried more than one frame — see [`RxStats::batched`].
static RX_BATCHED: AtomicU32 = AtomicU32::new(0);

/// Widest gap yet seen with no receive transfer pending, in microseconds.
static GAP_MAX_US: AtomicU32 = AtomicU32::new(0);

/// Gaps wider than [`GAP_LONG_US`].
static GAP_LONG: AtomicU32 = AtomicU32::new(0);

/// Gaps at least this wide are counted, not just recorded as a maximum.
///
/// A hundred microseconds is about ten frames' worth of arrival time at
/// 100 Mbit for the small frames this matters for — acknowledgements. Below
/// that a gap cannot plausibly overrun the chip; above it, it can.
const GAP_LONG_US: u64 = 100;

/// Notes one gap between a transfer completing and the next being issued.
///
/// A maximum and a count rather than a mean: the loss this measures is
/// caused by the *worst* gaps, and an average dominated by thousands of
/// microsecond-wide ones would hide exactly the outliers that matter.
fn record_gap(microseconds: u64) {
    let gap = u32::try_from(microseconds).unwrap_or(u32::MAX);
    GAP_MAX_US.fetch_max(gap, Ordering::Relaxed);
    if microseconds >= GAP_LONG_US {
        GAP_LONG.fetch_add(1, Ordering::Relaxed);
    }
}

/// Receive transfers that failed outright.
static RX_FAILURES: AtomicU32 = AtomicU32::new(0);

/// [`error_code`] of the most recent receive failure, or [`NO_ERROR`].
static RX_LAST_ERROR: AtomicU8 = AtomicU8::new(NO_ERROR);

/// What the receive loop has managed since boot.
///
/// Returned by [`rx_stats`].
#[derive(Clone, Copy, Debug)]
pub struct RxStats {
    /// Frames handed to the stack.
    ///
    /// Worth comparing against what the peer believes it sent. A shortfall
    /// is frames that reached the chip and never reached the stack, and
    /// there is no other way to see them: the peer's retransmissions make
    /// the connection work, so nothing fails, and the only symptom is
    /// latency.
    pub frames: u32,
    /// Transfers that returned successfully carrying nothing usable — a
    /// zero-length or truncated answer, or a frame the chip itself flagged
    /// as errored.
    ///
    /// Distinct from [`Self::failures`], where the transfer itself did not
    /// complete.
    pub unusable: u32,
    /// Transfers that carried more than one frame.
    ///
    /// The number that says whether coalescing is happening at all, and so
    /// whether draining a transfer is doing anything. Every frame after the
    /// first in each of these used to be discarded silently — the chip had
    /// handed them over, and only the head was parsed.
    pub batched: u32,
    /// Receive transfers that failed outright.
    pub failures: u32,
    /// Why the most recent failure failed, or `None` if none has.
    pub last_error: Option<TransferError>,
    /// Widest gap seen with no receive transfer pending, in microseconds.
    ///
    /// **This measures the application, not the adapter.** Exactly one
    /// bulk IN is outstanding at a time, so between one transfer
    /// completing and the next being issued the chip has nowhere to put an
    /// arriving frame but its own FIFO. The work in that window is a
    /// memcpy per frame, so it should be single-digit microseconds —
    /// measured at 5 to 15 µs on a Pi 2 while serving eight concurrent
    /// HTTP connections, with none at all above 100 µs.
    ///
    /// A large value therefore says the *executor* is not getting back to
    /// this task: a long critical section, blocking card or bus work, or a
    /// blocking console write. That is worth knowing because the resulting
    /// packet loss is silent — the frames never arrive and the peer waits
    /// out a retransmission timeout — and nothing else in this crate can
    /// distinguish it from a network problem.
    ///
    /// It is deliberately not a driver knob. Reordering the loop body or
    /// keeping several transfers in flight, as Linux's usbnet does with a
    /// queue of about forty, would shrink this window; neither is
    /// implemented here because the window has not been measured wide
    /// enough to matter. If it is wide on your board, the thing holding
    /// the CPU is the thing to fix.
    pub gap_max_us: u32,
    /// How many gaps were at least 100 µs wide — roughly ten small frames'
    /// arrival time at 100 Mbit, and so the point below which a gap cannot
    /// plausibly cost a frame.
    ///
    /// More useful than [`Self::gap_max_us`] for watching a running board:
    /// the maximum is a high-water mark that bring-up can set once and
    /// leave standing, while this climbing is a live symptom.
    pub gaps_long: u32,
}

/// What the receive loop has managed since boot.
///
/// The counterpart to [`tx_stats`], and for the same reason: a frame lost on
/// the way in is as invisible as one lost on the way out, and it is the
/// harder of the two to reason about from outside. A lost acknowledgement
/// does not lose data — it stalls the sender until its retransmission timer
/// fires, so the cost lands on a connection that is working perfectly and
/// looks it.
pub fn rx_stats() -> RxStats {
    RxStats {
        frames: RX_FRAMES.load(Ordering::Relaxed),
        unusable: RX_UNUSABLE.load(Ordering::Relaxed),
        batched: RX_BATCHED.load(Ordering::Relaxed),
        failures: RX_FAILURES.load(Ordering::Relaxed),
        last_error: error_from_code(RX_LAST_ERROR.load(Ordering::Relaxed)),
        gap_max_us: GAP_MAX_US.load(Ordering::Relaxed),
        gaps_long: GAP_LONG.load(Ordering::Relaxed),
    }
}

/// Sends every frame the stack queues.
///
/// A failed send is dropped, and the buffer released either way, or the
/// queue would wedge on the first failure. Retransmission is left to the
/// layer above, which owns a timer for it.
///
/// That dropped frame is counted rather than merely discarded — see
/// [`tx_stats`] for why a silent one is worth this much bookkeeping.
async fn transmit_forever<T: EthernetTx>(
    mut runner: ch::TxRunner<'_, MTU>,
    mut tx: T,
    channel: &mut Channel<'_>,
    timer: &Timer,
) -> ! {
    loop {
        let buf = runner.tx_buf().await;
        let outcome = tx.send_frame_async(channel, timer, buf).await;

        TX_FRAMES.fetch_add(1, Ordering::Relaxed);
        if let Err(error) = outcome {
            TX_FAILURES.fetch_add(1, Ordering::Relaxed);
            TX_LAST_ERROR.store(error_code(error), Ordering::Relaxed);
        }

        runner.tx_done();
    }
}

/// Frames [`transmit_forever`] has handed to the chip since boot.
static TX_FRAMES: AtomicU32 = AtomicU32::new(0);

/// How many of those the chip refused.
static TX_FAILURES: AtomicU32 = AtomicU32::new(0);

/// [`error_code`] of the most recent failure, or [`NO_ERROR`].
static TX_LAST_ERROR: AtomicU8 = AtomicU8::new(NO_ERROR);

/// [`TX_LAST_ERROR`] before anything has failed.
///
/// Zero rather than a variant's code so that "nothing has gone wrong" is the
/// value the counter starts at.
const NO_ERROR: u8 = 0;

/// What the transmit loop has managed since boot.
///
/// Returned by [`tx_stats`]. Counters, not a rate: an application decides
/// what interval to compare two readings over.
#[derive(Clone, Copy, Debug)]
pub struct TxStats {
    /// Frames the loop attempted to send.
    pub frames: u32,
    /// How many of those the chip refused, and which this adapter therefore
    /// dropped.
    ///
    /// **Not the same as frames lost on the network.** A drop here is a
    /// frame that never reached the wire at all, and nothing below TCP will
    /// notice: the peer waits out a retransmission timeout, which on a LAN
    /// is orders of magnitude longer than the transfer would have taken. A
    /// handful of these is enough to make a page load visibly stall while
    /// every other indicator — link state, throughput, error counters on the
    /// switch — looks perfectly healthy.
    pub failures: u32,
    /// Why the most recent failure failed, or `None` if none has.
    ///
    /// Which variant it is decides what to do about it, so it is worth more
    /// than the count on its own. A [`TransferError::Timeout`] or
    /// [`TransferError::NakTimeout`] is the chip declining to accept a frame
    /// it has no room for, and a caller that waited and asked again would
    /// have got it through. A [`TransferError::DataToggleError`] is host and
    /// device disagreeing about the bulk endpoint's toggle, which retrying
    /// cannot fix and which needs the endpoint resynchronised.
    pub last_error: Option<TransferError>,
}

/// What the transmit loop has managed since boot.
///
/// Exists because a frame this adapter drops is otherwise invisible. The
/// stack is told the send succeeded, the chip never sees the frame, and the
/// only trace is the peer's retransmission timeout some hundreds of
/// milliseconds later — so the symptom presents as latency with no
/// corresponding error anywhere, which is a hard thing to go looking for
/// without a number to look at.
///
/// Cheap enough to leave enabled: three relaxed atomic operations per frame,
/// against a USB transfer.
pub fn tx_stats() -> TxStats {
    TxStats {
        frames: TX_FRAMES.load(Ordering::Relaxed),
        failures: TX_FAILURES.load(Ordering::Relaxed),
        last_error: error_from_code(TX_LAST_ERROR.load(Ordering::Relaxed)),
    }
}

/// Packs a [`TransferError`] into a byte, so the last one can live in an
/// atomic.
///
/// A `match` rather than a `as` cast: [`TransferError`] carries no explicit
/// discriminants, so casting would silently renumber the codes if a variant
/// were ever inserted, and a stored code would then decode as the wrong
/// error.
fn error_code(error: TransferError) -> u8 {
    match error {
        TransferError::Stall => 1,
        TransferError::TransactionError => 2,
        TransferError::Babble => 3,
        TransferError::Nak => 4,
        TransferError::NakTimeout => 5,
        TransferError::FrameOverrun => 6,
        TransferError::DataToggleError => 7,
        TransferError::Halted => 8,
        TransferError::Timeout => 9,
    }
}

/// The inverse of [`error_code`]. Anything unrecognised — including
/// [`NO_ERROR`] — is `None`.
fn error_from_code(code: u8) -> Option<TransferError> {
    Some(match code {
        1 => TransferError::Stall,
        2 => TransferError::TransactionError,
        3 => TransferError::Babble,
        4 => TransferError::Nak,
        5 => TransferError::NakTimeout,
        6 => TransferError::FrameOverrun,
        7 => TransferError::DataToggleError,
        8 => TransferError::Halted,
        9 => TransferError::Timeout,
        _ => return None,
    })
}

/// [`error_code`] of the failure that stopped bring-up, or [`NO_ERROR`].
static START_LAST_ERROR: AtomicU8 = AtomicU8::new(NO_ERROR);

/// Why the interface failed to start, or `None` if it did not fail.
///
/// `Some` here and a link that never comes up are the same event seen from
/// two places. The runner attempts the bring-up once and then parks, so
/// this does not change afterwards — and unlike the receive and transmit
/// counters, a value here means the interface never carried a frame at
/// all rather than that it dropped some.
///
/// Also set, non-fatally, if the multicast filter could not be configured
/// (see [`EthernetConfig::all_multicast`]). That case leaves the interface working
/// for everything except the traffic that filter would have passed, which
/// is worth being able to tell apart from a total failure — the link state
/// is what distinguishes them.
pub fn start_error() -> Option<TransferError> {
    error_from_code(START_LAST_ERROR.load(Ordering::Relaxed))
}