psicose 0.4.3

no_std heapless reliable link motor: 4-byte frame, ACK/CRC, window N≤8, P2P Node/PeerLink, LinkFace — zero crate dependencies
Documentation
//! One physical link → two [`ByteTransport`] ends for [`crate::Pump`].
//!
//! A UART (or any single RX stream) cannot be read by both the sender and
//! the receiver: ACK/NACK must go to TX, DATA/START/FINISH/ABORT to RX.
//! [`LinkFace`] demultiplexes complete frames so [`crate::Pump::on`] can
//! run on real hardware.
//!
//! ```text
//! application
//!    Pump::on(FaceTx, FaceRx)
//!              │        │
//!              ▼        ▼
//!           LinkFace (demux)
//!              │
//!         ByteTransport   ← your UART impl on ESP32
//! ```
//!
//! In-memory A↔B tests keep using [`crate::Wire`] (`DuplexWire`). Hardware
//! (and any single-port link) uses this type.
//!
//! # Write discipline
//!
//! [`FaceTx`] and [`FaceRx`] share one TX pin. Stop-and-wait keeps them from
//! writing at the same time while only one peer streams DATA. When **both**
//! peers send, use [`crate::Turn`]: only the peer whose turn it is opens
//! `START`, then the turn flips. Two concurrent `START`s interleave on the wire.

use core::cell::RefCell;
use core::fmt;

use crate::protocol::{FrameAssembler, FrameType, FRAME_LEN};
use crate::pump::{Pump, WindowedPump};
use crate::timeout::RetryPolicy;
use crate::transport::page::PageLink;
use crate::transport::turn::{Turn, WindowTurn};
use crate::transport::ByteTransport;
use crate::window::MAX_WINDOW;

const RING: usize = 64;

#[derive(Clone, Copy)]
struct Ring {
    buf: [u8; RING],
    head: usize,
    tail: usize,
    len: usize,
}

impl Ring {
    const fn new() -> Self {
        Ring {
            buf: [0; RING],
            head: 0,
            tail: 0,
            len: 0,
        }
    }

    fn pop(&mut self) -> Option<u8> {
        if self.len == 0 {
            return None;
        }
        let byte = self.buf[self.head];
        self.head = (self.head + 1) % RING;
        self.len -= 1;
        Some(byte)
    }

    fn push_frame(&mut self, bytes: [u8; FRAME_LEN]) -> bool {
        if self.len > RING - FRAME_LEN {
            return false;
        }
        let mut i = 0;
        while i < FRAME_LEN {
            self.buf[self.tail] = bytes[i];
            self.tail = (self.tail + 1) % RING;
            self.len += 1;
            i += 1;
        }
        true
    }
}

#[derive(Clone, Copy)]
struct Held {
    bytes: [u8; FRAME_LEN],
    control: bool,
}

struct FaceInner<T> {
    port: T,
    assembler: FrameAssembler,
    control: Ring,
    payload: Ring,
    /// A decoded frame the ring could not take. Kept so the next poll
    /// does not tear it or read further from the UART.
    pending: Option<Held>,
}

impl<T: ByteTransport> FaceInner<T> {
    fn store(&mut self, held: Held) -> bool {
        if held.control {
            self.control.push_frame(held.bytes)
        } else {
            self.payload.push_frame(held.bytes)
        }
    }

    fn ingest(&mut self) -> Result<(), FaceError<T::Error>> {
        if let Some(held) = self.pending {
            if self.store(held) {
                self.pending = None;
            } else {
                return Ok(());
            }
        }
        loop {
            match self.port.read_byte() {
                Ok(None) => return Ok(()),
                Ok(Some(byte)) => {
                    let Some(result) = self.assembler.push(byte) else {
                        continue;
                    };
                    let held = Held {
                        bytes: match &result {
                            Ok(frame) => frame.to_bytes(),
                            Err(_) => self.assembler.last_bytes(),
                        },
                        control: matches!(
                            result,
                            Ok(frame)
                                if matches!(frame.frame_type(), FrameType::Ack | FrameType::Nack)
                        ),
                    };
                    if !self.store(held) {
                        self.pending = Some(held);
                        return Ok(());
                    }
                }
                Err(e) => return Err(FaceError::Port(e)),
            }
        }
    }
}

/// Demux one physical [`ByteTransport`] into Pump TX/RX ends.
///
/// Interior mutability lets [`FaceTx`] and [`FaceRx`] share the port.
pub struct LinkFace<T> {
    inner: RefCell<FaceInner<T>>,
}

impl<T: ByteTransport> LinkFace<T> {
    /// Wrap a physical port (your UART `ByteTransport`, radio, …).
    pub const fn new(port: T) -> Self {
        LinkFace {
            inner: RefCell::new(FaceInner {
                port,
                assembler: FrameAssembler::resyncing(),
                control: Ring::new(),
                payload: Ring::new(),
                pending: None,
            }),
        }
    }

    /// Borrow the sender end and the receiver end.
    pub fn split(&self) -> (FaceTx<'_, T>, FaceRx<'_, T>) {
        (FaceTx { face: self }, FaceRx { face: self })
    }

    /// Stop-and-wait [`Pump`] on this face.
    pub fn pump(&self) -> Pump<FaceTx<'_, T>, FaceRx<'_, T>> {
        let (tx, rx) = self.split();
        Pump::on(tx, rx)
    }

    /// [`Self::pump`] with an explicit [`RetryPolicy`].
    pub fn pump_with(&self, policy: RetryPolicy) -> Pump<FaceTx<'_, T>, FaceRx<'_, T>> {
        let (tx, rx) = self.split();
        Pump::on_with(tx, rx, policy)
    }

    /// Turn-taking pump: both peers send, one session at a time.
    ///
    /// `first` on exactly one peer. `N` is that peer's outbound queue.
    pub fn turn<const N: usize>(&self, first: bool) -> Turn<FaceTx<'_, T>, FaceRx<'_, T>, N> {
        Turn::new(self.pump(), first)
    }

    /// Hardware path: [`Turn`] plus the selective-repeat window of 8.
    ///
    /// One peer opens `START`. DATA frames fill the window, then `FINISH`.
    /// The other peer answers on the next turn. `N` is that peer's queue.
    /// P2P hello is not required — this is the UART / SPI / radio entry.
    pub fn window_turn<const N: usize>(
        &self,
        first: bool,
    ) -> WindowTurn<FaceTx<'_, T>, FaceRx<'_, T>, N> {
        let (tx, rx) = self.split();
        WindowTurn::new(crate::pump::WindowedPump::on(tx, rx), first)
    }

    /// Firmware path: pages of at most `N` bytes, then one status byte.
    ///
    /// The listener must [`PageLink::ack`] after each page. Without that
    /// byte the speaker's next [`PageLink::push_page`] stays at zero.
    pub fn page<const N: usize>(&self, first: bool) -> PageLink<FaceTx<'_, T>, FaceRx<'_, T>, N> {
        PageLink::new(self.window_turn(first))
    }

    /// Windowed pump for [`crate::PeerLink`] (`N = MAX_WINDOW`, limit 1 until hello).
    pub fn link_pump(&self) -> WindowedPump<FaceTx<'_, T>, FaceRx<'_, T>, MAX_WINDOW> {
        let (tx, rx) = self.split();
        let mut p = WindowedPump::on(tx, rx);
        p.set_window_limit(1);
        p
    }

    /// Access the wrapped port (e.g. to reconfigure baud).
    pub fn get_mut(&mut self) -> &mut T {
        &mut self.inner.get_mut().port
    }
}

/// TX half of a [`LinkFace`]: writes frames out; reads ACK/NACK.
pub struct FaceTx<'a, T> {
    face: &'a LinkFace<T>,
}

/// RX half of a [`LinkFace`]: writes ACK/NACK out; reads DATA/control frames.
pub struct FaceRx<'a, T> {
    face: &'a LinkFace<T>,
}

/// Error from a [`LinkFace`] port.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FaceError<E> {
    /// Underlying [`ByteTransport`] failed.
    Port(E),
    /// Demux ring had no room (should not happen with a cooperative poller).
    Full,
}

impl<E: fmt::Debug> fmt::Display for FaceError<E> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FaceError::Port(e) => write!(f, "link face: port error {e:?}"),
            FaceError::Full => write!(f, "link face: demux ring full"),
        }
    }
}

impl<T: ByteTransport> ByteTransport for FaceTx<'_, T> {
    type Error = FaceError<T::Error>;

    fn write_byte(&mut self, byte: u8) -> Result<(), Self::Error> {
        let mut g = self.face.inner.borrow_mut();
        g.port.write_byte(byte).map_err(FaceError::Port)
    }

    fn read_byte(&mut self) -> Result<Option<u8>, Self::Error> {
        let mut g = self.face.inner.borrow_mut();
        g.ingest()?;
        Ok(g.control.pop())
    }
}

impl<T: ByteTransport> ByteTransport for FaceRx<'_, T> {
    type Error = FaceError<T::Error>;

    fn write_byte(&mut self, byte: u8) -> Result<(), Self::Error> {
        let mut g = self.face.inner.borrow_mut();
        g.port.write_byte(byte).map_err(FaceError::Port)
    }

    fn read_byte(&mut self) -> Result<Option<u8>, Self::Error> {
        let mut g = self.face.inner.borrow_mut();
        g.ingest()?;
        Ok(g.payload.pop())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::protocol::Frame;
    use crate::test_support::MockTransport;

    #[test]
    fn ack_goes_to_tx_data_goes_to_rx() {
        let mut incoming = [0u8; 8];
        incoming[..4].copy_from_slice(&Frame::data(0, 0x42).to_bytes());
        incoming[4..].copy_from_slice(&Frame::ack(0).to_bytes());
        let face = LinkFace::new(MockTransport::with_incoming(&incoming));
        let (mut tx, mut rx) = face.split();

        let mut data = [0u8; 4];
        let mut i = 0;
        while i < 4 {
            data[i] = match rx.read_byte() {
                Ok(Some(b)) => b,
                _ => 0,
            };
            i += 1;
        }
        assert_eq!(data, Frame::data(0, 0x42).to_bytes());

        let mut ack = [0u8; 4];
        i = 0;
        while i < 4 {
            ack[i] = match tx.read_byte() {
                Ok(Some(b)) => b,
                _ => 0,
            };
            i += 1;
        }
        assert_eq!(ack, Frame::ack(0).to_bytes());
    }

    #[test]
    fn crc_miss_reaches_rx_not_tx() {
        let mut bad = Frame::data(0, 0x42).to_bytes();
        bad[3] ^= 0xFF;
        let face = LinkFace::new(MockTransport::with_incoming(&bad));
        let (mut tx, mut rx) = face.split();

        let mut got = [0u8; 4];
        let mut i = 0;
        while i < 4 {
            got[i] = match rx.read_byte() {
                Ok(Some(b)) => b,
                _ => 0,
            };
            i += 1;
        }
        assert_eq!(got, bad);
        assert_eq!(tx.read_byte(), Ok(None));
    }

    #[test]
    fn writes_reach_the_physical_port() {
        let mut face = LinkFace::new(MockTransport::with_incoming(&[]));
        {
            let (mut tx, mut rx) = face.split();
            assert_eq!(tx.write_byte(0xAA), Ok(()));
            assert_eq!(rx.write_byte(0xBB), Ok(()));
        }
        assert_eq!(face.get_mut().written(), &[0xAA, 0xBB]);
    }

    #[test]
    fn a_full_ring_keeps_the_next_frame_whole() {
        const N: usize = 17;
        struct Script {
            buf: [u8; N * 4],
            pos: usize,
        }
        impl ByteTransport for Script {
            type Error = ();
            fn write_byte(&mut self, _: u8) -> Result<(), Self::Error> {
                Ok(())
            }
            fn read_byte(&mut self) -> Result<Option<u8>, Self::Error> {
                if self.pos >= self.buf.len() {
                    return Ok(None);
                }
                let byte = self.buf[self.pos];
                self.pos += 1;
                Ok(Some(byte))
            }
        }

        let mut raw = [0u8; N * 4];
        let mut i = 0;
        while i < N {
            let frame = Frame::data(i as u8, i as u8).to_bytes();
            raw[i * 4..i * 4 + 4].copy_from_slice(&frame);
            i += 1;
        }
        let face = LinkFace::new(Script { buf: raw, pos: 0 });
        let (_tx, mut rx) = face.split();
        let mut got = [0u8; N * 4];
        let mut n = 0;
        while n < got.len() {
            match rx.read_byte() {
                Ok(Some(byte)) => {
                    got[n] = byte;
                    n += 1;
                }
                other => panic!("short read at {n}: {other:?}"),
            }
        }
        assert_eq!(got, raw);
    }
}