rhdl_ed25519_scalable_core/frontier/

costs.rs

//! Block costs: the device, each block's LUT/DSP/BRAM/URAM, the measured
//! ([`vivado_costs`]) and projected ([`slimmed_costs`]) tables, and the
//! adjustments routed builds taught us (multiplier choice, constant ROM).

use super::*;

/// Device limits of the Alveo U280 (XCU280) that [`frontier`] packs builds
/// into. All fields except `lut` are the physical device totals.
#[derive(Clone, Copy, Debug)]
pub struct Device {
    /// CLB LUT budget (the project cap, not the device total).
    pub lut: u32,
    /// DSP48E2 blocks.
    pub dsp: u32,
    /// BRAM36 blocks.
    pub bram36: u32,
    /// URAM blocks.
    pub uram: u32,
    /// Clock in MHz; converts cycles per operation into operations per second.
    pub mhz: f64,
}

impl Device {
    /// The device's limits as a share.
    pub(super) fn share(&self) -> Share {
        Share { lut: self.lut, dsp: self.dsp, bram36: self.bram36, uram: self.uram }
    }
    /// The U280 at a LUT budget and the 205 MHz design clock. The DSP, BRAM36
    /// and URAM counts are the XCU280 totals (same values as [`U280_DSP`],
    /// [`U280_BRAM36`], [`U280_URAM`]).
    pub fn u280(lut: u32) -> Self {
        Device {
            lut,
            dsp: 9_024,
            bram36: 2_016,
            uram: 960,
            mhz: 205.0,
        }
    }
}

/// Resources of one block, or a sum of blocks.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Cost {
    /// CLB LUTs.
    pub lut: u32,
    /// DSP48E2 blocks.
    pub dsp: u32,
    /// BRAM36 blocks.
    pub bram36: u32,
    /// URAM blocks.
    pub uram: u32,
}

impl Cost {
    /// `self` plus `n` instances of `other`, field by field. Used to build a
    /// module total from per-instance block costs.
    pub(super) fn add(self, other: Cost, n: u32) -> Cost {
        Cost {
            lut: self.lut + other.lut * n,
            dsp: self.dsp + other.dsp * n,
            bram36: self.bram36 + other.bram36 * n,
            uram: self.uram + other.uram * n,
        }
    }
    /// Whether every resource is within the device limits.
    pub(super) fn fits(&self, d: &Device) -> bool {
        self.lut <= d.lut && self.dsp <= d.dsp && self.bram36 <= d.bram36 && self.uram <= d.uram
    }
}

/// Per-instance block costs used by the frontier and the system planner.
/// Two tables exist: [`vivado_costs`] (as built) and [`slimmed_costs`]
/// (projected memory layout).
#[derive(Clone, Copy, Debug)]
pub struct Costs {
    /// Fixed-base signing machine.
    pub fb_machine: Cost,
    /// SHA-512 ring.
    pub sha_ring: Cost,
    /// Scalar ring.
    pub scalar_ring: Cost,
    /// Batch-compress machine.
    pub cp_machine: Cost,
    /// Signing controller.
    pub sign_controller: Cost,
    /// Signing controller of a fused build (no compress machine: no credit
    /// pool or compress dispatch).
    pub sign_controller_fused: Cost,
    /// Verify field machine, any key (derived: signing machine plus a
    /// per-context variable-base table and its write path).
    pub verify_machine_strict: Cost,
    /// Verify field machine for loaded keys (derived: signing machine plus a
    /// writable key table in URAM and its write path).
    pub verify_machine_known_key: Cost,
    /// Verify controller (derived from the signing controller).
    pub verify_controller: Cost,
    /// Scalar ring of the verify module (`k = H mod l` only).
    pub verify_scalar_ring: Cost,
    /// Key-loader machine of a known-key verify module (decodes `A` and
    /// builds its table; one per module).
    pub key_loader: Cost,
    /// The fused small signer, `Ed25519SignCoreSmall` (1/1/1/0 with its own
    /// SHA ring), as one block: measured in Vivado (routed). It is the
    /// cheapest way to sign at DSig's certificate rate.
    pub small_signer: Cost,
    /// The block-RAM layout of the field machines, if this table's own
    /// layout is a different one. A build may put some machines in it when
    /// UltraRAM runs out (see [`sign_cost_within`]).
    pub bram_layout: Option<BramLayout>,
    /// Change per field machine when it uses the DSP-lean multiplier, as
    /// `(LUT delta, DSP delta)` (17 x 26 tiles chained by the DSP's 17-bit
    /// cascade shift: 150 DSPs instead of 225, rows summed in fabric). `None`
    /// when the option is unavailable for this cost table; the planners then
    /// skip [`Multiplier::Lean150`].
    pub lean_mul: Option<(i32, i32)>,
    /// Where the numbers came from (printed in reports).
    pub source: &'static str,
}

/// Field-machine costs in the block-RAM (as-built) layout: the fallback for
/// machines that do not fit the UltraRAM layout's URAM.
#[derive(Clone, Copy, Debug)]
pub struct BramLayout {
    /// Fixed-base signing machine.
    pub fb_machine: Cost,
    /// Batch-compress machine.
    pub cp_machine: Cost,
    /// Verify machine, any key.
    pub verify_machine_strict: Cost,
    /// Verify machine, loaded keys.
    pub verify_machine_known_key: Cost,
    /// Key loader of a known-key verify module.
    pub key_loader: Cost,
}

/// Which multiplier a module's field machines use.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Multiplier {
    /// 225 DSPs (15 x 15 tiles of 17 x 22), built and measured.
    Dsp225,
    /// 150 DSPs (15 x 10 tiles of 17 x 26) plus fabric row adders (projected).
    Lean150,
}

impl Multiplier {
    /// Human-readable label for reports.
    pub fn name(self) -> &'static str {
        match self {
            Multiplier::Dsp225 => "225-DSP multiplier",
            Multiplier::Lean150 => "150-DSP Karatsuba multiplier",
        }
    }
}

/// The cost table `c` rebuilt for multiplier `m`. Returns `None` for
/// [`Multiplier::Lean150`] when `c.lean_mul` is `None`, so callers can skip
/// that option.
/// The cost table for multiplier `m`, or `c` itself when `m` is not
/// offered (for callers outside this module).
pub fn with_mul_pub(c: &Costs, m: Multiplier) -> Costs {
    with_mul(c, m).unwrap_or(*c)
}

/// LUTs the constant ROM (`machine::ConstRom`, fix14) adds to each field
/// machine: a literal and a mux per read port instead of LUT RAM. Routed
/// on the 1,1,1,1 verifier (three field machines: verify, compress, key
/// loader): 84,435 LUT against 82,184 on fix12 (007zzr, 007zzi), so 750
/// each. One core, so provisional; the signers' machines hold other
/// constants and are not yet routed on fix14.
pub const CONST_ROM_LUT: i32 = 750;

/// `c` with every field machine's LUTs changed by `dlut` (the multiplier
/// and the constant ROM live in every field machine; rings and
/// controllers keep their costs).
pub(super) fn per_field_machine(c: &Costs, dlut: i32, ddsp: i32) -> Costs {
    let f = |x: Cost| Cost { lut: (x.lut as i32 + dlut) as u32, dsp: (x.dsp as i32 + ddsp) as u32, ..x };
    Costs {
        fb_machine: f(c.fb_machine),
        cp_machine: f(c.cp_machine),
        verify_machine_strict: f(c.verify_machine_strict),
        verify_machine_known_key: f(c.verify_machine_known_key),
        key_loader: f(c.key_loader),
        // The fallback layouts hold the same machines.
        bram_layout: c.bram_layout.map(|a| BramLayout {
            fb_machine: f(a.fb_machine),
            cp_machine: f(a.cp_machine),
            verify_machine_strict: f(a.verify_machine_strict),
            verify_machine_known_key: f(a.verify_machine_known_key),
            key_loader: f(a.key_loader),
        }),
        ..*c
    }
}

/// The cost table for RTL before fix14 (constant banks in LUT RAM), to
/// compare routed cores of that RTL with the table.
pub fn before_const_rom(c: &Costs) -> Costs {
    per_field_machine(c, -CONST_ROM_LUT, 0)
}

pub(super) fn with_mul(c: &Costs, m: Multiplier) -> Option<Costs> {
    match m {
        Multiplier::Dsp225 => Some(*c),
        Multiplier::Lean150 => {
            // Per-machine LUT and DSP deltas (e.g. +2,500 LUT, -75 DSP),
            // applied to every block that holds one field multiplier.
            let (dlut, ddsp) = c.lean_mul?;
            Some(per_field_machine(c, dlut, ddsp))
        }
    }
}

/// Vivado 2023.2 out-of-context synthesis of 15/11/3/1, per instance.
///
/// The signing blocks (fixed-base machine, SHA ring, scalar ring, compress
/// machine, controller) are measured. The verify blocks are derived from the
/// signing blocks by adding estimated LUT and memory for what they add, and
/// are not built. The lean multiplier is not offered here.
pub fn vivado_costs() -> Costs {
    // Measured fixed-base signing machine; the verify machines and the key
    // loader below are expressed relative to it.
    let fb = Cost { lut: 10_110, dsp: 225, bram36: 72, uram: 0 };
    Costs {
        fb_machine: fb,
        sha_ring: Cost { lut: 4_567, dsp: 0, bram36: 1, uram: 0 },
        scalar_ring: Cost { lut: 5_520, dsp: 23, bram36: 0, uram: 0 },
        cp_machine: Cost { lut: 16_800, dsp: 225, bram36: 289, uram: 32 },
        sign_controller: Cost { lut: 15_800, dsp: 0, bram36: 4, uram: 16 },
        // Not measured in this table; the fused build is costed as the
        // non-fused controller.
        sign_controller_fused: Cost { lut: 15_800, dsp: 0, bram36: 4, uram: 16 },
        // Derived: the signing machine plus about 2,500 LUT and 22 BRAM36 for
        // the per-context variable-base table and its write path.
        verify_machine_strict: Cost { lut: fb.lut + 2_500, dsp: 225, bram36: fb.bram36 + 22, uram: 0 },
        // Derived: the signing machine plus about 1,500 LUT and a 22-URAM key
        // table.
        verify_machine_known_key: Cost { lut: fb.lut + 1_500, dsp: 225, bram36: fb.bram36, uram: 22 },
        // Derived: assumed equal to the signing controller.
        verify_controller: Cost { lut: 15_800, dsp: 0, bram36: 4, uram: 16 },
        // Derived: assumed equal to the signing scalar ring (no reduce-only
        // variant in the as-built table).
        verify_scalar_ring: Cost { lut: 5_520, dsp: 23, bram36: 0, uram: 0 },
        // Derived: a fixed-base machine plus 10 BRAM36 for table building.
        key_loader: Cost { lut: fb.lut, dsp: 225, bram36: fb.bram36 + 10, uram: 0 },
        // Routed at 4.878 ns: 26,408 CLB LUT, 248 DSP, 88 BRAM36 (+2 BRAM18).
        small_signer: Cost { lut: 26_408, dsp: 248, bram36: 89, uram: 0 },
        // This table is the block-RAM layout itself.
        bram_layout: None,
        lean_mul: None,
        source: "as built: Vivado 2023.2 OOC, blocks routed at 4.878 ns (compress stage and controller from 15/11/3/1 synthesis; verify blocks derived)",
    }
}

/// Verify-controller LUTs per verify machine (dispatch, free-slot word,
/// output offer), fitted from the 6- and 24-machine routed fix9 verifiers;
/// costed with each machine so the controller entry stays fixed. (Fitted
/// at 716 on the 6- and 14-machine verifiers before the timing fixes.)
pub const VERIFY_PER_MACHINE_LUT: u32 = 228;

/// LUT change of a fixed-base machine inside a whole signing core against
/// the machine routed alone (fitted, see [`slimmed_costs`]): synthesis
/// shares or trims logic across the machine's boundary.
pub const FB_IN_CORE_LUT: i32 = -1_505;

/// A routed fixed-base machine's cost inside a whole core.
pub(super) fn in_core(c: Cost) -> Cost {
    Cost { lut: (c.lut as i32 + FB_IN_CORE_LUT) as u32, ..c }
}

/// Specialized modules: the memory layout of
/// [`MachineMemory::SPECIALIZED`](crate::machine::MachineMemory) (banks M
/// and A in UltraRAM, constants in a LUT ROM, the compress machine's input
/// bank in UltraRAM), as built and **routed**: Vivado 2023.2 out of context
/// at 4.878 ns, every block meeting timing, on the fix9 RTL (the timing
/// fixes through e0c9caa; `measure/results.tsv`, 2026-10-18):
///
/// | Block | LUT | DSP | BRAM36 | URAM | WNS (ns) |
/// |---|---:|---:|---:|---:|---:|
/// | fixed-base machine | 14,615 | 225 | 24.5 | 32 | +0.848 |
/// | compress machine | 16,569 | 225 | 1.5 | 64 | +0.679 |
/// | known-key verify machine | 13,863 | 225 | 24.5 | 56 | +0.609 |
/// | aux machine (key loader) | 14,518 | 225 | 9.5 | 48 | +0.863 |
/// | SHA ring | 4,315 | 0 | 0 | 0 | +1.995 |
/// | small signer (1/1/1/0, fix4) | 29,055 | 248 | 40 | 32 | +0.306 |
/// | 150-DSP Karatsuba variants (before the fixes) | +4,367..4,441 | −75 | = | = | +0.056..+0.470 |
///
/// BRAM18 halves are rounded up. The scalar ring and the controllers are
/// fitted to routed whole cores (signers, verifiers; see the entries). Still
/// **derived, not built**: the strict verify machine (fixed-base machine
/// plus 2,500 LUT and 22 BRAM36); the reduce-only verify scalar ring is not
/// built, so verifiers are costed with the built signing ring.
pub fn slimmed_costs() -> Costs {
    let v = vivado_costs();
    // Blocks routed on the fix9 RTL (Vivado 2023.2 OOC, 4.878 ns,
    // 2026-10-18; `measure/results.tsv` jobs 007zq-007zzb), every one with
    // positive slack: fb machine 14,615 LUT (WNS +0.848), verify machine
    // 13,863 (+0.609), compress machine 16,569 (+0.679), key loader 14,518
    // (+0.863), SHA ring 4,315 (+1.995).
    let fb = Cost { lut: 14_615, dsp: 225, bram36: 25, uram: 32 };
    let fix13 = Costs {
        // In a whole core a fixed-base machine costs FB_IN_CORE_LUT less
        // than routed alone (fitted with the rings and controller below).
        fb_machine: in_core(fb),
        sha_ring: Cost { lut: 4_315, ..v.sha_ring },
        cp_machine: Cost { lut: 16_569, dsp: 225, bram36: 2, uram: 64 },
        verify_machine_strict: Cost { lut: fb.lut + 2_500, bram36: fb.bram36 + 22, ..fb },
        // Routed block 13,863 plus 228: the verify controller's per-machine
        // dispatch and offer logic (fitted, see `sign_controller`).
        verify_machine_known_key: Cost { lut: 13_863 + VERIFY_PER_MACHINE_LUT, dsp: 225, bram36: 25, uram: 56 },
        // Signing: rings, controller and the fixed-base machines' in-core
        // change, fitted by least squares to four routed signers (2026-10-20;
        // `measure/accuracy.tsv`): 8,0,2,1 u6l0 (fix9), 12,0,3,1 u5l2
        // (fix10), 4,0,1,1 and 8,0,3,1 (fix13). The routed total less the
        // routed blocks leaves 13,702, 15,708, 12,003 and 21,675 LUT; the fit
        // is a controller of 10,099, 7,871 per scalar ring and -1,505 per
        // fixed-base machine, and lands within 102 LUT of all four. A ring
        // routed alone is 6,194 (fix10), so ~1,700 per ring is its dispatch
        // and arbitration in the core. The fused 8,0,2,0 (fix13) leaves
        // 6,817: a controller of 3,115 with no credit pool or compress
        // dispatch (one core, in sample). The previous fit (2,408 per ring,
        // 8,886 controller, two cores) under-predicted 8,0,3,1 by 3.6 % and
        // over-predicted 8,0,2,0 by 5.5 %.
        //
        // Verifying: fitted to the fix9 RTL (2026-10-18). The routed total
        // less the routed blocks (machines in their built layouts, compress
        // machine, key loader, 1,500-LUT SHA client port) leaves 13,702 LUT
        // for sign 8,0,2,1 u6l0 (two scalar rings), 16,110 for sign 12,0,3,1
        // u5l2 (three), 34,435 for verify 6,0,1,1 (one) and 40,954 for verify
        // 24,0,2,1 u2l19 (two). That gives a scalar ring of 2,408 LUT, a
        // signing controller of 8,886 and a verify controller of 30,657 + 228
        // per machine. Before the timing fixes (six cores, 2026-10-17):
        // 1,590, 11,240 and 17,540 + 716; the verifier's limb-serial decode
        // and registered credit, output and dispatch paths account for most
        // of its growth. The 24-machine verifier missed timing (-5.763 ns)
        // and may carry replication; the 9,0,2,1 signer (fix7, +0.114 ns) is
        // the out-of-sample check.
        scalar_ring: Cost { lut: 7_871, ..v.scalar_ring },
        sign_controller: Cost { lut: 10_099, ..v.sign_controller },
        sign_controller_fused: Cost { lut: 3_115, ..v.sign_controller },
        verify_controller: Cost { lut: 30_657, ..v.verify_controller },
        // The verifier uses the signing scalar ring (no reduce-only ring
        // yet); its in-core cost is fitted with the verify controller, which
        // keeps the verify fit's 2,408.
        verify_scalar_ring: Cost { lut: 2_408, ..v.scalar_ring },
        key_loader: Cost { lut: 14_518, dsp: 225, bram36: 10, uram: 48 },
        // Routed 2026-10-17 (fix4: registered SHA ready), WNS +0.306.
        small_signer: Cost { lut: 29_055, dsp: 248, bram36: 40, uram: 32 },
        // The 150-DSP Karatsuba multiplier (`fe17_kara`), measured in all four
        // machines before the timing fixes: +4,367 to +4,441 LUT and -75 DSP
        // each.
        lean_mul: Some((4_440, -75)),
        // Replicated machines that do not fit the UltraRAM layout use the
        // block-RAM fallback (`MachineMemory::BRAM_BANKS`): banks M and A
        // move to block RAM (+32 BRAM36, -32 URAM); a verify machine's key
        // tables stay in UltraRAM. Routed on the fix9 RTL (2026-10-18): fb
        // 14,615 LUT / 56.5 BRAM36 / 0 URAM, WNS +0.544; verify 13,866 / 56.5
        // / 24, WNS +0.790. The other entries are unused (only replicated
        // machines fall back).
        bram_layout: Some(BramLayout {
            fb_machine: in_core(Cost { lut: 14_615, dsp: 225, bram36: 57, uram: 0 }),
            cp_machine: v.cp_machine,
            verify_machine_strict: v.verify_machine_strict,
            verify_machine_known_key: Cost { lut: 13_866 + VERIFY_PER_MACHINE_LUT, dsp: 225, bram36: 57, uram: 24 },
            key_loader: v.key_loader,
        }),
        source: "specialized memory layout: blocks routed on the fix9 RTL (Vivado 2023.2 OOC, 4.878 ns, 2026-10-18); signing rings, controllers and in-core machine change fitted to five routed signers (fix9-fix13), verify controller to the fix9 verifiers; fix14 constant ROM +750 LUT per field machine (one routed core)",
        ..v
    };
    // Today's RTL (fix14) builds the constant banks as ROM logic.
    per_field_machine(&fix13, CONST_ROM_LUT, 0)
}