rhdl_dsig_scalable_core/

packer.rs

//! Pack 18-byte chain nodes into 64-byte words.
//!
//! # The problem
//!
//! Hash chains produce 18-byte nodes ([`ELEMENT_BYTES`]), but the rest of the
//! hardware moves 64-byte words: a BLAKE3 block is 64 bytes and an HBM beat
//! (one transfer on the memory bus) is 64 bytes. Somebody has to glue a
//! stream of 18-byte pieces into a stream of 64-byte words, with no gaps.
//!
//! Two places in a slice turn a stream of 18-byte nodes into 64-byte words:
//!
//! | Stream | Prefix | Then | Total |
//! |---|---|---|---|
//! | Endpoint commitment (BLAKE3 blocks) | `pk_nonce`, 16 B | 68 chain ends | 1,240 B |
//! | Signature frame tail (HBM beats) | last 34 header bytes | 68 revealed nodes | 1,258 B |
//!
//! The first is used by the [key factory](crate::slice_factory) to hash the
//! 68 chain ends into `pk_hash` (the key's public commitment). The second is
//! used by the [signer](crate::slice_signer) to lay the 68 revealed nodes
//! into the signature frame right after the header. Both are the same circuit,
//! [`ElementPacker`], with a different prefix length `P`.
//!
//! # Why it is tricky
//!
//! 18 does not divide 64, so each node lands at a different byte offset. The
//! sequence of offsets repeats every 32 nodes (`32 × 18 = 9 × 64`).
//!
//! ```text
//!   word 0: [ prefix (P bytes) | node 0 | node 1 | node 2 | node 3 (part) ]
//!   word 1: [ node 3 (rest) | node 4 | node 5 | node 6 (part) ]   …
//! ```
//!
//! For the signature stream (`P = 34`) the first words look like this:
//!
//! ```text
//!   byte:    0          34        52     64
//!   word 0:  [ header tail | node 0 | node 1: 12 B ]
//!   word 1:  [ node 1: 6 B | node 2 | node 3 | node 4 | node 5: 4 B ] ...
//!   last:    [ ... node 67 ends at byte 42 | zero padding ]   (1,258 = 19 × 64 + 42)
//! ```
//!
//! The packer keeps a *fill* counter (bytes already used in the current
//! word). Each new node is placed at offset `fill`. If it fits, `fill` grows
//! by 18. If it crosses the 64-byte edge, the full word is emitted and the
//! 0 to 17 overflow bytes (the *remainder*) start the next word.
//!
//! [`ElementPacker`] accepts at most one node per cycle and emits at most one
//! word per cycle. Both streams have the property that the 68th node never
//! completes a word *and* leaves a remainder, so a single output suffices. A
//! compile-time assertion checks this for each prefix length.
//!
//! # Why the kernel looks unusual
//!
//! RHDL lowers every array-element assignment into a copy of the whole array,
//! so "for each offset, for each byte, maybe write it" would emit thousands
//! of 512-bit copies. Instead each output byte is one OR of ANDs over a
//! zero-padded copy of the node ([`place_kernel`]). Every index is a
//! compile-time constant in range, and synthesis folds the padding zeros away,
//! leaving an 18-way select per byte.
//!
//! # Timing
//!
//! One register stage: a node presented with `valid` in cycle `t` produces
//! its word (if any) on the output in cycle `t + 1`.

use crate::{CHAINS, ELEMENT_BYTES};
use rhdl::prelude::*;
use rhdl_fpga::core::dff::DFF;

/// Prefix length of the endpoint-commitment stream (`pk_nonce`).
pub const COMMITMENT_PREFIX: usize = 16;
/// Prefix length of the signature-frame tail: the 1,642-byte wire format puts
/// 418 header bytes before the nodes, and `418 = 6 × 64 + 34`.
///
/// The first 384 header bytes fill six whole beats that the signer writes
/// itself; the last 34 share beat 6 with node 0, so they go through the
/// packer as its prefix.
pub const SIGNATURE_PREFIX: usize = 34;

/// Whether `prefix` keeps the 68th node from overflowing into a second word.
///
/// `before_last` is the byte offset where node 67 starts inside its word. If
/// node 67 fits completely in that word, the stream ends with exactly one
/// partial word and the single output register is enough. The prefix must
/// also be even and shorter than one word (assumptions the packer relies on).
#[must_use]
pub const fn single_flush(prefix: usize) -> bool {
    let before_last = (prefix + (CHAINS - 1) * ELEMENT_BYTES) % 64;
    before_last + ELEMENT_BYTES < 64 && prefix % 2 == 0 && prefix < 64
}

// Both real prefixes satisfy the one-output rule; checked at compile time.
const _: () = assert!(single_flush(COMMITMENT_PREFIX));
const _: () = assert!(single_flush(SIGNATURE_PREFIX));

/// Packer input; `start` must accompany node 0 of each stream.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct PackerInput {
    /// Prefix bytes for this stream; only the first `P` bytes are used.
    pub prefix: [b8; 64],
    /// This node is node 0: discard state and begin with the prefix.
    pub start: bool,
    /// The 18-byte node.
    pub node: [b8; ELEMENT_BYTES],
    /// A node is present this cycle.
    pub valid: bool,
}

impl Default for PackerInput {
    /// No node, no start, all-zero prefix and node.
    fn default() -> Self {
        Self {
            prefix: [b8(0); 64],
            start: false,
            node: [b8(0); ELEMENT_BYTES],
            valid: false,
        }
    }
}

/// One output word; bytes at and after `bytes` are zero.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct PackerOutput {
    /// The word, byte 0 first in stream order.
    pub word: [b8; 64],
    /// Meaningful bytes: 64, or fewer for the final word.
    pub bytes: b7,
    /// This is the stream's final word.
    pub last: bool,
    /// A word is presented this cycle.
    pub valid: bool,
}

/// The registered part of [`PackerOutput`] (everything except `valid`,
/// which lives in its own resettable register). Internal.
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
#[doc(hidden)]
pub struct PackerOut {
    /// The word being presented.
    word: [b8; 64],
    /// Meaningful bytes in `word` (64, or fewer for the final word).
    bytes: b7,
    /// `word` is the stream's final word.
    last: bool,
}

/// Registered packer for a stream with a `P`-byte prefix and 68 nodes.
///
/// `P` is a const generic so each stream gets its own copy with the prefix
/// length baked in (16 for the commitment, 34 for the signature).
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
pub struct ElementPacker<const P: usize> {
    /// The partly filled word: bytes `0..fill` are valid.
    accumulator: DFF<[b8; 64]>,
    /// Bytes already used in `accumulator` (0..64).
    fill: DFF<b7>,
    /// Nodes accepted so far in this stream (0..68); 67 marks the last node.
    count: DFF<b7>,
    /// The word presented on the output.
    out: DFF<PackerOut>,
    /// `out` holds a new word this cycle. The only register with a reset.
    out_valid: DFF<bool>,
}

impl<const P: usize> Default for ElementPacker<P> {
    /// Checks `P` at construction (panics for a prefix that would need two
    /// flush words) and clears only `out_valid`; `start` initializes the rest.
    fn default() -> Self {
        assert!(single_flush(P), "prefix {P} needs a two-word flush");
        Self {
            accumulator: DFF::resetless(),
            fill: DFF::resetless(),
            count: DFF::resetless(),
            out: DFF::resetless(),
            out_valid: DFF::new(false),
        }
    }
}

/// Input: at most one node per cycle. Output: at most one word per cycle,
/// one cycle later.
impl<const P: usize> SynchronousIO for ElementPacker<P> {
    type I = PackerInput;
    type O = PackerOutput;
    type Kernel = element_packer_kernel<P>;
}

/// Bytes of `node` shifted to start at offset `fill`, over 82 positions.
///
/// Position `p` (0..82) holds `node[p - fill]` when that index is in range,
/// else zero. `onehot[f]` is true exactly for `f == fill`.
///
/// 82 = 64 + 18: positions 0..64 are the current word, 64..82 the overflow
/// into the next word. Pure combinational logic, no registers.
#[allow(clippy::needless_range_loop)] // Static byte wiring.
#[kernel]
pub fn place_kernel(node: [b8; ELEMENT_BYTES], onehot: [bool; 64]) -> [b8; 82] {
    // padded[64 + k] = node[k]; all other entries are zero.
    // The 64 zeros in front let `64 + p - f` stay in range for every p, f,
    // so all indices below are constants and no bounds logic is generated.
    let mut padded = [b8(0); 146];
    for k in 0..ELEMENT_BYTES {
        padded[64 + k] = node[k];
    }
    let mut placed = [b8(0); 82];
    for p in 0..82 {
        // OR together the candidate byte for every possible fill; exactly
        // one `onehot[f]` is true, so this is a select, not a merge.
        let mut value = b8(0);
        for f in 0..64 {
            if onehot[f] {
                value = value | padded[64 + p - f];
            }
        }
        placed[p] = value;
    }
    placed
}

/// Wiring for [`ElementPacker`].
///
/// * `input.start` (with node 0): load the prefix and reset `fill` to `P`.
/// * `input.valid`: place the node at `fill`. If it crosses the word edge,
///   emit the full word and keep the remainder; on node 67, emit the final
///   partial word.
/// * Output: the registered word from the previous cycle; `valid` is forced
///   low during reset.
#[allow(clippy::needless_range_loop)] // Static byte wiring.
#[kernel]
pub fn element_packer_kernel<const P: usize>(
    clock_reset: ClockReset,
    input: PackerInput,
    q: ElementPackerQ<P>,
) -> (PackerOutput, ElementPackerD<P>) {
    let resetting = clock_reset.reset.any();
    // `base`, `fill`, `count`: the state this node builds on. Normally the
    // registers; on `start`, a fresh word holding only the prefix.
    let mut base = q.accumulator;
    let mut fill = q.fill;
    let mut count = q.count;
    if input.start {
        base = [b8(0); 64];
        for byte in 0..P {
            base[byte] = input.prefix[byte];
        }
        fill = b7(P as u128);
        count = b7(0);
    }
    // One-hot form of `fill` for `place_kernel`'s select.
    let mut onehot = [false; 64];
    for f in 0..64 {
        onehot[f] = fill == b7(f as u128);
    }
    // The node shifted to byte offset `fill` (82 positions, rest zero).
    let placed = place_kernel(input.node, onehot);
    // Keep accumulator bytes below `fill`; take placed bytes from `fill` on.
    let mut word = [b8(0); 64];
    for p in 0..64 {
        word[p] = if b7(p as u128) < fill {
            base[p]
        } else {
            placed[p]
        };
    }
    // Bytes that spilled past byte 63; they start the next word.
    let mut remainder = [b8(0); 64];
    for p in 0..ELEMENT_BYTES {
        remainder[p] = placed[64 + p];
    }
    // Bytes used after adding this node, and whether that fills the word.
    let total = fill + b7(ELEMENT_BYTES as u128);
    let crosses = total >= b7(64);
    // This node is node 67, the last of the stream.
    let last = count == b7((CHAINS - 1) as u128);
    // Default: hold state, present nothing next cycle.
    let mut d = ElementPackerD::<P> {
        accumulator: q.accumulator,
        fill: q.fill,
        count: q.count,
        out: q.out,
        out_valid: false,
    };
    if input.valid {
        d.count = count + b7(1);
        if crosses {
            // Word full: carry the overflow bytes into a new word.
            d.accumulator = remainder;
            d.fill = total - b7(64);
        } else {
            d.accumulator = word;
            d.fill = total;
        }
        // Emit on a full word, or on the last node (partial final word).
        // `single_flush` guarantees these never both need a word at once.
        if crosses || last {
            d.out = PackerOut {
                word,
                bytes: if crosses { b7(64) } else { total },
                last,
            };
            d.out_valid = true;
        }
    }
    (
        PackerOutput {
            word: q.out.word,
            bytes: q.out.bytes,
            last: q.out.last,
            valid: q.out_valid && !resetting,
        },
        d,
    )
}