rhdl_ed25519_scalable_core/frontier/

system.rs

//! The system planner: split a [`SystemBudget`] into two [`Share`]s and pick
//! the fastest sign and verify builds inside each ([`plan_sign_with`],
//! [`plan_verify_with`], [`plan_system`]).

use super::*;

/// Bundles of the signing fixed-base program (for reports).
pub const SIGN_BUNDLES: u32 = FB_BUNDLES;

/// LUT budget that the 100 % setting means.
pub const BASE_LUT: u32 = 420_000;
/// DSP budget that the 100 % setting means.
pub const BASE_DSP: u32 = 4_500;
/// Physical CLB LUTs of the XCU280 (the hard ceiling for any LUT share).
pub const U280_LUT: u32 = 1_303_680;
/// Physical DSP48E2 blocks of the XCU280.
pub const U280_DSP: u32 = 9_024;
/// Physical BRAM36 blocks of the XCU280.
pub const U280_BRAM36: u32 = 2_016;
/// Physical URAM blocks of the XCU280.
pub const U280_URAM: u32 = 960;

/// The controls of the system planner: two budget sliders, two power
/// sliders, plus the verification mode and the clock.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SystemBudget {
    /// LUTs as a percentage of [`BASE_LUT`] (0..200).
    pub lut_percent: f64,
    /// DSPs as a percentage of [`BASE_DSP`] (0..200).
    pub dsp_percent: f64,
    /// Share of the budget given to signing (0..100).
    pub sign_power: f64,
    /// Share of the budget given to verification (0..100; at most
    /// `100 - sign_power`).
    pub verify_power: f64,
    /// Verification mode.
    pub mode: VerifyMode,
    /// Clock in MHz.
    pub mhz: f64,
}

impl Default for SystemBudget {
    /// 100 % LUT and DSP budgets, an even 50/50 split, known-key verification
    /// and the 205 MHz design clock.
    fn default() -> Self {
        SystemBudget { lut_percent: 100.0, dsp_percent: 100.0, sign_power: 50.0, verify_power: 50.0, mode: VerifyMode::KnownKey, mhz: 205.0 }
    }
}

/// A module's share of every resource: the limits one module (sign or
/// verify) must fit inside.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Share {
    /// LUTs.
    pub lut: u32,
    /// DSPs.
    pub dsp: u32,
    /// BRAM36 (the same fraction of the device).
    pub bram36: u32,
    /// URAM (the same fraction of the device).
    pub uram: u32,
}

impl SystemBudget {
    /// Total LUT budget.
    pub fn luts(&self) -> u32 {
        (BASE_LUT as f64 * self.lut_percent / 100.0) as u32
    }
    /// Total DSP budget, never above the device.
    pub fn dsps(&self) -> u32 {
        ((BASE_DSP as f64 * self.dsp_percent / 100.0) as u32).min(U280_DSP)
    }
    /// The share of a module that gets `power` percent. LUT and DSP are that
    /// fraction of the budget; BRAM36 and URAM, which have no budget slider,
    /// are that fraction of the whole device. Because the two powers sum to
    /// at most 100, the two shares never exceed the device together.
    pub fn share(&self, power: f64) -> Share {
        // Fraction 0..1 of every resource.
        let f = power.clamp(0.0, 100.0) / 100.0;
        Share {
            lut: (self.luts().min(U280_LUT) as f64 * f) as u32,
            dsp: (self.dsps() as f64 * f) as u32,
            bram36: (U280_BRAM36 as f64 * f) as u32,
            uram: (U280_URAM as f64 * f) as u32,
        }
    }
}

/// One planned module.
#[derive(Clone, Copy, Debug)]
pub struct ModulePlan<P> {
    /// The build ([`Profile`] or [`VerifyProfile`]).
    pub profile: P,
    /// Operations per second.
    pub rate: f64,
    /// Resources.
    pub cost: Cost,
    /// The share it had to fit.
    pub share: Share,
    /// Which share limit stops the next larger build: the resource with the
    /// highest cost/share ratio (see `limit_of`).
    pub limit: &'static str,
    /// Multiplier the module's field machines use.
    pub multiplier: Multiplier,
}

/// The planned system.
#[derive(Clone, Copy, Debug)]
pub struct SystemPlan {
    /// Signing module, if anything fits its share.
    pub sign: Option<ModulePlan<Profile>>,
    /// Verify module, if anything fits its share.
    pub verify: Option<ModulePlan<VerifyProfile>>,
    /// Both together.
    pub total: Cost,
}

/// Name of the resource that `cost` uses the largest fraction of in `share`
/// ("LUT", "DSP", "BRAM", "URAM", or "none" if all are zero). A zero share
/// limit is treated as 1 to avoid dividing by zero.
pub(super) fn limit_of(cost: Cost, share: &Share) -> &'static str {
    // Fill ratio of each resource.
    let ratios = [
        (cost.lut as f64 / share.lut.max(1) as f64, "LUT"),
        (cost.dsp as f64 / share.dsp.max(1) as f64, "DSP"),
        (cost.bram36 as f64 / share.bram36.max(1) as f64, "BRAM"),
        (cost.uram as f64 / share.uram.max(1) as f64, "URAM"),
    ];
    // Largest ratio wins; on a tie the earlier entry is kept.
    ratios.iter().fold((0.0, "none"), |a, b| if b.0 > a.0 { *b } else { a }).1
}

/// Whether every resource of `cost` is within `share`.
pub(super) fn fits(cost: &Cost, share: &Share) -> bool {
    cost.lut <= share.lut && cost.dsp <= share.dsp && cost.bram36 <= share.bram36 && cost.uram <= share.uram
}

/// Cycles per signature of the fused small signer with 32 requests in
/// flight (native simulation).
pub const SMALL_SIGNER_CYCLES: f64 = 895.0;

/// LUTs of the port from a module to the shared SHA-512 pipeline: request
/// mux, tag, and the credit-counted result FIFO (estimate until built).
pub const SHA_CLIENT_LUT: u32 = 1_500;
/// The shared SHA-512 pipeline is modeled as never limiting a module's own
/// stages (the planner checks total demand against its supply instead).
/// Plugging this many rings into the cycle model makes the SHA term about
/// 0.27 cycles for signing, below the 2-cycle admission floor.
pub(super) const SHARED_SHA_RINGS: u32 = 1_000;

/// Best signing module within a share, with its own SHA rings.
pub fn plan_sign(share: Share, costs: &Costs, mhz: f64) -> Option<ModulePlan<Profile>> {
    plan_sign_with(share, costs, mhz, false)
}

/// Best signing module within a share; with `shared_sha` the module has no
/// SHA rings and sends its three blocks per signature to the shared
/// SHA-512 pipeline (a client port instead of rings, `sha = 0` in the
/// profile).
///
/// "Best" is the highest rate; builds within 1 signature/s of the best are
/// treated as equal and the one with fewer LUTs wins. Both multipliers are
/// tried when the cost table offers the lean one. `None` if nothing fits.
pub fn plan_sign_with(share: Share, costs: &Costs, mhz: f64, shared_sha: bool) -> Option<ModulePlan<Profile>> {
    plan_sign_shaped(share, costs, mhz, shared_sha, &Shape::default())
}

/// [`plan_sign_with`] restricted to builds of `shape` (ratio, batch
/// compression). The fused small signer counts as a build without batch
/// compression and is skipped under a manual ratio.
pub fn plan_sign_shaped(share: Share, costs: &Costs, mhz: f64, shared_sha: bool, shape: &Shape) -> Option<ModulePlan<Profile>> {
    let mut best: Option<ModulePlan<Profile>> = None;
    // Shared-SHA builds have no rings of their own: only sha = 0 is tried.
    let shas = if shared_sha { 0..=0 } else { 1..=24 };
    for multiplier in [Multiplier::Dsp225, Multiplier::Lean150] {
    // Skip the lean multiplier when this cost table has no figures for it.
    let Some(c) = with_mul(costs, multiplier) else { continue };
    let c = &c;
    // The fused small signer, as measured: one block with its own SHA ring,
    // 895 cycles per signature with 32 in flight. It wins whenever the share
    // is too small for anything else, or the needed rate is low (DSig).
    if multiplier == Multiplier::Dsp225 && shape.ratio.is_none() && shape.compress.allows(false) && fits(&c.small_signer, &share) {
        let rate = mhz * 1e6 / SMALL_SIGNER_CYCLES;
        let p = Profile { fb: 1, sha: 1, sc: 1, fused: true };
        if best.is_none_or(|b| rate > b.rate + 1.0) {
            best = Some(ModulePlan { profile: p, rate, cost: c.small_signer, share, limit: limit_of(c.small_signer, &share), multiplier });
        }
    }
    // Search ranges: up to 40 fixed-base machines, 24 SHA rings, 6 scalar
    // rings (the same as `config::candidates`).
    for fused in [false, true] {
    if !shape.compress.allows(!fused) {
        continue;
    }
    for fb in 1..=40 {
        // Every layout of a machine has the same DSPs and at least the
        // UltraRAM layout's LUTs: no larger build can fit either.
        if fb * c.fb_machine.dsp > share.dsp || fb * c.fb_machine.lut.min(c.bram_layout.map_or(u32::MAX, |a| a.fb_machine.lut)) > share.lut {
            break;
        }
        for sha in shas.clone() {
            for sc in 1..=6 {
                if !shape.keeps(fb, sha, sc, shared_sha) {
                    continue;
                }
                let p = Profile { fb, sha, sc, fused };
                // The client port replaces the rings in the cost.
                let port = if shared_sha { SHA_CLIENT_LUT } else { 0 };
                let cost = sign_cost_within(&p, c, &share, port);
                if !fits(&cost, &share) {
                    continue;
                }
                // The profile used only for the rate: in shared mode the SHA
                // stage is made non-limiting (sha = 0 would divide by zero).
                let model = Profile { sha: if shared_sha { SHARED_SHA_RINGS } else { sha }, ..p };
                let rate = mhz * 1e6 / model.cycles_per_sign().0;
                // Faster by more than 1/s, or equally fast (within 1/s) with
                // fewer LUTs.
                if best.is_none_or(|b| rate > b.rate + 1.0 || (rate > b.rate - 1.0 && cost.lut < b.cost.lut)) {
                    best = Some(ModulePlan { profile: p, rate, cost, share, limit: limit_of(cost, &share), multiplier });
                }
            }
        }
    }
    }
    }
    best
}

/// Best verify module within a share, with its own SHA rings.
pub fn plan_verify(share: Share, mode: VerifyMode, costs: &Costs, mhz: f64) -> Option<ModulePlan<VerifyProfile>> {
    plan_verify_with(share, mode, costs, mhz, false)
}

/// Best verify module within a share; `shared_sha` as in [`plan_sign_with`]
/// (two blocks per verification). Same selection rule as
/// [`plan_sign_with`]; `None` if nothing fits.
pub fn plan_verify_with(share: Share, mode: VerifyMode, costs: &Costs, mhz: f64, shared_sha: bool) -> Option<ModulePlan<VerifyProfile>> {
    plan_verify_shaped(share, mode, costs, mhz, shared_sha, &Shape::default())
}

/// [`plan_verify_with`] restricted to builds of `shape`; without batch
/// compression the profile has `cp = 0`.
pub fn plan_verify_shaped(
    share: Share,
    mode: VerifyMode,
    costs: &Costs,
    mhz: f64,
    shared_sha: bool,
    shape: &Shape,
) -> Option<ModulePlan<VerifyProfile>> {
    let mut best: Option<ModulePlan<VerifyProfile>> = None;
    // Shared-SHA builds have no rings of their own: only sha = 0 is tried.
    let shas = if shared_sha { 0..=0 } else { 1..=16 };
    for multiplier in [Multiplier::Dsp225, Multiplier::Lean150] {
    // Skip the lean multiplier when this cost table has no figures for it.
    let Some(c) = with_mul(costs, multiplier) else { continue };
    let c = &c;
    // Search ranges: up to 64 machines, 16 SHA rings, 4 scalar rings and
    // 0 to 2 compress machines. Known-key verification is built only with
    // exactly one (`KnownKeyVerifyCore` always has one compress stage), so
    // it searches cp = 1 alone. Why: offering cp = 0 planned an unbuildable
    // 1,0,1,0 verifier for the DSig paper, costed at 63k LUT against the
    // 82,184 routed for the buildable 1,1,1,1 (job 007zzi, 2026-10-19).
    let cps = if matches!(mode, VerifyMode::KnownKey) { 1..=1 } else { 0..=2 };
    for machines in 1..=64 {
        // As for signing: DSPs and the cheapest layout's LUTs bound the size.
        let m = mode.machine(c);
        let alt = c.bram_layout.map_or(u32::MAX, |a| match mode {
            VerifyMode::Strict | VerifyMode::Batch => a.verify_machine_strict.lut,
            VerifyMode::KnownKey => a.verify_machine_known_key.lut,
        });
        if machines * m.dsp > share.dsp || machines * m.lut.min(alt) > share.lut {
            break;
        }
        for sha in shas.clone() {
            for sc in 1..=4 {
                for cp in cps.clone() {
                    if !shape.compress.allows(cp > 0) || !shape.keeps(machines, sha, sc, shared_sha) {
                        continue;
                    }
                    let v = VerifyProfile { machines, sha, sc, cp };
                    // The client port replaces the rings in the cost.
                    let port = if shared_sha { SHA_CLIENT_LUT } else { 0 };
                    let cost = verify_cost_within(&v, mode, c, &share, port);
                    if !fits(&cost, &share) {
                        continue;
                    }
                    // Rate model with a non-limiting SHA stage in shared mode.
                    let model = VerifyProfile { sha: if shared_sha { SHARED_SHA_RINGS } else { sha }, ..v };
                    let rate = mhz * 1e6 / model.cycles(mode);
                    // Faster by more than 1/s, or equally fast with fewer LUTs.
                    if best.is_none_or(|b| rate > b.rate + 1.0 || (rate > b.rate - 1.0 && cost.lut < b.cost.lut)) {
                        best = Some(ModulePlan { profile: v, rate, cost, share, limit: limit_of(cost, &share), multiplier });
                    }
                }
            }
        }
    }
    }
    best
}

/// Plan both modules for the budget controls. Each module is planned
/// independently inside its own share (no SHA sharing); a module with zero
/// power is left out.
pub fn plan_system(b: &SystemBudget, c: &Costs) -> SystemPlan {
    let sign_power = b.sign_power.clamp(0.0, 100.0);
    // Verification gets at most what signing left over, so the two shares
    // never sum to more than 100 %.
    let verify_power = b.verify_power.clamp(0.0, 100.0 - sign_power);
    let sign = if sign_power > 0.0 { plan_sign(b.share(sign_power), c, b.mhz) } else { None };
    let verify = if verify_power > 0.0 { plan_verify(b.share(verify_power), b.mode, c, b.mhz) } else { None };
    // Sum of the planned modules' resources.
    let mut total = Cost::default();
    if let Some(s) = &sign {
        total = total.add(s.cost, 1);
    }
    if let Some(v) = &verify {
        total = total.add(v.cost, 1);
    }
    SystemPlan { sign, verify, total }
}