sha256_rhdl/

lane.rs

//! Complete, one-block-per-cycle SHA-256 compression lane.
//!
//! A lane combines the registered round pipeline with a circular synchronous
//! memory holding the original 256-bit chaining values. At cycle `t` it writes
//! the accepted chaining value at pointer `p`. At cycle `t + ROUNDS - 1` it
//! reads address `p`; the memory's registered output and the round token are
//! both visible at cycle `t + ROUNDS`, where feed-forward is combinational.
//!
//! `ROUNDS` must equal `2^ADDRESS_BITS`. Consequently the current write address
//! and the read address (`write + 1`) are always distinct for supported lanes,
//! avoiding the pinned [`rhdl_fpga::core::ram::synchronous::SyncBRAM`]'s explicitly undefined same-address
//! read/write behavior. The pointer advances through valid tokens and bubbles,
//! because alignment is measured in cycles rather than accepted-token count.
//!
//! All three-lane figures in this module are arithmetic projections. Physical
//! block-RAM mapping, three-lane integration, resources, and timing remain
//! synthesis or implementation gates.

use rhdl::{core::circuit::descriptor::SyncKind, prelude::*};
use rhdl_fpga::core::{
    dff::DFF,
    ram::synchronous::{In as SyncBramIn, SyncBRAM, Write as SyncBramWrite},
};

use crate::{
    PipelineWord, ROUND_COUNT, RoundPipeline, RoundState, WorkingState, feed_forward_kernel,
};

/// Address width of the complete 64-round lane's chaining-value memory.
pub const FULL_LANE_ADDRESS_BITS: usize = 6;

/// Canonical module name of the separately generated complete compression lane.
///
/// [`ExternalFullCompressionLane`] emits a typed unresolved reference with this
/// name. The modular signer build must supply the byte-for-byte RHDL-generated
/// [`FullCompressionLane`] hierarchy under the same name before external HDL
/// parsing or synthesis.
pub const SHA256_COMPRESSION_LANE_MODULE: &str = "sha256_compression_lane";

/// Number of entries in the complete lane's circular chaining-value memory.
pub const FULL_LANE_DELAY_DEPTH: usize = 1 << FULL_LANE_ADDRESS_BITS;

/// Logical storage bits in one complete lane's chaining-value memory.
pub const FULL_LANE_CHAINING_STORAGE_BITS: usize = FULL_LANE_DELAY_DEPTH * 8 * 32;

/// Projected logical chaining-memory bits for three complete lanes.
pub const THREE_LANE_CHAINING_STORAGE_BITS: usize = 3 * FULL_LANE_CHAINING_STORAGE_BITS;

/// Flip-flops a naïve 64-stage chaining-value delay would add per lane.
///
/// [`CompressionLane`] replaces this logical delay with
/// [`rhdl_fpga::core::ram::synchronous::SyncBRAM`]. Whether
/// the target tools map it to physical block RAM is a synthesis evidence gate.
pub const AVOIDED_CHAINING_DELAY_FFS: usize = ROUND_COUNT * 8 * 32;

/// Projected flip-flops avoided by three circular chaining memories.
pub const THREE_LANE_AVOIDED_CHAINING_DELAY_FFS: usize = 3 * AVOIDED_CHAINING_DELAY_FFS;

const _: () = {
    assert!(FULL_LANE_DELAY_DEPTH == ROUND_COUNT);
    assert!(FULL_LANE_CHAINING_STORAGE_BITS == 16_384);
    assert!(THREE_LANE_CHAINING_STORAGE_BITS == 49_152);
    assert!(AVOIDED_CHAINING_DELAY_FFS == 16_384);
    assert!(THREE_LANE_AVOIDED_CHAINING_DELAY_FFS == 49_152);
};

/// Prepared input accepted by a compression lane on every rising edge.
///
/// `block` contains the sixteen already-decoded big-endian SHA-256 words.
/// `tag` is opaque to the lane and is preserved bit-for-bit for its scheduler.
/// When `valid` is false, every datapath field is ignored and represents a
/// bubble; there is no backpressure.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct CompressionInput {
    /// Input chaining value `H[0]..H[7]`.
    pub chaining: [b32; 8],
    /// Sixteen big-endian words in the 512-bit compression block.
    pub block: [b32; 16],
    /// Opaque scheduler-owned metadata.
    pub tag: b32,
    /// Marks this cycle as an accepted compression token.
    pub valid: bool,
}

/// Feed-forward result produced by a compression lane.
///
/// `digest` and `tag` are meaningful only while `valid` is true.
#[derive(Clone, Copy, Debug, Default, Digital, Eq, PartialEq)]
pub struct CompressionOutput {
    /// Eight-word SHA-256 state after round execution and feed-forward.
    pub digest: [b32; 8],
    /// Opaque scheduler tag copied from the corresponding input token.
    pub tag: b32,
    /// Marks `digest` and `tag` as meaningful.
    pub valid: bool,
}

/// Fully occupied SHA-256 compression pipeline with circular base-state delay.
///
/// The implementation accepts one input or bubble per cycle without
/// backpressure. Its logical input-to-output latency is exactly `ROUNDS`
/// cycles: the synchronous memory read is scheduled during the last round and
/// therefore does not add a 65th registered transfer.
///
/// # Storage contract
///
/// - round data and the 32-bit tag use resetless registers;
/// - only round-valid bits and the circular pointer reset;
/// - chaining values live in resetless
///   [`rhdl_fpga::core::ram::synchronous::SyncBRAM`] storage and are ignored
///   whenever the aligned round-valid bit is false;
/// - `ROUNDS` must be a power of two equal to `2^ADDRESS_BITS`, and at least two.
///
/// The complete implementation is [`FullCompressionLane`]. Smaller power-of-two
/// specializations are useful for fast lowering-equivalence tests.
#[derive(Clone, Debug, Synchronous, SynchronousDQ)]
#[rhdl(dq_no_prefix)]
pub struct CompressionLane<const ROUNDS: usize, const ADDRESS_BITS: usize>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    rounds: RoundPipeline<ROUNDS>,
    chaining_delay: SyncBRAM<[b32; 8], ADDRESS_BITS>,
    pointer: DFF<Bits<ADDRESS_BITS>>,
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize> Default
    for CompressionLane<ROUNDS, ADDRESS_BITS>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    fn default() -> Self {
        assert!(ROUNDS >= 2, "a BRAM-backed lane needs at least two stages");
        assert!(
            ADDRESS_BITS < usize::BITS as usize,
            "the address-width shift must fit usize"
        );
        assert_eq!(
            ROUNDS,
            1_usize << ADDRESS_BITS,
            "round count must equal the circular-memory depth"
        );
        assert!(
            ROUNDS <= ROUND_COUNT,
            "a SHA-256 compression lane cannot exceed 64 rounds"
        );
        Self {
            rounds: RoundPipeline::default(),
            chaining_delay: SyncBRAM::default(),
            pointer: DFF::new(Bits::default()),
        }
    }
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize> SynchronousIO
    for CompressionLane<ROUNDS, ADDRESS_BITS>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    type I = CompressionInput;
    type O = CompressionOutput;
    type Kernel = compression_lane_kernel<ROUNDS, ADDRESS_BITS>;
}

/// Connectivity and feed-forward kernel for [`CompressionLane`].
#[kernel]
pub fn compression_lane_kernel<const ROUNDS: usize, const ADDRESS_BITS: usize>(
    clock_reset: ClockReset,
    input: CompressionInput,
    q: Q<ROUNDS, ADDRESS_BITS>,
) -> (CompressionOutput, D<ROUNDS, ADDRESS_BITS>)
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    let _ = clock_reset;
    let next_pointer = q.pointer + 1;
    let d = D::<ROUNDS, ADDRESS_BITS> {
        rounds: PipelineWord {
            state: RoundState {
                working: WorkingState {
                    a: input.chaining[0],
                    b: input.chaining[1],
                    c: input.chaining[2],
                    d: input.chaining[3],
                    e: input.chaining[4],
                    f: input.chaining[5],
                    g: input.chaining[6],
                    h: input.chaining[7],
                },
                schedule: input.block,
            },
            tag: input.tag,
            valid: input.valid,
        },
        chaining_delay: SyncBramIn::<[b32; 8], ADDRESS_BITS> {
            read_addr: next_pointer,
            write: SyncBramWrite::<[b32; 8], ADDRESS_BITS> {
                addr: q.pointer,
                value: input.chaining,
                enable: input.valid,
            },
        },
        pointer: next_pointer,
    };
    let output = CompressionOutput {
        digest: feed_forward_kernel(q.chaining_delay, q.rounds.state.working),
        tag: q.rounds.tag,
        valid: q.rounds.valid,
    };
    (output, d)
}

/// Complete 64-round, 64-entry compression lane.
pub type FullCompressionLane = CompressionLane<ROUND_COUNT, FULL_LANE_ADDRESS_BITS>;

/// Copyable type-level adapter for an inline [`CompressionLane`].
///
/// Pinned RHDL derives place the injected child type itself in the generated
/// `Copy + PartialEq` bounds for a parent's D/Q records, even though those
/// records contain only the child's digital input and output. The concrete
/// [`CompressionLane`] carries elaboration configuration and is intentionally
/// not `Copy`. This zero-sized adapter preserves the exact native lane state,
/// simulation, and checked descriptor while satisfying that conservative
/// derive bound. It does not add a hardware wrapper or alter the emitted lane
/// hierarchy.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct InlineCompressionLane<const ROUNDS: usize, const ADDRESS_BITS: usize>;

impl<const ROUNDS: usize, const ADDRESS_BITS: usize> SynchronousDQ
    for InlineCompressionLane<ROUNDS, ADDRESS_BITS>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    type D = ();
    type Q = ();
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize> SynchronousIO
    for InlineCompressionLane<ROUNDS, ADDRESS_BITS>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    type I = CompressionInput;
    type O = CompressionOutput;
    type Kernel = NoSynchronousKernel<ClockReset, CompressionInput, (), (CompressionOutput, ())>;
}

impl<const ROUNDS: usize, const ADDRESS_BITS: usize> Synchronous
    for InlineCompressionLane<ROUNDS, ADDRESS_BITS>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    type S = <CompressionLane<ROUNDS, ADDRESS_BITS> as Synchronous>::S;

    fn init(&self) -> Self::S {
        CompressionLane::<ROUNDS, ADDRESS_BITS>::default().init()
    }

    fn sim(&self, clock_reset: ClockReset, input: Self::I, state: &mut Self::S) -> Self::O {
        CompressionLane::<ROUNDS, ADDRESS_BITS>::default().sim(clock_reset, input, state)
    }

    fn descriptor(&self, scoped_name: ScopedName) -> Result<Descriptor<SyncKind>, RHDLError> {
        CompressionLane::<ROUNDS, ADDRESS_BITS>::default().descriptor(scoped_name)
    }
}

/// Behavioral full lane with an unresolved external HDL implementation.
///
/// Simulation delegates to the exact [`FullCompressionLane`], preserving its
/// 64-cycle latency, reset flushing, bubbles, tags, and digest arithmetic. HDL
/// lowering deliberately emits only a typed reference to
/// [`SHA256_COMPRESSION_LANE_MODULE`]. A modular build must separately generate
/// that module from [`FullCompressionLane`] and pass the complete source set to
/// a capable external parser. The unresolved skeleton alone is not checked RTL
/// evidence and must never be sent to synthesis by itself.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ExternalFullCompressionLane;

impl SynchronousDQ for ExternalFullCompressionLane {
    type D = ();
    type Q = ();
}

impl SynchronousIO for ExternalFullCompressionLane {
    type I = CompressionInput;
    type O = CompressionOutput;
    type Kernel = NoSynchronousKernel<ClockReset, CompressionInput, (), (CompressionOutput, ())>;
}

impl Synchronous for ExternalFullCompressionLane {
    type S = <FullCompressionLane as Synchronous>::S;

    fn init(&self) -> Self::S {
        FullCompressionLane::default().init()
    }

    fn sim(&self, clock_reset: ClockReset, input: Self::I, state: &mut Self::S) -> Self::O {
        FullCompressionLane::default().sim(clock_reset, input, state)
    }

    fn descriptor(&self, scoped_name: ScopedName) -> Result<Descriptor<SyncKind>, RHDLError> {
        Descriptor::<SyncKind> {
            name: scoped_name,
            input_kind: CompressionInput::static_kind(),
            output_kind: CompressionOutput::static_kind(),
            d_kind: Kind::Empty,
            q_kind: Kind::Empty,
            kernel: None,
            netlist: None,
            hdl: Some(HDLDescriptor {
                name: SHA256_COMPRESSION_LANE_MODULE.into(),
                modules: vlog::ModuleList { modules: vec![] },
            }),
            _phantom: core::marker::PhantomData,
        }
        .with_external_netlist_black_box()
    }
}

/// Emits and Icarus-checks a power-of-two lane specialization.
///
/// This is intended for small specializations because the pinned RHDL release
/// emits the complete round array as one monolithic function; Icarus Verilog 13
/// cannot lex the full 64-stage form.
///
/// # Errors
///
/// Returns an error if the specialization is invalid, RHDL lowering fails, or
/// Icarus rejects the generated module hierarchy.
pub fn compression_lane_checked_verilog<const ROUNDS: usize, const ADDRESS_BITS: usize>()
-> Result<String, RHDLError>
where
    rhdl::bits::W<ROUNDS>: BitWidth,
    rhdl::bits::W<ADDRESS_BITS>: BitWidth,
{
    let lane = CompressionLane::<ROUNDS, ADDRESS_BITS>::default();
    Ok(lane
        .descriptor(SHA256_COMPRESSION_LANE_MODULE.into())?
        .hdl()?
        .modules
        .pretty())
}

/// Renders the full lane while deliberately bypassing its final Icarus check.
///
/// The pinned RHDL core is patched locally so nested composition consumes raw
/// child descriptors rather than re-running Icarus for every level. Icarus
/// Verilog 13 still overflows its scanner on the monolithic 64-stage function,
/// so callers of this entry point must pass the returned hierarchy through an
/// explicit capable parser such as Verilator or Vivado.
///
/// Any successfully returned text would be generation-only evidence. It would
/// not be parse, simulation, equivalence, synthesis, resource, or timing
/// evidence and would still require Verilator and Vivado gates.
///
/// # Errors
///
/// Returns an error if RHDL cannot construct or render the full descriptor.
pub fn try_full_compression_lane_unchecked_verilog() -> Result<String, RHDLError> {
    let lane = FullCompressionLane::default();
    let descriptor = lane.descriptor(SHA256_COMPRESSION_LANE_MODULE.into())?;
    let hdl = descriptor.hdl_unchecked()?;
    Ok(hdl.modules.pretty())
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeMap;

    use rhdl::core::sim::ResetOrData;

    use super::*;
    use crate::{ROUND_CONSTANTS_RHDL, compress_block, round_kernel};

    #[derive(Clone, Debug, Default, Synchronous, SynchronousDQ)]
    struct ExternalLaneParent {
        lane: ExternalFullCompressionLane,
    }

    impl SynchronousIO for ExternalLaneParent {
        type I = CompressionInput;
        type O = CompressionOutput;
        type Kernel = external_lane_parent_kernel;
    }

    #[kernel]
    fn external_lane_parent_kernel(
        clock_reset: ClockReset,
        input: CompressionInput,
        q: ExternalLaneParentQ,
    ) -> (CompressionOutput, ExternalLaneParentD) {
        let _ = clock_reset;
        (q.lane, ExternalLaneParentD { lane: input })
    }

    fn word(value: u32) -> b32 {
        b32(u128::from(value))
    }

    fn word_u32(value: b32) -> u32 {
        let bytes = value.raw().to_le_bytes();
        u32::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])
    }

    fn prepared_input(marker: u32, tag: u32) -> CompressionInput {
        let chaining = core::array::from_fn(|index| {
            let index = u32::try_from(index).expect("eight chaining words fit u32");
            word(
                0x1020_3040_u32
                    .wrapping_add(index.wrapping_mul(0x1111_1111))
                    .rotate_left(index)
                    ^ marker.rotate_right(index),
            )
        });
        let block = core::array::from_fn(|index| {
            let index = u32::try_from(index).expect("sixteen block words fit u32");
            word(
                marker
                    .wrapping_mul(index.wrapping_add(1))
                    .rotate_left(index * 3)
                    ^ index.wrapping_mul(0x9e37_79b9),
            )
        });
        CompressionInput {
            chaining,
            block,
            tag: word(tag),
            valid: true,
        }
    }

    fn partial_output(input: &CompressionInput, rounds: usize) -> CompressionOutput {
        let mut state = RoundState {
            working: WorkingState {
                a: input.chaining[0],
                b: input.chaining[1],
                c: input.chaining[2],
                d: input.chaining[3],
                e: input.chaining[4],
                f: input.chaining[5],
                g: input.chaining[6],
                h: input.chaining[7],
            },
            schedule: input.block,
        };
        for round_constant in ROUND_CONSTANTS_RHDL.into_iter().take(rounds) {
            state = round_kernel(state, round_constant);
        }
        CompressionOutput {
            digest: feed_forward_kernel(input.chaining, state.working),
            tag: input.tag,
            valid: true,
        }
    }

    fn expected_outputs(
        events: &[ResetOrData<CompressionInput>],
        rounds: usize,
    ) -> Vec<(usize, CompressionOutput)> {
        events
            .iter()
            .enumerate()
            .filter_map(|(accepted_cycle, event)| {
                let ResetOrData::Data(input) = event else {
                    return None;
                };
                if !input.valid {
                    return None;
                }
                let output_cycle = accepted_cycle + rounds;
                if output_cycle >= events.len()
                    || events[accepted_cycle + 1..output_cycle]
                        .iter()
                        .any(|event| matches!(event, ResetOrData::Reset))
                {
                    return None;
                }
                Some((output_cycle, partial_output(input, rounds)))
            })
            .collect()
    }

    fn observed_outputs<L>(
        lane: &L,
        events: &[ResetOrData<CompressionInput>],
    ) -> Vec<(usize, CompressionOutput)>
    where
        L: Synchronous<I = CompressionInput, O = CompressionOutput>,
    {
        lane.run(events.iter().copied().clock_pos_edge(10))
            .synchronous_sample()
            .enumerate()
            .filter_map(|(cycle, sample)| sample.output.valid.then_some((cycle, sample.output)))
            .collect()
    }

    fn small_lane_events() -> Vec<ResetOrData<CompressionInput>> {
        let mut events = vec![ResetOrData::Reset];
        // Initialize every memory address and every resetless round stage before
        // the emitted-Verilog test begins comparing complete output buses.
        events.extend((0..4).map(|index| {
            ResetOrData::Data(prepared_input(0x1000_0000 + index, 0xa000_0000 + index))
        }));
        events.extend([
            ResetOrData::Data(prepared_input(0x2000_0001, 0xb000_0001)),
            ResetOrData::Data(prepared_input(0x2000_0002, 0xb000_0002)),
            ResetOrData::Data(CompressionInput::default()),
            ResetOrData::Data(prepared_input(0x2000_0003, 0xb000_0003)),
            // This reset kills tags B0000002/B0000003 while they are in flight.
            ResetOrData::Reset,
        ]);
        for index in 0..13_u32 {
            let input = if index % 5 == 3 {
                CompressionInput::default()
            } else {
                prepared_input(0x3000_0000 + index, 0xc000_0000 + index)
            };
            events.push(ResetOrData::Data(input));
        }
        events.extend(std::iter::repeat_n(
            ResetOrData::Data(CompressionInput::default()),
            4,
        ));
        events
    }

    #[test]
    fn small_lane_handles_consecutive_tokens_bubbles_reset_and_wraparound() -> Result<(), RHDLError>
    {
        let lane = CompressionLane::<4, 2>::default();
        let events = small_lane_events();
        let observed = observed_outputs(&lane, &events);
        let expected = expected_outputs(&events, 4);
        assert_eq!(observed, expected);
        assert!(observed.windows(2).any(|pair| pair[1].0 == pair[0].0 + 1));
        assert!(
            !observed
                .iter()
                .any(|(_, output)| output.tag == word(0xb000_0002))
        );
        assert!(events.len() > 2 * 4);

        let test_bench = lane
            .run(events.into_iter().clock_pos_edge(10))
            .collect::<SynchronousTestBench<_, _>>();
        test_bench
            .rtl(&lane, &TestBenchOptions::default().skip(18))?
            .run_iverilog()?;
        Ok(())
    }

    #[test]
    fn full_lane_matches_compression_for_more_than_two_pointer_wraps() {
        let mut events = vec![ResetOrData::Reset];
        for cycle in 1..=20_u32 {
            events.push(ResetOrData::Data(prepared_input(
                0x4000_0000 + cycle,
                0xd000_0000 + cycle,
            )));
        }
        events.push(ResetOrData::Reset);
        for cycle in 0..145_u32 {
            let input = if cycle % 11 == 7 {
                CompressionInput::default()
            } else {
                prepared_input(0x5000_0000 + cycle, 0xe000_0000 + cycle)
            };
            events.push(ResetOrData::Data(input));
        }
        events.extend(std::iter::repeat_n(
            ResetOrData::Data(CompressionInput::default()),
            ROUND_COUNT,
        ));

        let lane = FullCompressionLane::default();
        let observed = observed_outputs(&lane, &events);
        let expected = expected_outputs(&events, ROUND_COUNT);
        assert_eq!(observed, expected);
        assert!(observed.len() > FULL_LANE_DELAY_DEPTH);

        let input_by_tag = events
            .iter()
            .filter_map(|event| match event {
                ResetOrData::Data(input) if input.valid => Some((word_u32(input.tag), *input)),
                _ => None,
            })
            .collect::<BTreeMap<_, _>>();
        for (_, output) in observed {
            let input = input_by_tag
                .get(&word_u32(output.tag))
                .expect("every output tag came from one prepared input");
            let chaining = input.chaining.map(word_u32);
            let block = input.block.map(word_u32);
            assert_eq!(output.digest.map(word_u32), compress_block(chaining, block));
        }
    }

    #[test]
    fn external_full_lane_behavior_delegates_to_the_native_full_lane() {
        let mut events = vec![ResetOrData::Reset];
        for cycle in 0..70_u32 {
            let input = if cycle.is_multiple_of(9) {
                CompressionInput::default()
            } else {
                prepared_input(0x6000_0000 + cycle, 0xf000_0000 + cycle)
            };
            events.push(ResetOrData::Data(input));
        }
        events.push(ResetOrData::Reset);
        events.push(ResetOrData::Data(prepared_input(0x7000_0001, 0x0bad_f00d)));
        events.extend(std::iter::repeat_n(
            ResetOrData::Data(CompressionInput::default()),
            ROUND_COUNT,
        ));

        let native = observed_outputs(&FullCompressionLane::default(), &events);
        let external = observed_outputs(&ExternalFullCompressionLane, &events);
        assert_eq!(external, native);
        assert_eq!(external.len(), 7);
        assert_eq!(
            external.last().expect("post-reset result").1.tag,
            word(0x0bad_f00d)
        );
    }

    #[test]
    fn external_full_lane_descriptor_is_typed_and_unresolved() -> Result<(), RHDLError> {
        let lane = ExternalFullCompressionLane;
        let descriptor = lane.descriptor("ignored_parent_scope".into())?;
        assert_eq!(descriptor.name.to_string(), "ignored_parent_scope");
        assert_eq!(descriptor.input_kind, CompressionInput::static_kind());
        assert_eq!(descriptor.output_kind, CompressionOutput::static_kind());
        assert_eq!(descriptor.input_kind.bits(), 801);
        assert_eq!(descriptor.output_kind.bits(), 289);
        assert!(descriptor.hdl().is_err());
        assert!(descriptor.hdl_unchecked()?.modules.modules.is_empty());

        let wrapper = descriptor
            .netlist()?
            .as_vlog("sha256_external_lane_wrapper")?
            .modules
            .pretty();
        assert!(wrapper.contains("sha256_compression_lane bb_0("));
        assert!(!wrapper.contains("module sha256_compression_lane("));
        Ok(())
    }

    #[test]
    fn external_reference_resolves_against_separate_checked_lane_source() -> Result<(), RHDLError> {
        let descriptor =
            ExternalLaneParent::default().descriptor("sha256_external_lane_wrapper".into())?;
        assert!(descriptor.hdl().is_err());
        let wrapper = descriptor.hdl_unchecked()?.modules.pretty();
        assert!(wrapper.contains("module sha256_external_lane_wrapper("));
        assert!(
            wrapper.contains("sha256_compression_lane c0("),
            "unexpected modular wrapper:\n{wrapper}"
        );
        assert!(!wrapper.contains("module sha256_compression_lane("));
        let lane = compression_lane_checked_verilog::<4, 2>()?;
        assert_eq!(
            wrapper.matches("module sha256_compression_lane(").count()
                + lane.matches("module sha256_compression_lane(").count(),
            1
        );

        let wrapper_path = std::env::temp_dir().join(format!(
            "hashsigs_sha256_external_lane_wrapper_{}.v",
            std::process::id()
        ));
        let lane_path = std::env::temp_dir().join(format!(
            "hashsigs_sha256_external_lane_source_{}.v",
            std::process::id()
        ));
        std::fs::write(&wrapper_path, wrapper).expect("write temporary modular wrapper");
        std::fs::write(&lane_path, lane).expect("write temporary generated lane source");
        let result = std::process::Command::new("iverilog")
            .args(["-g2012", "-s", "sha256_external_lane_wrapper", "-t", "null"])
            .arg(&wrapper_path)
            .arg(&lane_path)
            .output()
            .expect("Icarus Verilog must be installed for RHDL RTL gates");
        std::fs::remove_file(&wrapper_path).expect("remove temporary modular wrapper");
        std::fs::remove_file(&lane_path).expect("remove temporary generated lane source");
        assert!(
            result.status.success(),
            "separately generated lane did not resolve the external reference:\n{}\n{}",
            String::from_utf8_lossy(&result.stdout),
            String::from_utf8_lossy(&result.stderr)
        );
        Ok(())
    }

    #[test]
    fn checked_small_lane_generator_exposes_resetless_memory() -> Result<(), RHDLError> {
        let hdl = compression_lane_checked_verilog::<4, 2>()?;
        assert!(hdl.contains("module sha256_compression_lane"));
        assert!(hdl.contains("reg [255:0] mem[3:0]"));
        assert_eq!(hdl.matches("if (reset)").count(), 5);
        Ok(())
    }

    #[test]
    #[ignore = "slow explicit external Verilator parser gate"]
    fn full_lane_unchecked_render_passes_verilator_lint() -> Result<(), RHDLError> {
        let hdl = try_full_compression_lane_unchecked_verilog()?;
        assert!(hdl.contains("module sha256_compression_lane"));
        assert!(hdl.contains("reg [255:0] mem[63:0]"));
        let path = std::env::temp_dir().join(format!(
            "hashsigs_sha256_full_lane_{}.v",
            std::process::id()
        ));
        std::fs::write(&path, hdl).expect("write temporary full-lane Verilog");
        let result = std::process::Command::new("verilator")
            .args([
                "--lint-only",
                "--Wno-fatal",
                "--top-module",
                "sha256_compression_lane",
            ])
            .arg(&path)
            .output()
            .expect("Verilator must be installed for this explicitly ignored gate");
        std::fs::remove_file(&path).expect("remove temporary full-lane Verilog");
        assert!(
            result.status.success(),
            "Verilator lint failed:\n{}\n{}",
            String::from_utf8_lossy(&result.stdout),
            String::from_utf8_lossy(&result.stderr)
        );
        Ok(())
    }
}