rhdl_ubft/

ports.rs

//! The kernel's ports: the same as ubft_new's `ubft` kernel, so the Vitis
//! link (`config.cfg`) connects rhdl_ubft where ubft_new's kernel was.
//!
//! | Port | Kind | ubft_new | Here |
//! |---|---|---|---|
//! | `input` | AXI4-Stream in, 64 bits | `hls::stream<ProposedValue>` | [`Axis64`] |
//! | `output`, `remoteUpdate` | AXI4-Stream out, 256 bits | `hls::stream<ap_uint<256>>` | [`Axis256`] |
//! | `m_axis_tx_meta` | AXI4-Stream out, 256 + keep/last | `pkt256` | [`Axis256`] + [`TxSide`] |
//! | `m_axis_tx_data` | AXI4-Stream out, 512 + keep/last | `pkt512` | [`Axis512`] + [`TxSide`] |
//! | `s_axis_tx_status` | AXI4-Stream in, 512 | `pkt512` (drained) | [`Axis512`] |
//! | `network_ptr` | AXI4 master, 512-bit data | `m_axi gmem0` | [`AxiRead`]/[`AxiWrite`] |
//! | `message_ptr` | AXI4 master (reads) | `m_axi gmem1` | [`AxiRead`] |
//! | `s_axi_control` | AXI4-Lite | arguments and `ap_ctrl_hs` | [`AxiLiteIn`]/[`AxiLiteOut`] |
//!
//! Words are little-endian 64-bit lanes: lane 0 holds bits 0..64.

use rhdl::prelude::*;

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

/// A 256-bit stream beat.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct Axis256 {
    /// `tvalid`.
    pub valid: bool,
    /// `tdata`, four lanes.
    pub data: [b64; 4],
    /// `tlast`.
    pub last: bool,
}

/// A 512-bit stream beat.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct Axis512 {
    /// `tvalid`.
    pub valid: bool,
    /// `tdata`, eight lanes.
    pub data: [b64; 8],
    /// `tkeep`: one bit per byte (byte 0 in bit 0).
    pub keep: b64,
    /// `tlast`.
    pub last: bool,
}

/// The `tkeep` of a meta beat (32 bytes, all kept).
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct TxSide {
    /// `tkeep` of the 256-bit meta beat.
    pub keep: b32,
}

/// AXI4 read requests from the kernel (INCR bursts of 64-byte beats).
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct AxiRead {
    /// AR `valid`.
    pub ar_valid: bool,
    /// AR byte address (64-byte aligned).
    pub ar_addr: b64,
    /// AR `len`: beats − 1.
    pub ar_len: b8,
    /// R `ready`.
    pub r_ready: bool,
}

/// AXI4 read responses to the kernel.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct AxiReadResp {
    /// AR `ready`.
    pub ar_ready: bool,
    /// R `valid`.
    pub r_valid: bool,
    /// R `data`, eight lanes.
    pub r_data: [b64; 8],
    /// R `last`.
    pub r_last: bool,
}

/// AXI4 write requests from the kernel (single 64-byte beats with byte
/// strobes).
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct AxiWrite {
    /// AW `valid`.
    pub aw_valid: bool,
    /// AW byte address (64-byte aligned).
    pub aw_addr: b64,
    /// W `valid`.
    pub w_valid: bool,
    /// W `data`.
    pub w_data: [b64; 8],
    /// W `strb`: one bit per byte.
    pub w_strb: b64,
    /// B `ready`.
    pub b_ready: bool,
}

/// AXI4 write responses to the kernel.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct AxiWriteResp {
    /// AW `ready`.
    pub aw_ready: bool,
    /// W `ready`.
    pub w_ready: bool,
    /// B `valid`.
    pub b_valid: bool,
}

/// AXI4-Lite requests (the layout of the Ed25519 and DSig services' port).
#[derive(Clone, Copy, Debug, Default, Digital, PartialEq)]
pub struct AxiLiteIn {
    /// AW `valid`.
    pub aw_valid: bool,
    /// Write byte address (4 KiB aperture).
    pub aw_addr: b12,
    /// W `valid`.
    pub w_valid: bool,
    /// Write word.
    pub w_data: b32,
    /// Byte enables (every write is a whole word).
    pub w_strb: b4,
    /// B `ready`.
    pub b_ready: bool,
    /// AR `valid`.
    pub ar_valid: bool,
    /// Read byte address.
    pub ar_addr: b12,
    /// R `ready`.
    pub r_ready: bool,
}

/// AXI4-Lite responses.
#[derive(Clone, Copy, Debug, Default, Digital, PartialEq)]
pub struct AxiLiteOut {
    /// AW `ready`.
    pub aw_ready: bool,
    /// W `ready`.
    pub w_ready: bool,
    /// B `valid`.
    pub b_valid: bool,
    /// B `resp` (always OKAY).
    pub b_resp: b2,
    /// AR `ready`.
    pub ar_ready: bool,
    /// R `valid`.
    pub r_valid: bool,
    /// R `data`.
    pub r_data: b32,
    /// R `resp` (always OKAY).
    pub r_resp: b2,
    /// Level interrupt (`ap_done` with `GIE` and `IER` set).
    pub interrupt: bool,
}

/// The kernel's control registers (byte offsets), those of ubft_new's HLS
/// kernel (`xubft_hw.h`), so its host code drives rhdl_ubft unchanged.
pub mod regs {
    /// `ap_ctrl`: bit 0 `ap_start`, 1 `ap_done`, 2 `ap_idle`, 3 `ap_ready`.
    pub const AP_CTRL: usize = 0x00;
    /// Global interrupt enable.
    pub const GIE: usize = 0x04;
    /// Interrupt enable.
    pub const IER: usize = 0x08;
    /// Interrupt status.
    pub const ISR: usize = 0x0c;
    /// `network_ptr` (64 bits).
    pub const NETWORK_PTR: usize = 0x10;
    /// `message_ptr` (64 bits).
    pub const MESSAGE_PTR: usize = 0x1c;
    /// `node_num`.
    pub const NODE_NUM: usize = 0x28;
    /// `id`.
    pub const ID: usize = 0x30;
    /// `execution_cycles`.
    pub const EXECUTION_CYCLES: usize = 0x38;
    /// `wait`.
    pub const WAIT: usize = 0x40;
    /// `sk0` (64 bits); `sk1`, `sk2`, `sk3` follow at +0x0c each.
    pub const SK0: usize = 0x48;
    /// rhdl_ubft's `session` (64 bits): a host-chosen id, never reused, that
    /// every signed share carries (outside ubft_new's map, which ends at 0x74).
    pub const SESSION: usize = 0x80;
    /// rhdl_ubft's own read-only status words start here (the HLS kernel
    /// has nothing at or above 0x100).
    pub const STATUS: usize = 0x100;
}

/// One host write into a scheme's configuration window.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct CfgWrite {
    /// A write this cycle.
    pub valid: bool,
    /// Offset within the window (s_axi_control offset − 0x800).
    pub addr: b12,
    /// The word.
    pub data: b32,
}

/// What the consensus controller asks of a signature scheme: the agreed
/// four streams, plus a one-time setup (seed and peers' keys). A scheme is
/// any `Synchronous` component with `I = CryptoIn, O = CryptoOut`
/// (`crypto::ed25519::Ed25519Crypto`, DSig's `crypto::dsig`), and the
/// replica is generic over it.
///
/// Streams (the layout both services share), sign layout v2 (ABI 2). The
/// signed context is 48 bytes, all LE: bytes 0..8 `"RUB2"` (low 4 bytes)
/// and the role (byte 4; 1 = certify share), 8..16 the session, 16..24
/// `view | slot << 32`, 24..32 `k | m << 32`, 32..48 reserved (zero today;
/// tail-CB instance context goes here, which DSig profile 2 also signs).
/// * `sign`: one beat. Bytes 0..8 are the tag, bytes 8..56 the context.
///   Ed25519 signs the context zero-extended to 64 bytes.
/// * `sig`: two beats. Beat 0 is the 64-byte share, beat 1 bytes 0..8 the
///   tag; `tlast` on beat 1.
/// * `verify`: three beats. Beat 0 has byte 0 = the signer's replica index
///   (its key slot) and bytes 4..8 the tag; beat 1 is the context at bytes
///   0..48, zero-extended to 64 (the message as signed); beat 2 the share.
///   `tlast` on beat 2.
/// * `verdict`: one word. Bits 0..8 are 0x80 if valid (else `0x80 | code`),
///   8..12 the slot, 32..64 the tag.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct CryptoIn {
    /// Set up (one-cycle pulse).
    pub setup: bool,
    /// Replicas.
    pub n: b5,
    /// This replica.
    pub id: b5,
    /// This replica's private key (`sk0..sk3`).
    pub sk: [b64; 4],
    /// `message_ptr`: every replica's public key, 8 words each.
    pub keys_base: b64,
    /// `message_ptr` read answers.
    pub msg: AxiReadResp,
    /// Sign requests.
    pub sign: Axis512,
    /// `sig` `tready`.
    pub sig_ready: bool,
    /// Verify requests.
    pub verify: Axis512,
    /// `verdict` `tready`.
    pub verdict_ready: bool,
    /// `announce` `tready`.
    pub announce_ready: bool,
    /// A host write into the scheme's configuration window (s_axi_control
    /// 0x800..0xFFF, only while stopped). DSig takes its per-session
    /// namespace here; Ed25519 ignores it.
    pub cfg: CfgWrite,
    /// A peer's announce, fed back to the scheme: header beat (byte 0 =
    /// the peer's key slot), then its two announce beats; `tlast` on the
    /// third. Schemes without announces keep `cert_ready` high.
    pub cert: Axis512,
}

/// A signature scheme's answers to the controller.
#[derive(Clone, Copy, Debug, PartialEq, Digital, Default)]
pub struct CryptoOut {
    /// Setup finished (level, until the next `setup`).
    pub ready: bool,
    /// `message_ptr` read requests.
    pub msg: AxiRead,
    /// `sign` `tready`.
    pub sign_ready: bool,
    /// Signature beats.
    pub sig: Axis512,
    /// `verify` `tready`.
    pub verify_ready: bool,
    /// Verdicts.
    pub verdict: Axis64,
    /// Sticky fault (the service's `FAULT` or a framing error).
    pub fault: bool,
    /// Best-effort announce for the peers (DSig: a new batch's 64-byte
    /// commitment, then its 64-byte Ed25519 signature; `tlast` on beat 1).
    /// Never valid for Ed25519.
    pub announce: Axis512,
    /// `cert` `tready`.
    pub cert_ready: bool,
}

/// A signature scheme's compile-time shape. The replica takes `SB =
/// C::SHARE_BEATS` as a const generic (kernels cannot read associated
/// constants), and its constructor asserts they agree.
pub trait CryptoScheme: rhdl::prelude::Synchronous<I = CryptoIn, O = CryptoOut> + Default + Clone {
    /// 64-byte beats in one certify share (Ed25519 1, DSig 26). Shares sit
    /// at `certify[(slot·N + node)·16·SHARE_BEATS]`; the share stream
    /// (`sig`) carries this many beats and then the tag beat, and a verify
    /// request is header, message, then this many share beats.
    const SHARE_BEATS: usize;
    /// Scheme number reported in `SHAPE` (1 Ed25519, 2 DSig).
    const SCHEME: u8;
}

// Zero values usable inside kernels (`Default::default()` does not lower).

/// No 64-bit beat.
#[kernel]
pub fn idle64() -> Axis64 {
    Axis64 { valid: false, data: b64(0) }
}

/// No 256-bit beat.
#[kernel]
pub fn idle256() -> Axis256 {
    Axis256 { valid: false, data: [b64(0); 4], last: false }
}

/// No 512-bit beat.
#[kernel]
pub fn idle512() -> Axis512 {
    Axis512 { valid: false, data: [b64(0); 8], keep: b64(0), last: false }
}

/// No read request.
#[kernel]
pub fn idle_read() -> AxiRead {
    AxiRead { ar_valid: false, ar_addr: b64(0), ar_len: b8(0), r_ready: false }
}

/// No read answer.
#[kernel]
pub fn idle_read_resp() -> AxiReadResp {
    AxiReadResp { ar_ready: false, r_valid: false, r_data: [b64(0); 8], r_last: false }
}

/// No write request.
#[kernel]
pub fn idle_write() -> AxiWrite {
    AxiWrite { aw_valid: false, aw_addr: b64(0), w_valid: false, w_data: [b64(0); 8], w_strb: b64(0), b_ready: false }
}

/// No AXI4-Lite request.
#[kernel]
pub fn idle_lite_in() -> AxiLiteIn {
    AxiLiteIn {
        aw_valid: false,
        aw_addr: b12(0),
        w_valid: false,
        w_data: b32(0),
        w_strb: b4(0),
        b_ready: false,
        ar_valid: false,
        ar_addr: b12(0),
        r_ready: false,
    }
}

/// No AXI4-Lite answer.
#[kernel]
pub fn idle_lite_out() -> AxiLiteOut {
    AxiLiteOut {
        aw_ready: false,
        w_ready: false,
        b_valid: false,
        b_resp: b2(0),
        ar_ready: false,
        r_valid: false,
        r_data: b32(0),
        r_resp: b2(0),
        interrupt: false,
    }
}