rhdl_dsig_scalable_core/

hbm_writer.rs

//! Write a slice's frames into HBM, one 26-beat burst per frame.
//!
//! # The problem
//!
//! Each [slice](crate::slice) produces finished signatures as a stream of
//! 64-byte *frame beats* ([`FrameBeat`]): 26 beats make one frame, the
//! 1,642-byte signature plus the message index, padded. Those frames must end
//! up in HBM where the host can read them back and verify them. Something has
//! to turn "here is a beat" into legal AXI4 write bursts (see
//! [`crate::axi4`]), and it has to say honestly how many frames actually
//! landed.
//!
//! # The reasoning
//!
//! * **Where does frame `f` go?** Frame `f` of a slice lands at
//!   `base + f · 2048`: a 2 KiB stride keeps every burst inside one 4 KiB page
//!   as AXI requires, and needs no multiplier. The host reads the first
//!   1,664 bytes of each 2 KiB slot. (26 beats × 64 bytes = 1,664 bytes; the
//!   rest of the slot is unused.) Multiplying by 2,048 is just a left shift
//!   by [`FRAME_STRIDE_LOG2`] = 11 bits, which costs no logic.
//! * **One HBM port per slice.** Every slice owns one writer and one HBM
//!   port, so frame writes scale with the slice count and slices never
//!   compete for a port (the planner's "frame writes" stage in
//!   [`crate::config`]).
//! * **Count responses, not beats.** A beat that left the kernel may still
//!   fail in memory. Only the B (write response) channel says the data is in
//!   HBM, so that is what [`WriterOutput::frames_written`] counts and what the
//!   engine waits for before it declares the run done.
//!
//! # How it works
//!
//! ```text
//!   signer beats ──▶ [W] ──wvalid/wready──▶ HBM
//!                     ▲ only after its AW
//!   frame counter ──▶ [AW] base + f << 11, awlen = 25
//!   [B] count responses; any non-OKAY response sets `error`
//! ```
//!
//! The address for frame `f` is issued when the frame's first beat is waiting,
//! and data beats of frame `f` flow only after that address was accepted, so
//! the master never promises data it does not have. At most
//! [`MAX_OUTSTANDING`] bursts await responses. `frames_written` counts frames
//! whose write response came back OKAY; that, not beats sent, is what the run
//! is measured on. (Precisely: it counts every write response, and any
//! response that was not OKAY also sets the sticky `error` flag, which the
//! engine reports in its `FAULT` register. A run with no fault therefore has
//! every counted frame acknowledged OKAY.)
//!
//! # Three counters, one invariant
//!
//! The whole writer is three 32-bit frame counters and an error bit
//! ([`WriterState`]). Because every frame is exactly one burst, each AXI
//! channel's progress is just "how many frames has it finished":
//!
//! ```text
//!   b_frames  ≤  w_frames  ≤  aw_frames  ≤  b_frames + MAX_OUTSTANDING
//!   (answered)   (all beats   (address
//!                 sent)        accepted)
//!
//!   aw_frames == w_frames  → the next frame still needs its address
//!   aw_frames >  w_frames  → the current frame's address is out; send beats
//!   aw_frames − b_frames   → bursts awaiting a response (capped at 16)
//! ```
//!
//! Because an address is only requested once a beat is waiting, and at most
//! one address runs ahead of the data, `aw_frames` is at most one ahead of
//! `w_frames`.
//!
//! # Timing
//!
//! Everything is combinational from the current state and inputs to the
//! outputs, with the counters updated at the clock edge. So a beat that is
//! valid with an address already accepted goes out the same cycle `wready` is
//! high, and a whole frame can stream at one beat per clock (26 clocks) once
//! its address is accepted.
//!
//! # Neighbours
//!
//! The beats come from [`crate::slice_signer`] (through [`crate::slice`]);
//! the `beat_ready` answer goes back to it. [`crate::engine`] instantiates
//! one writer per slice, gives each its `base` address from the host
//! registers, sums `frames_written` to decide when the run is done, and ORs
//! the `error` bits into `FAULT` bit 0.

use crate::axi4::{RESP_OKAY, WriteRequest, WriteResponse};
use crate::slice_signer::{FRAME_BEATS, FrameBeat};
use rhdl::prelude::*;
use rhdl_fpga::core::dff::DFF;

/// Bursts in flight before the master waits for responses.
///
/// HBM answers a write burst some cycles after its last beat. If the writer
/// waited for each answer before starting the next frame it would idle for
/// that whole round trip; allowing up to 16 unanswered bursts hides the
/// latency. The cap bounds how far the writer can run ahead of writes the
/// memory has confirmed.
pub const MAX_OUTSTANDING: usize = 16;
/// log2 of the frame stride in bytes (2 KiB).
///
/// Frame `f` starts at `base + (f << 11)`. A power-of-two stride turns the
/// address multiply into a free wire shift, and 2 KiB divides 4 KiB, so a
/// 1,664-byte frame never crosses a 4 KiB AXI page.
pub const FRAME_STRIDE_LOG2: usize = 11;

/// Writer inputs, sampled every clock.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct WriterInput {
    /// Base byte address of this slice's frame region (2 KiB aligned; 64
    /// bits). Set by the host through the engine's `frames{s}` argument and
    /// held constant for the whole run.
    pub base: b64,
    /// Frame beats from the signer: `valid`, 64 data bytes and `last` (set on
    /// the 26th beat of a frame).
    pub beat: FrameBeat,
    /// Channel signals from memory (the `ready`s and the B response).
    pub memory: WriteResponse,
}

/// Writer outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct WriterOutput {
    /// Channel signals to memory (AW, W and `bready`).
    pub memory: WriteRequest,
    /// The presented beat was accepted (1 bit). The signer must hold the same
    /// beat until it sees this high, then present the next one.
    pub beat_ready: bool,
    /// Frames acknowledged OKAY (32 bits; see the module notes for the exact
    /// meaning). Read by the host per slice as `FRAMES[s]`.
    pub frames_written: b32,
    /// A write response was not OKAY (sticky until reset).
    pub error: bool,
}

/// Writer state (all resettable; small).
///
/// Only counters live here, no data: the 64-byte beat goes straight from the
/// signer to the W channel, so the state is 3 × 32 + 1 = 97 flip-flops and
/// the writer needs no RAM.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct WriterState {
    /// Addresses accepted (32 bits): frames whose AW transfer has happened.
    pub aw_frames: b32,
    /// Frames whose last beat was accepted (32 bits).
    pub w_frames: b32,
    /// Responses received (32 bits): B transfers seen.
    pub b_frames: b32,
    /// Error seen (sticky): some B response was not OKAY.
    pub error: bool,
}

/// The per-slice HBM write master.
///
/// An RHDL [`Synchronous`] component: a struct of clocked children (here one
/// register, `state`) plus a pure kernel function, [`hbm_writer_kernel`],
/// that computes outputs and next state every clock.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct HbmWriter {
    /// The three frame counters and the error bit, reset to zero.
    state: DFF<WriterState>,
}

/// A fresh writer: nothing addressed, written or answered.
impl Default for HbmWriter {
    fn default() -> Self {
        Self {
            state: DFF::new(WriterState::default()),
        }
    }
}

/// Binds the writer's input and output types to its kernel.
impl SynchronousIO for HbmWriter {
    type I = WriterInput;
    type O = WriterOutput;
    type Kernel = hbm_writer_kernel;
}

/// The writer's logic.
///
/// * Inputs: `clock_reset` (reset forces every `valid` low), the signer's
///   beat, the memory's `ready`s and B response, and `q`, the current
///   [`WriterState`].
/// * Outputs: the AXI4 write request, `beat_ready` back to the signer, the
///   acknowledged-frame count and the sticky error; plus `HbmWriterD`, the
///   next state.
/// * Timing: purely combinational within one cycle; the counters advance at
///   the next clock edge. `frames_written` and `error` are the registered
///   values, so they lag the B transfer by one clock.
#[kernel]
pub fn hbm_writer_kernel(
    clock_reset: ClockReset,
    input: WriterInput,
    q: HbmWriterQ,
) -> (WriterOutput, HbmWriterD) {
    // High during reset: no channel may claim `valid` then.
    let resetting = clock_reset.reset.any();
    // Current counters, and a copy we update to form the next state.
    let s = q.state;
    let mut next = s;
    // Bursts whose address was accepted but whose response has not arrived.
    let outstanding = s.aw_frames - s.b_frames;
    // Address of the frame whose beats are (or will next be) on the W channel.
    let need_address = s.aw_frames == s.w_frames && input.beat.valid;
    // AW step: ask for the address only when a beat is actually waiting and
    // fewer than MAX_OUTSTANDING bursts are unanswered.
    let awvalid = need_address && outstanding < b32(MAX_OUTSTANDING as u128) && !resetting;
    if awvalid && input.memory.awready {
        next.aw_frames = s.aw_frames + b32(1);
    }
    // W step: data may flow only once this frame's address has been accepted,
    // so we never put beats on W that the memory has no address for.
    let address_ready = s.aw_frames > s.w_frames;
    let wvalid = input.beat.valid && address_ready && !resetting;
    // The beat transfers this cycle (valid and ready both high).
    let accepted = wvalid && input.memory.wready;
    // The 26th beat closes the frame on W.
    if accepted && input.beat.last {
        next.w_frames = s.w_frames + b32(1);
    }
    // B step: `bready` is always high, so every response is counted the cycle
    // it appears; a bad code latches the error.
    if input.memory.bvalid {
        next.b_frames = s.b_frames + b32(1);
        if input.memory.bresp != RESP_OKAY {
            next.error = true;
        }
    }
    // Address of frame number `w_frames` (the next frame to be written):
    // base + w_frames · 2048, done as a shift.
    let awaddr = input.base + (s.w_frames.resize::<64>() << (FRAME_STRIDE_LOG2 as u128));
    (
        WriterOutput {
            memory: WriteRequest {
                awvalid,
                awaddr,
                // Every burst is one whole frame: 26 beats, encoded as 25.
                awlen: b8((FRAME_BEATS - 1) as u128),
                wvalid,
                wdata: input.beat.data,
                wlast: input.beat.last,
                // We can always count a response, so never stall B.
                bready: true,
            },
            // Tell the signer its beat went out, so it can present the next.
            beat_ready: accepted,
            frames_written: s.b_frames,
            error: s.error,
        },
        HbmWriterD { state: next },
    )
}