Crate rhdl_fpga_planner

Expand description

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 or DSig: 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

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).
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.
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.
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.
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.
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 (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

Modules§

build_apply: Validate the small set of uBFT settings that currently reach real hardware.
decisions: How the planner decides: from your knobs to a build
tui: The interactive terminal front end (feature tui).
ubft: The uBFT modes’ shared parts: the replica the services sit beside, the baseline they replace, and what a consensus slot spends on crypto.

Structs§

Background: The DSig paper’s second split: the budget is foreground (the HBSS: DSig sign and DSig verify, divided by Powers) plus background (EdDSA: the Ed25519 sign and verify modules DSig relies on), and the background is divided between Ed25519 sign and verify. Each part sums to 100 %; None lets the planner choose (layout).
BackgroundUsed: The background actually used: both values chosen or given.
Budget: The global resource controls.
ChipPlan: The planned chip.
Context: Workload inputs every component sees.
Cost: Resources of one build.
Delivered: Delivered rates of the chip.
Flow: A throughput a component needs from, or offers to, other components.
Knob: One build option of a component.
Plan: The best build of a component within its share.
Powers: How the budget is divided between the two sides, in percent (summing to at most 100).
Service: Demand and supply of one service.
SideRate: What one side delivers.
Slot: A component with its share of the budget.

Enums§

Mode: Which paper the chip is planned for.
Resource: The four resources, in the order of Slot::limits.
Role: What a component does.
Side: Signing or verification.

Constants§

BASE_DSP: DSP budget that the 100 % setting means: 4,500 for the engines plus the SHA-512 line’s 20.
BASE_LUT: LUT budget that the 100 % setting means: 420k for the signature engines plus the SHA-512 line’s default 65k, which now comes out of the budget like everything else (SHA_DEFAULT_LUT).
BUDGET_BRAM36: BRAM36 that the 100 % BRAM setting means: the U280 shell’s dynamic region holds 3,552 BRAM18 sites (1,776 BRAM36), not the device’s 2,016. DSig’s build v4 failed placement asking for 4,033 BRAM18 there.
DSIG_BATCH: DSig’s default batch: one-time keys certified by one Ed25519 signature (used when the DSig module does not report its own, Plan::batch).
SHA512_BLOCKS: The planner’s name for SHA-512 compression throughput (blocks/s).
SHA_DEFAULT_LUT: The SHA-512 line’s default LUTs (13.4 % of BASE_LUT): with it, the default chip gives the engines the same 420k they had when the line sat outside the budget.
U280_BRAM36: Physical BRAM36 blocks of the XCU280.
U280_DSP: Physical DSP48E2 blocks of the XCU280.
U280_LUT: Physical CLB LUTs of the XCU280.
U280_URAM: Physical URAM blocks of the XCU280.

Traits§

Component: A part of the chip the planner can size.

Functions§

allowances: Each slot’s fixed allowance (None for a module with a power).
allowances_in: allowances of the slots mode admits (None for the rest): a uBFT chip has no SHA-512 line, and a paper no replica.
apply_layout: apply_powers with the DSig paper’s background bg; also returns the background used.
apply_powers: Set the module powers for powers (and, in the DSig paper, the background bg) and plan the chip. Slots outside the mode get 0.
balance_mix: The sign/verify split (summing to 100 %) that maximizes min(sign, verify / mix): what the B key does. With mix = 0 only signing counts. Returns the chosen powers; the slots are left at them.
balance_mix_with: balance_mix with the DSig paper’s background bg (the powers then split the HBSS foreground).
build_config: Every slot’s build flags as TOML text, one table per component.
deliver: Delivered rates of parts (the plans of slots) in mode.
fixed_total: Sum of the fixed allowances.
layout: The DSig paper’s background: the given values, or the planner’s.
layout_in: layout for a mode that follows the DSig paper (Mode::UbftDsig too).
plan_chip: Plan every slot of mode and the delivered rates.
plan_slot: slot’s best build in share, remembered across calls.
shares: Each slot’s share: fixed allowances as given (the SHA-512 line’s part of the LUT split); everyone else power % of what the budget has left after them (Budget::rest). A module’s manual limit on a resource gives it exactly that % of the resource; the rest of that resource is divided among the other modules in proportion to their powers.
shares_with: shares with the fixed allowances given per slot (a line the planner sizes to demand, Component::size_for).
side_slots: The slots of mode that work for side.

Type Aliases§

BuildFlags: Compile-time settings for one component’s build (written by the TUI).
Share: The resources one component may use.