rhdl_dsig_scalable_core/

slice.rs

//! One complete slice: factory, subtree builder, signer and key cache.
//!
//! # Why slices exist
//!
//! Almost all of DSig's work is hashing, and almost all of the hashing is
//! making one-time keys (68 W-OTS+ chains per key). The way to sign faster is
//! to make keys faster, and the way to do *that* within a LUT budget is to
//! build one compact unit that makes and spends keys on its own, then copy it.
//! That unit is a **slice**. Each slice makes one key per 68 clocks, so the
//! engine's signing rate grows with the number of slices
//! ([`SLICES`](crate::SLICES)).
//!
//! This is the unit the [sustained engine](crate::sustained) repeats eight
//! times. Everything a signature needs is made and spent inside it, except the
//! batch certificate, which comes from the shared [`cert_unit`](crate::cert_unit).
//!
//! ```text
//!                 ┌──────────────────────── Slice ───────────────────────────┐
//!   config ──────▶│ SliceFactory ──cache_write──▶ 4 × UltraRAM cache banks    │
//!                 │   │ key_done      ▲ Merkle/message slots      │ nodes     │
//!                 │   ▼               │                           ▼           │
//!                 │ SubtreeBuilder ───┘          SliceSigner ◀── proof port   │
//!                 │   │ subtree root               │   ▲ certificate        │
//!                 └───┼────────────────────────────┼───┼─────────────────────┘
//!                     ▼                            ▼   │
//!               cert_unit (shared)            frame beats ─▶ HBM writer
//! ```
//!
//! | Part | Module | Role in the slice |
//! |---|---|---|
//! | `factory` | [`crate::slice_factory`] | makes one key per 68 clocks; also hashes Merkle parents and messages for the others |
//! | `bank0..bank3` | [`crate::cache_bank`] | hold chain positions 0..3 of 512 keys until they are spent |
//! | `subtree` | [`crate::slice_merkle`] | builds this slice's subtree of every batch, keeps the nodes for proofs |
//! | `signer` | [`crate::slice_signer`] | burns a key per message and writes a 1,642-byte signature frame |
//!
//! This file contains almost no logic. It is wiring: it connects the parts
//! and computes one signal of its own, `space` (cache admission, below).
//!
//! The same slice drawn as dataflow, with its clock budget and its routed LUT
//! cost. The three chain lanes are what make it fast and what make it big:
//!
#![doc = concat!("<div style=\"overflow-x:auto\">", include_str!("../docs/images/dsig-slice.svg"), "</div>")]
//!
//! # The life of one key
//!
//! ```text
//!   factory starts key n ───▶ 68 chains written to cache slot n mod 512
//!        (needs `space`)          │ key_done (pk_hash, nonces, batch, j)
//!                                 ├──▶ signer: metadata RAM
//!                                 └──▶ subtree: leaf j → … → subtree root ─▶ cert unit
//!                                                                  │
//!   cert unit ─▶ certificate for the batch ─▶ signer FIFO ◀────────┘ (much later)
//!   message arrives ─▶ signer BURNS key n (consumed += 1) ─▶ reads nodes ─▶ frame
//! ```
//!
//! A key is spent ("burned") the moment the signer accepts a message for it,
//! before any output is produced. If a frame is lost afterwards, the key is
//! still gone. The project rule is that a one-time key is never reused after
//! admission, timeout, reset or an uncertain launch; burning first is what
//! makes that true here, because the counter only moves forward.
//!
//! # Cache admission
//!
//! The factory assigns cache slots in a ring of
//! [`CACHE_SLOTS`](crate::slice_factory::CACHE_SLOTS) = 512 keys (32 batches).
//! Each bank stores them densely, 68 rows per key
//! ([`cache_address_kernel`](crate::slice_factory::cache_address_kernel)).
//! The factory may start key `n` only while `started − consumed <`
//! [`ADMIT_LIMIT`] `= 512 − KEYS_PER_SLICE`, so at least one whole batch of
//! slack remains:
//!
//! * slot `n mod 512` is free, because key `n − 512` was burned long ago;
//! * the subtree ring entry of batch `b` is free, because **every** key of the
//!   batch that last used it has been burned. Leaf `j` and its parents overwrite nodes
//!   that are *siblings* of other keys in the old batch, so freeing only key
//!   `n − 512` would not be enough.
//!
//! ```text
//!   key numbers in one slice, 8-slice build (512 slots, 16 keys per batch)
//!
//!   … burned │ in flight: made, not burned │ may still start │ kept free │
//!   ─────────┼─────────────────────────────┼─────────────────┼───────────┼──▶ key n
//!        consumed                       started     consumed + 496  consumed + 512
//!
//!   start allowed while started − consumed < ADMIT_LIMIT = 512 − 16 = 496
//! ```
//!
//! When the signer falls behind (HBM stalls, or certificates still in flight),
//! the factory simply skips key starts: every compression of a skipped key
//! becomes an idle slot.

use crate::ELEMENT_BYTES;
use crate::cache_bank::CacheBank;
use crate::slice_factory::{
    CACHE_ADDRESS_BITS, CACHE_ROWS, CACHE_SLOTS, FactoryConfig, SliceFactory, SliceFactoryInput,
    TWO_BLOCK_MESSAGE, cache_address_kernel,
};
use crate::slice_merkle::NODE_RING_BATCHES;
use crate::slice_merkle::{SubtreeBuilder, SubtreeInput, SubtreeRoot};
use crate::slice_signer::{Certificate, FrameBeat, Message, SignerInput, SliceSigner};
use crate::cert_unit::ROOT_QUEUE;
use crate::{KEYS_PER_SLICE, SLICES, SUBTREE_LEVELS};
use rhdl::prelude::*;
use rhdl_fpga::core::ram::synchronous::{In as RamIn, Write as RamWrite};

// The slices together cover exactly one batch of 128 keys.
const _: () = assert!(SLICES * KEYS_PER_SLICE == crate::BATCH_KEYS);
// The subtree ring and the cache ring advance together, one batch per KEYS_PER_SLICE keys.
const _: () = assert!(NODE_RING_BATCHES * KEYS_PER_SLICE == CACHE_SLOTS);
// Every cache row must be reachable with the bank's 16-bit address.
const _: () = assert!(CACHE_ROWS <= 1 << CACHE_ADDRESS_BITS);

/// Keys that may be started but not yet burned: the cache less one batch.
///
/// 512 − 16 = 496 in the 8-slice build. The missing batch is the safety
/// margin that guarantees a reused slot or subtree ring entry belongs only to
/// keys that are already burned (see the module docs).
pub const ADMIT_LIMIT: usize = CACHE_SLOTS - KEYS_PER_SLICE;

/// Slice inputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SliceInput {
    /// Key-factory configuration (includes this slice's number).
    pub config: FactoryConfig,
    /// Allow key starts.
    pub run: bool,
    /// Next message.
    pub message: Message,
    /// Certificate offered by the shared unit.
    pub certificate: Certificate,
    /// The HBM writer accepts the presented beat.
    pub beat_ready: bool,
    /// Batches whose roots the cert unit has taken
    /// ([`CertOutput::roots_popped`](crate::cert_unit::CertOutput::roots_popped)):
    /// root credit for the factory.
    pub roots_popped: b32,
}

/// Slice outputs.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct SliceOutput {
    /// Subtree root pulse for the shared unit.
    pub root: SubtreeRoot,
    /// The offered certificate was accepted.
    pub certificate_taken: bool,
    /// The message was consumed.
    pub message_taken: bool,
    /// Frame beat for the HBM writer.
    pub beat: FrameBeat,
    /// Real keys started.
    pub keys_started: b32,
    /// Keys burned.
    pub keys_consumed: b32,
    /// Frames handed to the writer.
    pub frames_out: b32,
    /// Subtree job queue overflowed (design error).
    pub fault: bool,
}

/// One slice of the sustained engine.
///
/// `TABLE_MASK` is the chain-lane area knob, passed through to the factory:
/// it chooses which AES rounds of the Haraka lane use table ROMs (see
/// [`crate::chain_step`]).
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct Slice<const TABLE_MASK: usize> {
    /// Makes keys; also runs the subtree's and signer's BLAKE3 requests.
    factory: SliceFactory<TABLE_MASK>,
    /// Builds this slice's Merkle subtree of each batch.
    subtree: SubtreeBuilder,
    /// Spends keys: one signature frame per message.
    signer: SliceSigner,
    /// Key cache, chain position 0 of every cached key.
    bank0: CacheBank,
    /// Key cache, chain position 1.
    bank1: CacheBank,
    /// Key cache, chain position 2.
    bank2: CacheBank,
    /// Key cache, chain position 3.
    bank3: CacheBank,
}

impl<const TABLE_MASK: usize> Default for Slice<TABLE_MASK> {
    /// Every part in its own reset state.
    fn default() -> Self {
        Self {
            factory: SliceFactory::default(),
            subtree: SubtreeBuilder::default(),
            signer: SliceSigner::default(),
            bank0: CacheBank::default(),
            bank1: CacheBank::default(),
            bank2: CacheBank::default(),
            bank3: CacheBank::default(),
        }
    }
}

/// Input: config, messages, certificates and writer back-pressure. Output:
/// subtree roots, frame beats and counters.
impl<const TABLE_MASK: usize> SynchronousIO for Slice<TABLE_MASK> {
    type I = SliceInput;
    type O = SliceOutput;
    type Kernel = slice_kernel<TABLE_MASK>;
}

/// One cache bank's port: write position `p` of a chain, read the signer's address.
///
/// * `write_valid`, `write_address`, `value`: the factory's write of one
///   18-byte node (the same address for all four banks, a different `value`).
/// * `read_address`: the signer's read row (the same for all four banks).
/// * Returns the bank's RAM input. Combinational; no registers.
#[kernel]
pub fn bank_port_kernel(
    write_valid: bool,
    write_address: b16,
    value: [b8; ELEMENT_BYTES],
    read_address: b16,
) -> RamIn<[b8; ELEMENT_BYTES], 16> {
    RamIn::<[b8; ELEMENT_BYTES], 16> {
        read_addr: read_address,
        write: RamWrite::<[b8; ELEMENT_BYTES], 16> {
            addr: write_address,
            value,
            enable: write_valid,
        },
    }
}

/// `log2 KEYS_PER_SLICE` as a shift amount: `keys_started >> SUBTREE_SHIFT`
/// is the batch of the next key (RHDL shifts take `Bits`, not `usize`).
pub const SUBTREE_SHIFT: b32 = b32(SUBTREE_LEVELS as u128);

/// Pure wiring between the slice's parts.
///
/// In an RHDL kernel, `q.factory`, `q.signer` and so on are the parts'
/// current outputs, and the fields of `d` are their next inputs. This kernel
/// only connects outputs to inputs. The only signals it computes are `space`
/// (the admission test) and the shared cache write address.
#[kernel]
pub fn slice_kernel<const TABLE_MASK: usize>(
    _clock_reset: ClockReset,
    input: SliceInput,
    q: SliceQ<TABLE_MASK>,
) -> (SliceOutput, SliceD<TABLE_MASK>) {
    // Current outputs of the factory and the signer.
    let factory = q.factory;
    let signer = q.signer;
    // Keys made (or being made) but not yet burned. 32-bit counters; the
    // subtraction stays correct across wrap-around.
    let in_flight = factory.keys_started - signer.consumed;
    // Batch (relative to the run) of the next key this slice would start:
    // each slice makes KEYS_PER_SLICE keys of every batch, in order.
    let next_batch: b32 = factory.keys_started >> SUBTREE_SHIFT;
    // Root credit: the cert unit's root queue holds ROOT_QUEUE roots per
    // slice, so only batches below `roots_popped + ROOT_QUEUE` may be made.
    // Wrapping subtraction keeps this right across counter wrap-around.
    let root_room = (next_batch - input.roots_popped) < b32(ROOT_QUEUE as u128);
    // The factory may start another key only below the admission limit and
    // with root credit.
    let space = in_flight < b32(ADMIT_LIMIT as u128) && root_room;
    // The factory's cache write this cycle: four positions of one chain.
    let write = factory.cache_write;
    // Row `slot × 68 + chain`, shared by all four banks.
    let write_address = cache_address_kernel(write.slot, write.chain);
    let d = SliceD::<TABLE_MASK> {
        // Factory: config, the admission flag and the two borrowed hash
        // slots (Merkle parents from the subtree, message hashes from the
        // signer).
        factory: SliceFactoryInput {
            config: input.config,
            run: input.run,
            space,
            merkle: q.subtree.merkle,
            message: signer.request,
        },
        // Subtree: leaves and parent results from the factory, proof reads
        // from the signer.
        subtree: SubtreeInput {
            key_done: factory.key_done,
            merkle_taken: factory.merkle_taken,
            slot_result: factory.slot_result,
            proof_address: signer.proof_address,
        },
        // Signer: messages and certificates from outside, key metadata and
        // message hashes from the factory, nodes from the banks, siblings
        // from the subtree.
        signer: SignerInput {
            slice: input.config.slice,
            message: input.message,
            key_done: factory.key_done,
            certificate: input.certificate,
            message_taken: factory.message_taken,
            slot_result: factory.slot_result,
            cache_data: [q.bank0, q.bank1, q.bank2, q.bank3],
            proof_data: q.subtree.proof_data,
            beat_ready: input.beat_ready,
        },
        // Bank p stores position p of the chain the factory just finished.
        bank0: bank_port_kernel(
            write.valid,
            write_address,
            write.nodes[0],
            signer.cache_address,
        ),
        bank1: bank_port_kernel(
            write.valid,
            write_address,
            write.nodes[1],
            signer.cache_address,
        ),
        bank2: bank_port_kernel(
            write.valid,
            write_address,
            write.nodes[2],
            signer.cache_address,
        ),
        bank3: bank_port_kernel(
            write.valid,
            write_address,
            write.nodes[3],
            signer.cache_address,
        ),
    };
    (
        SliceOutput {
            root: q.subtree.root,
            certificate_taken: signer.certificate_taken,
            // Profile 2: the factory also takes tail blocks, which consume no
            // message; the signer's flag is true only when a first block
            // burns a key. Profile 1 has no tails, so the two agree.
            message_taken: if TWO_BLOCK_MESSAGE { signer.message_taken } else { factory.message_taken },
            beat: signer.beat,
            keys_started: factory.keys_started,
            keys_consumed: signer.consumed,
            frames_out: signer.frames_out,
            fault: q.subtree.overflow,
        },
        d,
    )
}