rhdl_dsig_scalable_core/

config.rs

//! The planner: predicts signatures per second and resources for every build
//! and picks the best one for a LUT budget.
//!
//! # The problem
//!
//! A Vivado run of this design takes hours. You cannot try every size of the
//! engine on real tools just to learn which one fits the chip and how fast it
//! signs. So before you build anything, you want a cheap answer to two
//! questions:
//!
//! 1. *Does this build fit?* (LUTs, block RAM, UltraRAM, DSPs.)
//! 2. *How many signatures per second will it make?*
//!
//! This module answers both with plain arithmetic. It takes costs that were
//! **measured once** on real place-and-route runs, multiplies them by how many
//! copies a build has, and compares the result with the device and with the
//! project's 420,000-LUT cap. Nothing here touches hardware; it is a
//! spreadsheet written in Rust.
//!
//! # The reasoning
//!
//! The engine is made of identical *slices* (see [`crate::slice`]). Each slice
//! is one complete signer. So the cost of a build is close to linear:
//! `slices × (cost of one slice) + (things that exist once)`. The "things that
//! exist once" are the Ed25519 certificate core ([`crate::ed25519`]) and the
//! engine glue (the certificate unit, control and HBM I/O in
//! [`crate::engine`]).
//!
//! The one big lever besides the slice count is where the AES S-boxes live.
//! (An S-box is the 256-entry byte-substitution table at the heart of AES;
//! Haraka-512 is built from AES rounds.) A slice has three Haraka lanes
//! ([`crate::chain_step`]) with 494 live S-boxes each. In LUTs an S-box costs
//! roughly 32 LUTs (an estimate, see [`LUTS_PER_LUT_SBOX`]); in block RAM or
//! UltraRAM it costs one memory instead. LUTs are the scarce budget, and the
//! U280 has RAM that the design does not otherwise use. So moving S-boxes
//! into spare RAM buys LUTs, which can buy more slices.
//!
//! # The decision
//!
//! Model only the choices that matter (slices: 2, 4 or 8; S-boxes per lane in
//! UltraRAM and block RAM), list the two sensible placements per slice count
//! (all-LUT and RAM-filled, see [`Build::all`]), and pick the fastest one
//! that fits ([`best`]). The binary `dsig_plan` prints the answer; the chip
//! planner component in `planner.rs` (Cargo feature `planner`) reuses these
//! same constants.
//!
//! ```text
//!   measured per-block costs ──┐
//!   (SLICE_LUT, ED25519_LUT,   │
//!    GLUE_LUT, ...)            ▼
//!                       ┌──────────────┐   Resources   ┌──────────┐
//!   Build {slices,  ──▶ │ resources()  │ ────────────▶ │ fits(%)  │──┐
//!     uram, bram}       └──────────────┘               └──────────┘  │
//!        │              ┌───────────────────────────┐                ▼
//!        └────────────▶ │ signatures_per_second(f)  │ ──▶  best(): fastest
//!                       │ = min(slices, certs,      │      build that fits,
//!                       │       frame writes)       │      ties → fewer LUTs
//!                       └───────────────────────────┘
//! ```
//!
//! A [`Build`] is a slice count (`DSIG_SLICES=2|4|8`) plus where each
//! lane's 494 live AES S-boxes live: UltraRAM, block RAM or LUTs
//! (`DSIG_SBOX_PLACEMENT`, see [`sbox_placement`](crate::sbox_placement)).
//! Budgets are percentages of [`LUT_CAP`] (420,000 CLB LUTs, the budget DSig
//! and Ed25519 share for the comparison).
//!
//! # Throughput model
//!
//! [`Build::signatures_per_second`] is the slowest of these stages:
//!
//! | Stage | Signatures per second | Why |
//! |---|---|---|
//! | slices | `SLICES × f / 68` | each slice makes one key per 68-cycle period ([`slice_schedule`](crate::slice_schedule)) |
//! | certificates | `128 × f / 895` | the Ed25519 core finishes one batch per ~895 cycles with ≥ 32 in flight |
//! | frame writes | `SLICES × port bandwidth / 2,048 B` | one HBM port per slice, 64 B per clock |
//!
//! times [`STEADY_STATE_EFFICIENCY`], the fraction of the slice ceiling that
//! the cycle-accurate throughput test measures in steady state.
//!
//! # Resource model
//!
//! Per-block costs come from Vivado 2023.2 out-of-context place-and-route on
//! the U280 part (`xcu280-fsvh2892-2L-e`), except where a field says
//! *estimate*:
//!
//! | Block | CLB LUT | Source |
//! |---|---:|---|
//! | Slice, all S-boxes in LUTs | 127,502 | first routed `slices-2` link, in context (59,946 of them LUT-RAM, mostly S-box ROMs) |
//! | Haraka chain-step lane | 23,902 | Vivado OOC routed |
//! | BLAKE3 lane | 16,422 | Vivado OOC routed |
//! | Ed25519SignCoreSmall | 25,383 | same link, in context (26,408 OOC) |
//! | Engine glue (cert unit's BLAKE3 lane, control, HBM I/O) | 20,564 | same link: kernel 301,037 − slices − Ed25519 |
//!
//! S-boxes placed in RAM go in dual-port pairs ([`SboxPair`](crate::aes_table::SboxPair)):
//! two per URAM, or two per BRAM18 (four per BRAM36).
//! Either way it frees about [`LUTS_PER_LUT_SBOX`] LUTs. That LUT figure is an
//! **estimate** (a 256 × 8 ROM is eight 8-input functions, four LUT6s each).
//! [`Build::fill`] places as many S-boxes as the device's spare UltraRAM and
//! block RAM allow, keeping [`RAM_HEADROOM`] of each free.
//!
//! # Worked example (the measured anchor)
//!
//! The all-LUT `slices-2` build is the one build that was actually routed, so
//! the model should reproduce it:
//!
//! ```text
//!   2 × SLICE_LUT      2 × 127,502 = 255,004
//! + ED25519_LUT                       25,383
//! + GLUE_LUT                          20,564
//! = kernel                           300,951  (routed link: 301,037)
//! ```
//!
//! `GLUE_LUT` was itself derived from that same link (kernel minus slices
//! minus Ed25519), so matching it is a consistency check, not an independent
//! validation. Every other build is an extrapolation from this one point plus
//! the S-box estimate.

// `fmt::Write` lets `sweep` append formatted lines to a `String` with
// `writeln!`; the `as _` import brings the trait in without naming it.
use std::fmt::Write as _;

// ------------------------------------------------------------ device limits
//
// These are fixed facts about the target chip (xcu280) and the project rules.
// Every build is checked against them in `Build::fits`.

/// Project LUT cap (100 %): the comparison budget shared with Ed25519.
///
/// Unit: CLB LUTs. All `--lut` percentages in `dsig_plan` are percentages of
/// this number, not of the whole device. It exists so DSig and the Ed25519
/// baseline are compared at the same area.
pub const LUT_CAP: u32 = 420_000;
/// Design clock in MHz.
///
/// The kernel is linked at 205 MHz. Every rate in this module is "work per
/// clock times this clock", so a slower clock scales every rate down by the
/// same factor.
pub const DESIGN_MHZ: f64 = 205.0;
/// Physical BRAM36 tiles of the xcu280.
///
/// A BRAM36 is one 36-kbit block RAM tile; it can also be used as two BRAM18
/// halves. Kept as `f64` because the model counts half tiles.
pub const DEVICE_BRAM36: f64 = 2_016.0;
/// BRAM36 tiles a kernel can actually use: the platform's dynamic region.
///
/// Vivado's DRC for build v4 reported 3,552 BRAM18 sites in
/// `pblock_dynamic_region` (the rest belong to the static shell), i.e. 1,776
/// BRAM36. Every fit check uses this, not [`DEVICE_BRAM36`]: build v4 was
/// sized against the device and failed placement.
pub const KERNEL_BRAM36: f64 = 1_776.0;
/// Physical UltraRAMs of the xcu280.
///
/// An UltraRAM (URAM) is a larger on-chip memory block. The key caches use
/// them, and spare ones can hold S-boxes.
pub const DEVICE_URAM: u32 = 960;
/// Physical DSP48E2 slices of the xcu280.
///
/// DSPs are hard multiply-add blocks. In this model only the Ed25519 core
/// uses them.
pub const DEVICE_DSP: u32 = 9_024;

// --------------------------------------------------------- throughput model

/// Cycles per key in one slice (the modulo schedule's period).
///
/// Unit: clock cycles. A slice finishes one one-time key every 68 cycles (see
/// [`crate::slice_schedule`]), and each key signs exactly one message, so one
/// slice makes at most `f / 68` signatures per second.
pub const KEY_PERIOD: f64 = 68.0;
/// Measured Ed25519 cycles per signature with ≥ 32 requests in flight.
///
/// Unit: clock cycles per Ed25519 signature. One Ed25519 signature certifies
/// a whole batch of 128 keys, so the certificate ceiling is `128 × f / 895`.
pub const ED25519_CYCLES_PER_SIGN: f64 = 895.0;
/// Bytes written per signature (one 2 KiB frame slot, 26 beats used).
///
/// Unit: bytes. A beat is one 64-byte HBM write. The 1,642-byte signature
/// plus its message index needs 26 beats; the rest of the 2 KiB slot is not
/// written, so only 26 × 64 bytes count against port bandwidth.
pub const FRAME_BYTES: f64 = 26.0 * 64.0;
/// Fraction of the slice ceiling reached in steady state. Set from the
/// cycle-accurate throughput test (`tests/throughput.rs`); 1.0 until measured.
///
/// Unit: a ratio in `0.0..=1.0`. It is the correction between the ideal
/// "one key per 68 cycles" and what the simulated engine sustains. While it
/// is 1.0 the planner reports ceilings, not measured rates.
pub const STEADY_STATE_EFFICIENCY: f64 = 1.0;

// ----------------------------------------------------------- resource model

/// Measured slice cost with every S-box in LUTs (routed `slices-2` link).
///
/// Unit: CLB LUTs per slice. This is the largest term in the model.
pub const SLICE_LUT: f64 = 127_502.0;
/// BRAM36 tiles of one slice (caches in UltraRAM, S-boxes in LUTs), from two
/// kernel syntheses: build v3 used 202 tiles at 2 slices; build v5 used
/// 1,362.5 at 4 slices, of which 12 lanes × 88 are T-tables, leaving 306.5.
/// The difference, (306.5 − 202) / 2 ≈ 52 per slice, is the slice's FIFOs,
/// frame buffers and Merkle RAMs.
///
/// An earlier value, 11 (a routed link's 555 tiles minus the 544 its
/// block-RAM caches used), missed those buffers. Undercounting block RAM is
/// what sank build v4, so this figure errs high: with it the fixed part
/// (Ed25519 87 + glue 28 = 115) slightly exceeds what v3 implies (98).
///
/// Unit: BRAM36 tiles per slice.
pub const SLICE_BRAM36: f64 = 52.0;
/// UltraRAMs of one slice (4 banks × 18), Vivado-confirmed.
///
/// Unit: URAMs per slice. These hold the 512-key cache
/// ([`crate::cache_bank`]).
pub const SLICE_URAM: u32 = 72;
/// Haraka chain-step lanes per slice.
///
/// A lane is one pipelined Haraka-512 chain step ([`crate::chain_step`]).
/// Three in series finish a whole w = 4 chain per clock
/// ([`crate::slice_chain`]).
pub const LANES_PER_SLICE: u32 = 3;
/// Live S-boxes per lane.
///
/// The S-boxes left after the constant bytes of a chain step are folded away.
/// This is how many S-boxes per lane can be moved out of LUTs.
pub const SBOXES_PER_LANE: u32 = 494;
/// LUTs per LUT-ROM S-box. **Estimate**: the routed link's 59,946 LUT-RAM
/// per slice over its 1,482 S-boxes is ~40; 32 (8 outputs × 4 LUT6) is the
/// conservative floor used here.
///
/// Unit: CLB LUTs saved per S-box moved to RAM. Choosing the low figure means
/// the planner under-promises savings rather than over-promises them.
pub const LUTS_PER_LUT_SBOX: f64 = 32.0;
/// Ed25519SignCoreSmall in context (routed `slices-2` link).
///
/// Unit: CLB LUTs, counted once per kernel (one core serves every slice).
pub const ED25519_LUT: f64 = 25_383.0;
/// Ed25519SignCoreSmall BRAM36 tiles in context.
///
/// Unit: BRAM36 tiles, once per kernel.
pub const ED25519_BRAM36: f64 = 87.0;
/// Ed25519SignCoreSmall DSPs.
///
/// Unit: DSP48E2s, once per kernel. In this model it is the kernel's whole
/// DSP use.
pub const ED25519_DSP: u32 = 248;
/// Engine glue outside slices and the Ed25519 core (routed `slices-2` link).
///
/// Unit: CLB LUTs, once per kernel. Derived as kernel 301,037 minus two
/// slices minus Ed25519, so it absorbs everything not modeled separately.
pub const GLUE_LUT: f64 = 20_564.0;
/// Engine glue BRAM36 (certificate records, message FIFO), same link.
///
/// Unit: BRAM36 tiles, once per kernel.
pub const GLUE_BRAM36: f64 = 28.0;

/// Fraction of the device's UltraRAM and block RAM the planner leaves free.
///
/// Unit: a ratio (5 %). Filling RAM to the last tile makes placement and
/// routing harder, so [`Build::fill`] stops short.
pub const RAM_HEADROOM: f64 = 0.05;
/// LUTs of one lane's UltraRAM loader (counter + one LUT S-box): an **estimate**.
///
/// Unit: CLB LUTs per lane. UltraRAM cannot be preloaded by the bitstream, so
/// a lane with any UltraRAM S-box needs this small loader to write the table
/// after reset (see [`crate::sbox_placement`]).
pub const LOADER_LUT: f64 = 80.0;

/// One buildable configuration.
///
/// It is exactly the set of compile-time choices that change cost and speed:
/// the `DSIG_SLICES` and `DSIG_SBOX_PLACEMENT` build variables. [`Build::command`] prints the command that builds it.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Build {
    /// Slices (2, 4 or 8).
    ///
    /// Each slice is one complete signer; more slices means more signatures
    /// per second and proportionally more LUTs.
    pub slices: u32,
    /// S-boxes per lane in UltraRAM.
    ///
    /// Count out of [`SBOXES_PER_LANE`]; the same number in every lane.
    pub uram_per_lane: u32,
    /// S-boxes per lane in block RAM.
    ///
    /// Count out of [`SBOXES_PER_LANE`]; two share one BRAM18 (a quarter of
    /// a tile each).
    /// `uram_per_lane + bram_per_lane` never exceeds 494 in builds made by
    /// [`Build::fill`].
    pub bram_per_lane: u32,
}

/// Predicted resources.
///
/// The model's output for one [`Build`]: what the whole kernel would use on
/// the device. [`Build::fits`] compares it with the `DEVICE_*` constants and
/// [`LUT_CAP`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Resources {
    /// CLB LUTs of the kernel.
    ///
    /// `f64` so the sum stays exact before any rounding for display.
    pub lut: f64,
    /// BRAM36 tiles.
    ///
    /// Can end in .5 when an odd number of BRAM18 S-boxes is placed.
    pub bram36: f64,
    /// UltraRAMs.
    pub uram: u32,
    /// DSP48E2s.
    pub dsp: u32,
}

impl Build {
    /// All S-boxes in LUTs.
    ///
    /// The baseline build: no RAM placement, closest to the routed
    /// measurement.
    #[must_use]
    pub const fn lut_only(slices: u32) -> Build {
        Build { slices, uram_per_lane: 0, bram_per_lane: 0 }
    }

    /// The most S-boxes per lane that spare UltraRAM, then spare block RAM,
    /// can hold.
    ///
    /// UltraRAM is filled first, block RAM takes the remainder. Both keep
    /// [`RAM_HEADROOM`] free.
    #[must_use]
    pub fn fill(slices: u32) -> Build {
        Build::fill_within(
            slices,
            f64::from(DEVICE_URAM) * (1.0 - RAM_HEADROOM),
            KERNEL_BRAM36 * (1.0 - RAM_HEADROOM),
        )
    }

    /// Like [`Build::fill`], but only `uram` UltraRAMs and `bram36` BRAM36
    /// tiles are available in total (the share the chip planner gives DSig).
    ///
    /// Why: on a shared chip DSig gets part of the RAM, not the whole device.
    /// Filling the whole device's spare RAM would make every partial share
    /// look too small.
    #[must_use]
    pub fn fill_within(slices: u32, uram: f64, bram36: f64) -> Build {
        // Total Haraka lanes in the kernel; the placement is per lane, so the
        // spare RAM is shared out evenly over all of them.
        let lanes = f64::from(slices * LANES_PER_SLICE);
        // What the build uses before any S-box moves (caches, Ed25519, glue).
        let base = Build::lut_only(slices).resources();
        // URAMs left after the headroom and the key caches.
        let uram_free = uram - f64::from(base.uram);
        // URAM S-boxes per lane (two per URAM): whole numbers only, never
        // negative, never more than the lane has.
        let uram = ((2.0 * uram_free / lanes).floor().max(0.0) as u32).min(SBOXES_PER_LANE);
        // Spare block RAM in S-box slots: two per BRAM18, four per BRAM36.
        let slots = 4.0 * (bram36 - base.bram36);
        // Block-RAM S-boxes per lane, limited to what UltraRAM did not take.
        let bram = ((slots / lanes).floor().max(0.0) as u32).min(SBOXES_PER_LANE - uram);
        Build { slices, uram_per_lane: uram, bram_per_lane: bram }
    }

    /// The all-LUT and the RAM-filled build of every slice count.
    ///
    /// Six candidates in total: the two ends of the placement range for each
    /// of the three slice counts. In this model, moving more S-boxes into
    /// free RAM only lowers LUTs, so the partial placements in between are
    /// not listed.
    #[must_use]
    pub fn all() -> Vec<Build> {
        let mut builds = Vec::new();
        // The three slice counts `DSIG_SLICES` accepts.
        for slices in [2, 4, 8] {
            builds.push(Build::lut_only(slices));
            builds.push(Build::fill(slices));
        }
        builds
    }

    /// A short name: the slice feature plus the placement, if any.
    ///
    /// Used as the row label in [`sweep`], for example `slices-2` or
    /// `slices-4 uram=… bram=…`.
    #[must_use]
    pub fn features(self) -> String {
        // No S-box moved: the feature name alone identifies the build.
        if self.uram_per_lane + self.bram_per_lane == 0 {
            format!("slices-{}", self.slices)
        } else {
            format!(
                "slices-{} uram={} bram={}",
                self.slices, self.uram_per_lane, self.bram_per_lane
            )
        }
    }

    /// The command that builds it.
    ///
    /// So a reader can copy the planner's answer straight into a shell.
    #[must_use]
    pub fn command(self) -> String {
        // The placement variable is only needed when something moves out of
        // LUTs; otherwise the default (all LUT) applies.
        let env = if self.uram_per_lane + self.bram_per_lane == 0 {
            String::new()
        } else {
            format!(
                "DSIG_SBOX_PLACEMENT=uram={},bram={} ",
                self.uram_per_lane, self.bram_per_lane
            )
        };
        format!(
            "DSIG_SLICES={} {env}cargo build --profile sim",
            self.slices
        )
    }

    /// Predicted kernel resources.
    ///
    /// The cost model, one line per resource:
    ///
    /// ```text
    /// lut    = slices × SLICE_LUT − lanes × (placed × 32 − loader) + Ed25519 + glue
    /// bram36 = slices × SLICE_BRAM36 + lanes × bram_per_lane / 2 + Ed25519 + glue
    /// uram   = slices × 72 + lanes × uram_per_lane
    /// dsp    = Ed25519 only
    /// ```
    ///
    /// `lanes = slices × 3`, `placed = uram_per_lane + bram_per_lane`, and
    /// `loader` is [`LOADER_LUT`] when the lane has UltraRAM S-boxes.
    #[must_use]
    pub fn resources(self) -> Resources {
        // Haraka lanes in the whole kernel.
        let lanes = f64::from(self.slices * LANES_PER_SLICE);
        // S-boxes per lane taken out of LUTs (either RAM kind).
        let placed = f64::from(self.uram_per_lane + self.bram_per_lane);
        // A lane only needs the after-reset loader if it has UltraRAM S-boxes.
        let loader = if self.uram_per_lane > 0 { LOADER_LUT } else { 0.0 };
        // Slice count as f64 for the LUT and BRAM sums.
        let slices = f64::from(self.slices);
        Resources {
            // Slices pay full price, minus the LUTs freed by every placed
            // S-box, plus a loader per lane if UltraRAM is used; then the
            // once-per-kernel Ed25519 core and glue.
            lut: slices * SLICE_LUT - lanes * (placed * LUTS_PER_LUT_SBOX - loader)
                + ED25519_LUT
                + GLUE_LUT,
            // Two block-RAM S-boxes share a BRAM18: a quarter of a BRAM36 each.
            bram36: slices * SLICE_BRAM36
                + lanes * f64::from(self.bram_per_lane) / 4.0
                + ED25519_BRAM36
                + GLUE_BRAM36,
            // Key-cache URAMs per slice plus one URAM per pair of UltraRAM
            // S-boxes (rounded up per lane).
            uram: self.slices * SLICE_URAM + self.slices * LANES_PER_SLICE * self.uram_per_lane.div_ceil(2),
            // Only the Ed25519 core uses DSPs in this model.
            dsp: ED25519_DSP,
        }
    }

    /// Whether the build fits a LUT budget (percent of [`LUT_CAP`]) and the
    /// device's block RAM, UltraRAM and DSPs.
    ///
    /// `lut_percent` is a percentage, so `100.0` means the full 420,000-LUT
    /// cap. The RAM and DSP limits are the whole device, because the cap only
    /// applies to LUTs.
    #[must_use]
    pub fn fits(self, lut_percent: f64) -> bool {
        // Predicted use of every resource.
        let r = self.resources();
        r.lut <= f64::from(LUT_CAP) * lut_percent / 100.0
            && r.bram36 <= KERNEL_BRAM36
            && r.uram <= DEVICE_URAM
            && r.dsp <= DEVICE_DSP
    }

    /// Predicted steady-state signatures per second at `mhz`, and the stage
    /// that limits it.
    ///
    /// The engine is a pipeline of three stages that all must keep up, so the
    /// slowest one sets the rate:
    ///
    /// ```text
    ///  slices ─────────▶ certificates ─────────▶ frame writes
    ///  SLICES × f / 68    128 × f / 895           SLICES × 64 B × f / (26 × 64 B)
    ///          └──────────────── min(...) × STEADY_STATE_EFFICIENCY ──▶ sig/s
    /// ```
    ///
    /// The returned name (`"slices"`, `"certificates"` or `"frame writes"`)
    /// tells you which stage to improve next.
    #[must_use]
    pub fn signatures_per_second(self, mhz: f64) -> (f64, &'static str) {
        // Clock in hertz.
        let f = mhz * 1e6;
        // Slice ceiling: one key (one signature) per slice every 68 cycles.
        let slices = f64::from(self.slices) * f / KEY_PERIOD;
        // Certificate ceiling: one Ed25519 signature per 895 cycles covers 128.
        let certs = 128.0 * f / ED25519_CYCLES_PER_SIGN;
        // Write ceiling: one 64-byte beat per clock per slice port, and a
        // frame needs FRAME_BYTES of beats.
        let writes = f64::from(self.slices) * 64.0 * f / FRAME_BYTES;
        // Start with the slice stage and replace it with any slower stage.
        let mut best = (slices, "slices");
        for (rate, name) in [(certs, "certificates"), (writes, "frame writes")] {
            if rate < best.0 {
                best = (rate, name);
            }
        }
        (best.0 * STEADY_STATE_EFFICIENCY, best.1)
    }
}

/// The fastest build that fits the budget, if any.
///
/// `lut_percent` is a percentage of [`LUT_CAP`]; `mhz` is the clock to rate
/// builds at (normally [`DESIGN_MHZ`]). Returns `None` when even the smallest
/// build does not fit. Among equally fast builds it prefers the one with
/// fewer LUTs, which leaves more room for timing closure.
#[must_use]
pub fn best(lut_percent: f64, mhz: f64) -> Option<Build> {
    Build::all()
        .into_iter()
        // Drop every build that breaks the LUT budget or a device limit.
        .filter(|b| b.fits(lut_percent))
        .max_by(|a, b| {
            // Predicted rates of the two builds being compared.
            let (ra, rb) = (a.signatures_per_second(mhz).0, b.signatures_per_second(mhz).0);
            // Faster first; then fewer LUTs.
            ra.total_cmp(&rb).then(b.resources().lut.total_cmp(&a.resources().lut))
        })
}

/// A human-readable table of every build.
///
/// One row per candidate in [`Build::all`]: name, predicted rate, limiting
/// stage, resources and whether it fits `lut_percent`. This is what
/// `dsig_plan --sweep` prints.
#[must_use]
pub fn sweep(lut_percent: f64, mhz: f64) -> String {
    // The table is built in memory and returned, so callers decide where it
    // goes.
    let mut out = String::new();
    // Header row. Writing to a String cannot fail, so the result is ignored.
    let _ = writeln!(
        out,
        "{:<30} sig/s @{mhz} MHz  limit          CLB LUT   BRAM36  URAM  DSP  fits {lut_percent}%", "build"
    );
    for b in Build::all() {
        // Rate and limiting stage, then resources, for this row.
        let (rate, limit) = b.signatures_per_second(mhz);
        let r = b.resources();
        // Rate is printed in millions of signatures per second.
        let _ = writeln!(
            out,
            "{:<30} {:>12.2}M  {:<13} {:>8.0} {:>8.0} {:>5} {:>4}  {}",
            b.features(),
            rate / 1e6,
            limit,
            r.lut,
            r.bram36,
            r.uram,
            r.dsp,
            if b.fits(lut_percent) { "yes" } else { "no" }
        );
    }
    out
}

/// Sanity checks of the model itself (not of hardware).
#[cfg(test)]
mod tests {
    use super::*;

    /// `fill` must never ask for more UltraRAM or block RAM than the chip has.
    #[test]
    fn filled_builds_respect_the_device() {
        for slices in [2, 4, 8] {
            let r = Build::fill(slices).resources();
            assert!(r.uram <= DEVICE_URAM && r.bram36 <= KERNEL_BRAM36, "{slices}: {r:?}");
        }
    }

    /// The routed fact the model is anchored on: two all-LUT slices fit the
    /// 420k cap; eight all-LUT slices (about a million LUTs) do not.
    #[test]
    fn two_slices_fit_the_full_budget_and_eight_do_not() {
        assert!(Build::lut_only(2).fits(100.0));
        assert!(!Build::lut_only(8).fits(100.0));
    }

    /// With two slices the slice stage, not certificates or writes, is the
    /// bottleneck, and its rate is exactly `2 × f / 68`.
    #[test]
    fn the_slice_ceiling_is_slices_times_f_over_68() {
        // Rate and limit of the baseline two-slice build at 205 MHz.
        let (rate, limit) = Build::lut_only(2).signatures_per_second(205.0);
        assert_eq!(limit, "slices");
        assert!((rate - 2.0 * 205e6 / 68.0).abs() < 1.0);
    }
}