rhdl_dsig_scalable_core/

msg_reader.rs

//! Read 16-byte messages from HBM and deal them to the [`SLICES`] slices.
//!
//! # The problem
//!
//! Every signature signs one message, and the messages start out in HBM,
//! written there by the host before the run. The [slices](crate::slice) need
//! them one at a time, each slice at its own pace, and every resulting frame
//! must be traceable back to the exact message it signed. This module is the
//! single AXI4 read master (see [`crate::axi4`]) that fetches the messages
//! and hands them out like a card dealer.
//!
//! # The reasoning
//!
//! * **Fetch in bursts, deal one by one.** HBM is efficient with long bursts
//!   and inefficient with tiny reads. A message is only 16 bytes, so the
//!   reader fetches 16-beat (1 KiB, 64-message) bursts into a small block-RAM
//!   FIFO (first-in, first-out queue) and unpacks four messages from each
//!   64-byte beat.
//! * **Round-robin, in order.** Message `n` always goes to slice
//!   `n mod SLICES`. The rule is fixed, so the host knows in advance which
//!   slice's frame region will hold each signature, and no tag or arbiter is
//!   needed. Because `SLICES` is a power of two, `mod` is a bit mask
//!   (`SLICE_MASK`); RHDL kernels avoid `/` and `%`.
//! * **Credits instead of backpressure.** A read address is issued only when
//!   the FIFO has room for the whole burst. Data that the reader asked for
//!   therefore always fits, and `rready` can be tied high. That is simpler
//!   and safer than stalling the R channel.
//!
//! # How it works
//!
//! The host writes `count` messages back to back starting at `base` (4 KiB
//! aligned). Each 64-byte beat holds four messages. Message `n` goes to slice
//! `n mod SLICES`, carrying its index `n`, which the slice writes into the frame
//! padding so the host can check every frame against the right message.
//!
//! ```text
//!   HBM ──16-beat bursts──▶ beat FIFO (64 beats, credit-limited) ──▶ unpack 4/beat
//!                                                                     │ msg n
//!                                               slice (n mod SLICES) buffer ◀┘
//! ```
//!
//! Read addresses are issued only while the FIFO has room for the whole burst,
//! so read data can always be accepted (`rready` is constant high). A slice
//! buffer holds one message; dealing stalls when the target slice's buffer is
//! still full, which keeps messages strictly in order.
//!
//! # Four counters track every beat
//!
//! All bookkeeping is in *beats* (64 bytes = 4 messages) except `dealt`,
//! which counts messages:
//!
//! ```text
//!   consumed ≤ received ≤ requested ≤ ceil(count / 4)
//!
//!   requested − consumed   beats the FIFO has promised room for (≤ 64)
//!   received − consumed    beats sitting in the FIFO, ready to unpack
//!   lane                   which of the 4 messages in the head beat is next
//!   dealt                  messages handed to slices = index of the next one
//! ```
//!
//! The FIFO is a 64-entry ring of 64-byte words: the low 6 bits of
//! `received` are the write slot and the low 6 bits of `consumed` the read
//! slot, so the ring wraps for free.
//!
//! # Timing
//!
//! The block-RAM FIFO has one clock of read latency. Moving a beat into the
//! `head` register therefore takes two steps: a cycle that sets
//! `read_pending`, then a cycle that captures the RAM output. After that the
//! dealer can hand out at most one message per clock, so one beat (4
//! messages) is unpacked in 4 clocks when the target slices are free. A
//! slice consumes a message far less often than that (one key per 68 clocks,
//! see [`crate::slice_schedule`]), so the reader is not the bottleneck.
//!
//! # Neighbours
//!
//! [`crate::engine`] supplies `base`, `count` and `run` from its registers,
//! forwards the AXI read channel, and wires each slice's `message_taken`
//! back here as `taken`. The [`Message`] type, and the rule that a message
//! is held until taken, come from [`crate::slice_signer`]. The `dealt` count
//! is the host-visible `DEALT` register and `error` is `FAULT` bit 1.

use crate::axi4::{RESP_OKAY, ReadRequest, ReadResponse};
use crate::cert_unit::SLICES;
use crate::slice_signer::Message;
use rhdl::prelude::*;
use rhdl_fpga::core::{
    dff::DFF,
    ram::synchronous::{In as RamIn, SyncBRAM, Write as RamWrite},
};

/// `SLICES − 1`, the mask for `n mod SLICES`.
///
/// 3 bits wide because the largest build has 8 slices (slice numbers 0..=7).
/// `n & SLICE_MASK` equals `n mod SLICES` only because `SLICES` is a power of
/// two (2, 4 or 8).
const SLICE_MASK: b3 = b3((SLICES - 1) as u128);

/// Beats per read burst (1 KiB).
///
/// 16 beats × 64 bytes = 1 KiB = 64 messages. Bursts start at
/// `base + 64 · requested`, and `requested` advances by 16 except for the
/// final, shorter burst, so with a 4 KiB-aligned base no burst crosses a
/// 4 KiB page.
pub const BURST_BEATS: usize = 16;
/// Beat FIFO capacity.
///
/// 64 beats (4 KiB, 256 messages), which is the 2⁶ entries addressed by the
/// FIFO's 6-bit address. It holds four full bursts, so one burst can be in
/// flight from HBM while earlier ones are still being dealt.
pub const FIFO_BEATS: usize = 64;

/// Reader inputs, sampled every clock.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct ReaderInput {
    /// Byte address of message 0 (4 KiB aligned; 64 bits). Host argument
    /// `messages`.
    pub base: b64,
    /// Number of messages to read (32 bits). Host argument `count`; it need
    /// not be a multiple of 4.
    pub count: b32,
    /// Start reading (1 bit). High while the engine is running; no read
    /// address is issued while it is low.
    pub run: bool,
    /// Memory read channel signals (AR `ready` and the R channel).
    pub memory: ReadResponse,
    /// Each slice consumed its buffered message this cycle (one bit per
    /// slice). This frees that slice's one-message buffer.
    pub taken: [bool; SLICES],
}

/// Reader outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct ReaderOutput {
    /// Memory read channel signals (AR and `rready`).
    pub memory: ReadRequest,
    /// The buffered message offered to each slice. `valid` is high while the
    /// buffer is full; the slice holds off until it is ready, then pulses
    /// `taken`.
    pub messages: [Message; SLICES],
    /// Messages dealt to slices so far (32 bits; the host's `DEALT`
    /// register).
    pub dealt: b32,
    /// A read response was not OKAY (sticky until reset).
    pub error: bool,
}

/// Resettable control.
///
/// Every field here must start from a known value after reset, so it lives in
/// a register with a reset value (all zero / false).
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct ReaderControl {
    /// Beats requested (32 bits): sum of the burst lengths whose AR transfer
    /// has happened.
    pub requested: b32,
    /// Beats received (32 bits): R transfers written into the FIFO. Its low
    /// 6 bits are the FIFO write slot.
    pub received: b32,
    /// Beats fully unpacked (32 bits). Its low 6 bits are the FIFO read slot.
    pub consumed: b32,
    /// Message within the current beat (0..=3, 2 bits): the beat's 16-byte
    /// lane that will be dealt next.
    pub lane: b2,
    /// The FIFO output register holds beat `consumed`, copied into `head`.
    pub head_valid: bool,
    /// A FIFO read is outstanding: the RAM's output will be valid next clock.
    pub read_pending: bool,
    /// Messages dealt (32 bits). Also the index of the next message, which
    /// picks its slice (`dealt mod SLICES`).
    pub dealt: b32,
    /// Slice buffers occupied (one bit per slice).
    pub full: [bool; SLICES],
    /// Error seen (sticky): some R beat came back not OKAY.
    pub error: bool,
}

/// Resetless data.
///
/// Wide data registers do not need a reset value, because the control bits
/// above say whether they hold anything meaningful. Skipping the reset saves
/// routing and logic on hundreds of bits.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct ReaderData {
    /// Beat being unpacked (64 bytes); meaningful while `head_valid`.
    pub head: [b8; 64],
    /// Buffered message per slice; meaningful while that slice's `full` bit
    /// is set.
    pub buffers: [Message; SLICES],
}

/// The message reader and dealer.
///
/// Three clocked children: the beat FIFO in block RAM, the resettable control
/// register and the resetless data register. The per-clock logic is
/// [`message_reader_kernel`].
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct MessageReader {
    /// 64 × 512-bit synchronous block RAM (6-bit address): the beat FIFO.
    fifo: SyncBRAM<[b8; 64], 6>,
    /// Counters, flags and slice-buffer occupancy ([`ReaderControl`]).
    control: DFF<ReaderControl>,
    /// The head beat and the per-slice message buffers ([`ReaderData`]).
    data: DFF<ReaderData>,
}

/// A fresh reader: empty FIFO, zero counters, data registers left undefined
/// ("don't care") because nothing reads them until a control bit says so.
impl Default for MessageReader {
    fn default() -> Self {
        Self {
            fifo: SyncBRAM::default(),
            control: DFF::new(ReaderControl::default()),
            data: DFF::resetless(),
        }
    }
}

/// Binds the reader's input and output types to its kernel.
impl SynchronousIO for MessageReader {
    type I = ReaderInput;
    type O = ReaderOutput;
    type Kernel = message_reader_kernel;
}

/// The reader's logic.
///
/// Runs once per clock and has four parts, in the order of a message's
/// journey: issue read addresses (AR), store returned beats in the FIFO
/// (R → FIFO), free slice buffers that were taken, and unpack the head beat
/// into the next slice's buffer (unpack + deal).
///
/// * Inputs: `clock_reset`, the [`ReaderInput`] (host settings, memory
///   signals, per-slice `taken`), and `q`, the current FIFO output, control
///   and data registers.
/// * Outputs: the [`ReaderOutput`] and `MessageReaderD`, the next register
///   values plus this clock's FIFO read and write ports.
/// * Timing: a message dealt in cycle `t` appears as `valid` to its slice in
///   cycle `t + 1` (the outputs come from registers); a slice's `taken` in
///   cycle `t` lets a new message be dealt into its buffer in cycle `t + 1`.
#[allow(clippy::needless_range_loop)]
#[kernel]
pub fn message_reader_kernel(
    clock_reset: ClockReset,
    input: ReaderInput,
    q: MessageReaderQ,
) -> (ReaderOutput, MessageReaderD) {
    // High during reset: no `valid` may be raised then.
    let resetting = clock_reset.reset.any();
    // Next control and data values; start from the current ones and edit.
    let mut c = q.control;
    let mut data = q.data;
    // Beats needed: ceil(count / 4).
    let total_beats = (input.count + b32(3)) >> 2;

    // ---------------------------------------------------- AR
    // Beats already promised FIFO space (requested but not yet unpacked).
    let in_fifo = q.control.requested - q.control.consumed;
    // A whole burst still fits: this is the credit check that lets `rready`
    // stay high.
    let room = in_fifo <= b32((FIFO_BEATS - BURST_BEATS) as u128);
    // Some beats of the message buffer have not been asked for yet.
    let more = q.control.requested < total_beats;
    let arvalid = input.run && room && more && !resetting;
    // Length of the next burst: 16 beats, or whatever is left at the end.
    let remaining = total_beats - q.control.requested;
    let burst: b32 = if remaining < b32(BURST_BEATS as u128) {
        remaining
    } else {
        b32(BURST_BEATS as u128)
    };
    if arvalid && input.memory.arready {
        c.requested = q.control.requested + burst;
    }
    // Byte address of beat `requested`: base + 64 · requested (shift by 6).
    let araddr = input.base + (q.control.requested.resize::<64>() << 6);

    // ---------------------------------------------------- R → FIFO
    // Every arriving beat is written; space was reserved when it was asked for.
    let write = input.memory.rvalid && !resetting;
    if write {
        c.received = q.control.received + b32(1);
        if input.memory.rresp != RESP_OKAY {
            c.error = true;
        }
    }
    // FIFO write slot: low 6 bits of the received count (a 64-entry ring).
    let write_address: b6 = q.control.received.resize();

    // ---------------------------------------------------- slice buffers
    // A slice that took its message this cycle has an empty buffer next cycle.
    let mut full = q.control.full;
    for s in 0..SLICES {
        if input.taken[s] {
            full[s] = false;
        }
    }

    // ---------------------------------------------------- unpack + deal
    // FIFO read slot: by default keep reading beat `consumed`.
    let mut read_address: b6 = q.control.consumed.resize();
    // Refill the head register in two steps because the block RAM answers one
    // clock after it is addressed: first mark a read pending, then capture.
    if q.control.read_pending {
        data.head = q.fifo;
        c.head_valid = true;
        c.read_pending = false;
    } else if !q.control.head_valid && q.control.received > q.control.consumed {
        c.read_pending = true;
    }
    // Deal one message per clock while a head beat is loaded and messages remain.
    if q.control.head_valid && q.control.dealt < input.count {
        // SLICES is a power of two, so `n mod SLICES` is a mask.
        let target: b3 = q.control.dealt.resize::<3>() & SLICE_MASK;
        // Is the target slice's buffer empty? (Uses last cycle's `full`, so a
        // buffer freed this cycle is refilled next cycle.)
        let mut free = false;
        for s in 0..SLICES {
            if target == b3(s as u128) && !q.control.full[s] {
                free = true;
            }
        }
        // If it is not free we simply wait: skipping ahead to another slice
        // would break the fixed `n mod SLICES` order.
        if free {
            // Pick the 16-byte lane `lane` out of the 64-byte head beat. RHDL
            // needs constant array indices, so loop over all four lanes and
            // keep the one that matches.
            // Bytes past 16 stay zero: the HBM batch engine reads 16-byte messages
            // (its exporter refuses profile 2).
            let mut bytes = [b8(0); crate::MESSAGE_BYTES];
            for l in 0..4 {
                if q.control.lane == b2(l as u128) {
                    for b in 0..16 {
                        bytes[b] = q.data.head[16 * l + b];
                    }
                }
            }
            // The message carries its global index so the frame can name it.
            let message = Message {
                valid: true,
                bytes,
                index: q.control.dealt.resize(),
            };
            // Store it in the target slice's buffer and mark the buffer full.
            for s in 0..SLICES {
                if target == b3(s as u128) {
                    data.buffers[s] = message;
                    full[s] = true;
                }
            }
            c.dealt = q.control.dealt + b32(1);
            // 2-bit lane wraps from 3 back to 0 on its own.
            c.lane = q.control.lane + b2(1);
            // The beat is finished after its 4th message, or early if this was
            // the very last message: retire it and point the FIFO at the next.
            if q.control.lane == b2(3) || q.control.dealt + b32(1) == input.count {
                c.head_valid = false;
                c.consumed = q.control.consumed + b32(1);
                read_address = (q.control.consumed + b32(1)).resize();
            }
        }
    }
    c.full = full;
    // Offer each slice its registered buffer; `valid` is the registered full
    // bit, forced low during reset.
    let mut messages = q.data.buffers;
    for s in 0..SLICES {
        messages[s].valid = q.control.full[s] && !resetting;
    }

    // Next state plus this clock's FIFO ports (read slot, and the write of
    // any arriving beat).
    let d = MessageReaderD {
        fifo: RamIn::<[b8; 64], 6> {
            read_addr: read_address,
            write: RamWrite::<[b8; 64], 6> {
                addr: write_address,
                value: input.memory.rdata,
                enable: write,
            },
        },
        control: c,
        data,
    };
    (
        ReaderOutput {
            memory: ReadRequest {
                arvalid,
                araddr,
                // AXI encodes the beat count minus one.
                arlen: (burst - b32(1)).resize(),
                // Always ready: the credit check above reserved the space.
                rready: true,
            },
            messages,
            dealt: q.control.dealt,
            error: q.control.error,
        },
        d,
    )
}