rhdl_dsig_scalable_core/ubft/

mod.rs

//! DSig as the signature service of a uBFT replica (feature `ubft`).
//!
//! # The problem
//!
//! [uBFT](https://github.com/YiJiang0908/ubft_new) is a consensus engine that
//! runs entirely on an Alveo U280: a Vitis HLS state machine (`ubft`) that
//! talks to its peers through a RoCE stack and keeps its mailboxes in HBM.
//! On its slow path every replica signs a 64-bit summary of the slot, sends
//! the signature to every peer, and verifies the shares it receives until
//! it holds `2f + 1`. It does both with the Vitis Security Library's
//! Ed25519 (`xf::security::eddsaEd25519`), called inline: the replica's
//! whole state machine stops for every signature and every verification,
//! and that signer is the routed design's worst path (−2.866 ns), which
//! pulls the shared kernel clock from 300 MHz down to 161.3 MHz.
//!
//! The rest of this crate signs and verifies in *batches*: the host fills
//! HBM, starts a kernel, and reads frames or verdicts back when it is done.
//! A consensus engine cannot work that way. It needs a service that sits
//! next to it on the chip, takes one request at a time on a stream, and
//! answers in microseconds.
//!
//! # The idea
//!
//! [`UbftEngine`] is that service: the same slices, certificate unit, verify
//! core and Ed25519 verify core as the batch kernels, with AXI4-Stream ports
//! where those have HBM masters.
//!
//! ```text
//!   uBFT (HLS) ──sign request──▶ ┌──────────────── UbftEngine ───────────────┐
//!              ◀──26-beat frame── │ UbftSigner: dealer ▶ slices ▶ arbiter     │
//!                                 │             cert unit (Ed25519 signer)    │
//!   uBFT (HLS) ──verify request─▶ │ UbftVerifier: framing ▶ verify core ▶ tags│
//!              ◀──verdict word─── │ Ed25519 verify core, 8 trusted key slots  │
//!                                 └──────── AXI4-Lite: keys, counters ────────┘
//! ```
//!
//! * **Signing.** A request is one 64-byte beat: the 16-byte message and an
//!   8-byte tag. The dealer hands it to the first idle slice; the slice
//!   signs it with a one-time key it made in advance, and the frame (26
//!   beats, the format of [`crate::slice_signer`], the tag in the message
//!   index field) leaves on the frame stream. Keys are made all the time in
//!   the background, so a request never waits for key generation.
//! * **Verifying.** A request is a header beat (the signer's key slot and a
//!   32-bit tag) followed by the 26 beats of the frame exactly as the
//!   signer produced it. The verdict word comes back in request order.
//! * **Peers.** uBFT has one signer per replica, so the verifier trusts up to
//!   [`KEY_SLOTS`] Ed25519 keys at once (replicas `N ≤ 9`). The certificate
//!   cache keeps the key slot with every entry (see
//!   [`crate::verify::certs`]): a certificate checked for one replica never
//!   answers for another.
//!
//! # Streams
//!
//! | Port | Direction | Beat | Content |
//! |---|---|---|---|
//! | `s_axis_sign` | in | 512 bits | bytes 0..16 message, 16..24 tag (LE64) |
//! | `m_axis_frame` | out | 512 bits, `tlast` on beat 25 | the frame: 1,642-byte signature, tag at 1642..1650 |
//! | `s_axis_verify` | in | 512 bits, `tlast` on beat 26 | beat 0: byte 0 key slot (4 bits), bytes 4..8 tag (LE32); beats 1..26: the frame |
//! | `m_axis_verdict` | out | 64 bits | bits 0..8 verdict ([`crate::verify`]), 8..12 key slot, 32..64 tag |
//! | `m_axis_cert` | out | 512 bits, `tlast` on beat 1 | this signer's new batch certificate: commitment, then Ed25519 signature |
//! | `s_axis_cert` | in | 512 bits, `tlast` on beat 2 | a peer's announced certificate: header (byte 0 key slot), commitment, signature |
//!
//! The certificate streams are optional: uBFT forwards `m_axis_cert` to
//! its peers and feeds theirs into `s_axis_cert`, so a batch's certificate
//! is checked before its first signature arrives (a cache miss otherwise
//! costs one Ed25519 check, ~52,670 cycles). Leave `s_axis_cert` idle and
//! `m_axis_cert` drained to skip it.
//!
//! A verdict of `0x80` means valid; any other value has bit 7 set and names
//! the failed checks.
//!
//! # Register map (32-bit words)
//!
//! | Offset | Name | Access |
//! |---|---|---|
//! | `0x000` | `AP_CTRL`: bit 0 `ap_start`, 1 `ap_done` (clear on read), 2 `ap_idle`, 3 `ap_ready` | RW |
//! | `0x004`/`0x008`/`0x00c` | `GIE` / `IER` / `ISR` | RW |
//! | `0x010` | arg `sign_count`: signatures this session (u32) | W |
//! | `0x014` | arg `verify_count`: verifications this session (u32) | W |
//! | `0x018` | arg `batches`: key batches to make (u32, 128 keys each) | W |
//! | `0x020` | arg `epoch` (u64) | W |
//! | `0x028` | arg `first_batch` (u64) | W |
//! | `0x030 + 4w` | args `cv0..cv7`: derive-key prefix CV (secret) | W |
//! | `0x050 + 4w` | args `seed0..seed7`: Ed25519 seed (secret) | W |
//! | `0x070` | arg `key_mask`: trusted key slots in use (bits 0..8) | W |
//! | `0x080 + 0x20·s + 4w` | args `key{s}_{w}`: slot `s`'s Ed25519 public key, bytes `4w..4w+4` LE | W |
//! | `0x180 + 8·s` | args `epoch{s}` (u64, lo then hi): slot `s`'s signer's epoch this session | W |
//! | `0x1c0` | arg `epoch_mask`: slots whose epoch is enforced (bits 0..8; see [`verifier`], session epochs) | W |
//! | `0x200` | `MAGIC` = [`MAGIC`] ("DSU1") | R |
//! | `0x204` | `ABI` = [`ABI_VERSION`] | R |
//! | `0x208` | `SHAPE`: slices bits 0..8, table mask 8..24, key slots 24..28 | R |
//! | `0x20c` | `FAULT`: bit 0 slice, 1 certificate unit, 2 Ed25519 verify core, 3 a trusted key rejected, 4 verify stream framing | R |
//! | `0x210`/`0x214` | `TICKS` lo (snapshots hi) / hi | R |
//! | `0x218`/`0x21c` | `START_TICK` lo/hi | R |
//! | `0x220`/`0x224` | `DONE_TICK` lo/hi | R |
//! | `0x228`/`0x22c` | `KEY_TICK` lo/hi: the trusted keys finished loading | R |
//! | `0x230` | `SIGNED`: frames sent | R |
//! | `0x234` | `SIGN_TAKEN`: sign requests accepted | R |
//! | `0x238` | `VERIFIED`: verdicts sent | R |
//! | `0x23c` | `VALID`: verdicts that were `0x80` | R |
//! | `0x240` | `CERT_CHECKS`: Ed25519 verifications issued | R |
//! | `0x244` | `CERT_FAILS` | R |
//! | `0x248` | `CERTIFIED`: batches the signer certified | R |
//! | `0x24c` | `ANNOUNCED`: certificates sent on `m_axis_cert` | R |
//! | `0x250 + 4i` | sign latency: `N`, `LAST`, `MIN`, `MAX`, `SUM` lo, `SUM` hi | R |
//! | `0x270 + 4i` | verify latency: same six words | R |
//! | `0x2a0 + 4w` | `PUBLIC_KEY`: the signer's Ed25519 public key (8 × u32) | R |
//!
//! # How latency is measured
//!
//! The kernel times requests on its own clock. A request that arrives while
//! no other request of its kind is in flight starts a measurement: the tick
//! of its first beat's handshake. The measurement ends on the handshake of
//! its answer's last beat, if no second request arrived meanwhile. So `N`
//! counts *isolated* requests, and `LAST`/`MIN`/`MAX`/`SUM` are their
//! latencies in cycles, request beat to answer beat, with nothing else in
//! the service. Loaded latency is not measured here.
//!
//! # The rules from the batch kernels still hold
//!
//! One session per reset: the kernel never restarts, the host gives every
//! session a fresh namespace (epoch, batch range, master seed), and the
//! secrets have no read path. A one-time key is burned before its frame
//! leaves, so a stalled frame stream can never cause a key to sign twice.

pub mod card;
pub mod engine;
pub mod probe;
pub mod signer;
pub mod verifier;

pub use card::{CardInput, CardOutput, UbftCard};
pub use engine::{CfgWrite, UbftEngine, UbftInput, UbftOutput};
pub use probe::UbftProbe;
pub use signer::UbftSigner;
pub use verifier::UbftVerifier;

use rhdl::prelude::*;

/// `MAGIC` register value ("DSU1" in little-endian ASCII).
pub const MAGIC: b32 = b32(0x3155_5344);
/// Register-map version.
pub const ABI_VERSION: b32 = b32(0x0001_0001);
/// Trusted Ed25519 keys the verifier holds at once (the verify core's key
/// slots): replicas `N ≤ KEY_SLOTS + 1`.
pub const KEY_SLOTS: usize = 8;
/// Verify requests that may be in flight (the verify core's contexts).
pub const VERIFY_IN_FLIGHT: usize = 64;
/// Beats of a verify request: the header and the 26-beat frame.
pub const VERIFY_REQUEST_BEATS: usize = 27;

/// Offsets of the host arguments.
pub const ARG_SIGN_COUNT: usize = 0x010;
/// `verify_count`.
pub const ARG_VERIFY_COUNT: usize = 0x014;
/// `batches`.
pub const ARG_BATCHES: usize = 0x018;
/// `epoch` (u64).
pub const ARG_EPOCH: usize = 0x020;
/// `first_batch` (u64).
pub const ARG_FIRST_BATCH: usize = 0x028;
/// `cv0`.
pub const ARG_CV: usize = 0x030;
/// `seed0`.
pub const ARG_SEED: usize = 0x050;
/// `key_mask`.
pub const ARG_KEY_MASK: usize = 0x070;
/// `key0_0`; slot `s`, word `w` at `+ 0x20·s + 4w`.
pub const ARG_KEYS: usize = 0x080;
/// `epoch{s}` (slot 0's low word; high word at +4, slots at +8).
pub const ARG_EPOCHS: usize = 0x180;
/// `epoch_mask`.
pub const ARG_EPOCH_MASK: usize = 0x1c0;
/// Status registers.
pub const REG_MAGIC: usize = 0x200;
/// `ABI`.
pub const REG_ABI: usize = 0x204;
/// `SHAPE`.
pub const REG_SHAPE: usize = 0x208;
/// `FAULT`.
pub const REG_FAULT: usize = 0x20c;
/// `TICKS` lo.
pub const REG_TICKS: usize = 0x210;
/// `START_TICK` lo.
pub const REG_START_TICK: usize = 0x218;
/// `DONE_TICK` lo.
pub const REG_DONE_TICK: usize = 0x220;
/// `KEY_TICK` lo.
pub const REG_KEY_TICK: usize = 0x228;
/// `SIGNED`.
pub const REG_SIGNED: usize = 0x230;
/// `SIGN_TAKEN`.
pub const REG_SIGN_TAKEN: usize = 0x234;
/// `VERIFIED`.
pub const REG_VERIFIED: usize = 0x238;
/// `VALID`.
pub const REG_VALID: usize = 0x23c;
/// `CERT_CHECKS`.
pub const REG_CERT_CHECKS: usize = 0x240;
/// `CERT_FAILS`.
pub const REG_CERT_FAILS: usize = 0x244;
/// `CERTIFIED`.
pub const REG_CERTIFIED: usize = 0x248;
/// `ANNOUNCED`.
pub const REG_ANNOUNCED: usize = 0x24c;
/// Sign latency block (six words).
pub const REG_SIGN_LATENCY: usize = 0x250;
/// Verify latency block (six words).
pub const REG_VERIFY_LATENCY: usize = 0x270;
/// `PUBLIC_KEY` words.
pub const REG_PUBLIC_KEY: usize = 0x2a0;

/// One 512-bit stream beat (`tvalid`, `tdata`, `tlast`; `tready` travels
/// the other way as a plain `bool`).
#[derive(Clone, Copy, Debug, PartialEq, Digital)]
pub struct Axis512 {
    /// `tvalid`.
    pub valid: bool,
    /// `tdata`, byte 0 in bits 0..8.
    pub data: [b8; 64],
    /// `tlast`.
    pub last: bool,
}

impl Axis512 {
    /// No beat.
    #[must_use]
    pub fn idle() -> Self {
        Self {
            valid: false,
            data: [b8(0); 64],
            last: false,
        }
    }
}

/// One 64-bit stream beat (the verdict stream).
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct Axis64 {
    /// `tvalid`.
    pub valid: bool,
    /// `tdata`.
    pub data: b64,
}

/// Isolated-request latency statistics, in cycles.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct Latency {
    /// A measurement is open.
    pub open: bool,
    /// Its start tick.
    pub start: b64,
    /// Measurements taken.
    pub n: b32,
    /// The last one.
    pub last: b32,
    /// The smallest.
    pub min: b32,
    /// The largest.
    pub max: b32,
    /// Their sum.
    pub sum: b64,
}

/// Opens or closes a latency measurement.
///
/// * `begin`: a request handshake happened while `in_flight` (before it)
///   was zero.
/// * `end`: an answer's last handshake happened while `in_flight` (before
///   it) was one.
/// * `abandon`: a second request arrived while one was measured.
#[kernel]
pub fn latency_kernel(l: Latency, ticks: b64, begin: bool, end: bool, abandon: bool) -> Latency {
    let mut n = l;
    if end && l.open {
        let sample: b32 = (ticks - l.start).resize();
        n.open = false;
        n.n = l.n + b32(1);
        n.last = sample;
        n.min = if l.n == b32(0) || sample < l.min { sample } else { l.min };
        n.max = if sample > l.max { sample } else { l.max };
        n.sum = l.sum + sample.resize::<64>();
    }
    if abandon {
        n.open = false;
    }
    if begin {
        n.open = true;
        n.start = ticks;
    }
    n
}