rhdl_fpga_planner/

lib.rs

//! Planner for one U280 shared by Ed25519, DSig and a SHA-512 line.
//!
//! # Building for Wolverine's U280
//!
//! The planner runs on the host; it chooses configurations and does not emit a
//! U280 image. From the workspace root, `cargo tuner` runs the planner for both
//! papers and `cargo tuner-ed25519` selects Ed25519 alone. For just this library,
//! use `cargo build --locked -p rhdl_fpga_planner`.
//!
//! Take the selected configuration to the front-page build instructions for
//! [Ed25519](../rhdl_ed25519_scalable_core/index.html#building-for-wolverines-u280)
//! or [DSig](../rhdl_dsig_scalable_core/index.html#building-for-wolverines-u280):
//! generate RTL, package and link with Vitis 2023.2, then check routed acceptance.
//! A planner estimate is not evidence that a configuration fits or meets timing.
//!
//! Run commands from the workspace root. Before compilation or RTL generation,
//! record ownership in `PROJECT_COORDINATION.md` and
//! `/home/sahasta/Development/FPGA_COORDINATION.md`, and use the applicable
//! nonblocking `local-heavy.lock`; `crates/ed25519/tools/bounded.sh` wraps local
//! Cargo commands with that lock and resource limits. Reserve Wolverine builds
//! in both ledgers too, then use `crates/dsig/tools/with-u280-lock.sh` to hold
//! `u280.lock`. Do not bypass a busy lock.
//!
//! # The question it answers
//!
//! *Given a budget of LUTs, DSPs, BRAM and URAM, how should the chip be
//! divided, and how many signatures and how many verifications per second
//! does it deliver?* Two papers ask it with different modules ([`Mode`]):
//!
//! - **Ed25519 paper** ([`Mode::Ed25519`]): Ed25519 signing and Ed25519
//!   verification.
//! - **DSig paper** ([`Mode::Dsig`]): DSig signing and DSig verification,
//!   each with the Ed25519 work it relies on.
//! - **uBFT modes** ([`Mode::UbftEd25519`], [`Mode::UbftDsig`]): the same
//!   schemes as a service beside a uBFT replica. Only uBFT modules take
//!   part ([`Component::ubft`]). The replica's footprint comes off the
//!   whole device, and the headline is a consensus slot's crypto time
//!   rather than a rate ([`ubft`]).
//!
//! In both, a **SHA-512 line** is shared by every module that hashes on it.
//! Its allowance comes out of the budget (65k LUTs and 20 DSPs of the
//! default 485k and 4,520): the **LUT split** is SHA | DSig | Ed25519 in the
//! DSig paper and SHA | Ed25519 in the Ed25519 paper, each summing to 100 %.
//!
//! # Two sides: signing and verifying
//!
//! Signing and verification are independent services: a chip can be built
//! to sign a lot and verify little, or the opposite. So the budget is split
//! into a **sign side** and a **verify side** by two powers ([`Powers`]),
//! and each side reports its own delivered rate. A side can need several
//! modules ([`Side::roles`]):
//!
//! | Paper | Sign side delivers | needs per operation | Verify side delivers | needs per operation |
//! |---|---|---|---|---|
//! | Ed25519 | Ed25519 signatures | 1 Ed25519 sign | Ed25519 verifications | 1 Ed25519 verify |
//! | DSig | DSig signatures | 1 DSig sign + 1/K Ed25519 sign | DSig verifications | 1 DSig verify + (1 − h) Ed25519 verify |
//!
//! `K` is DSig's batch size (one Ed25519 signature certifies `K` one-time
//! keys) and `h` the fraction of verifications that find their batch's
//! root already verified ([`Context::cache_hit`]).
//!
//! # How a plan is made
//!
//! 1. **Shares.** The SHA line's allowance comes off the top; each other
//!    module gets a percentage of what is left of the LUTs, DSPs, BRAM and
//!    URAM ([`shares`], [`Budget::rest`]).
//! 2. **Best build per share.** Each module is a [`Component`]: given a
//!    share it returns the best build that fits ([`Plan`]): resources,
//!    **capacity** (operations per second), latency, and the SHA-512 blocks
//!    it hashes.
//! 3. **Lending** ([`plan_chip`]). What modules leave unused of their share
//!    is counted in real units and lent to the module whose re-plan raises
//!    the delivered rates most, until no module gains. The line's unused
//!    allowance (its pipelines come in steps) is lent too.
//! 3b. **The remainder.** What lending could not turn into delivered rate
//!    is still handed out, pro rata by power and then to whoever can use
//!    it, so every module grows (more capacity, more headroom) and nothing
//!    sits idle that a module could use.
//! 4. **Delivered rates** ([`deliver`]). A side delivers the smallest
//!    `capacity / need` over its roles. If both sides together want more
//!    SHA-512 blocks than the line supplies, both are scaled down to fit.
//! 5. **Background** ([`layout`], DSig paper): the budget is the HBSS
//!    foreground plus the EdDSA background (summing to 100 %), and the
//!    background is split between Ed25519 sign and verify (100 %); either
//!    can be set or chosen to deliver the most.
//! 6. **Splitting between sides** ([`balance_mix`], key B in the TUI):
//!    the sign power that maximizes `min(sign, verify / mix)`, where the
//!    **mix** is the verifications wanted per signature. The powers can also
//!    be set by hand.
//!
//! Every number is a *model* unless the component marks it
//! [measured](Plan::measured) (synthesized or routed in Vivado).
//!
//! The `tui` feature adds [`tui::run`], the interactive front end.
//!
//! # Where to go next
//!
//! | You want to... | Read |
//! |---|---|
//! | understand how a plan and its build config come about, step by step | [`decisions`] (start here) |
//! | change what a paper needs per operation | [`Mode::need`], then [`deliver`] |
//! | change how the budget is split | [`apply_layout`], [`layout`], [`balance_mix`] |
//! | add a module | [`Component`] and [`Plan`]; an example is `rhdl_ed25519_scalable_core::planner` |
//! | plan crypto for uBFT | [`ubft`] (replica, baseline, slot time), then [`Mode::admits`] |
//! | change the screen | [`tui`] (`App` holds the state, `draw` renders) |
//! | see the whole chip | the root crate `rhdl_signatures`: its guide and `tuner` binary |

#![warn(missing_docs)]

pub mod decisions;

/// The interactive terminal front end (feature `tui`).
#[cfg(feature = "tui")]
pub mod tui;

// The model, one file per step of "How a plan is made". Everything is
// re-exported here, so the crate's API stays flat (`rhdl_fpga_planner::Plan`).
mod component;
mod delivered;
mod layout;
mod lending;
mod resources;
mod shares;
pub mod ubft;
pub mod build_apply;
mod workload;

pub use component::*;
pub use delivered::*;
pub use layout::*;
pub use lending::*;
pub use resources::*;
pub use shares::*;
pub use workload::*;

#[cfg(test)]
pub(crate) mod demo;
#[cfg(test)]
mod tests;