retroSoC/tests

Repository Tests

This directory contains tests for deterministic SDK behavior and build/quality tooling.

• c/test_runtime.c is the host C test program used by make sw-host-test.
• test_npu_framework_reference.py checks model-specific Softmax scaling, all 65536 VWW two-class input combinations, seeded KWS vectors, unchanged hardware artifacts and complete sample-model outputs against the locked TFLite integer kernels. The C++ adapter under cpp/ is host verification code, not an embedded runtime or an alternative production datapath.
• test_npu_qualification.py proves that common-mode Python errors, missing oracle tools, stale source revisions and incomplete tensor records fail closed. Full corpus qualification is the explicit npu-p0-qualify target; ordinary Pytest results alone do not establish full-corpus acceptance.
• test_npu_compiler.py covers all ABI-1 placements, branching ADD lifetime, pooling/Clamp, malformed input, reproducible deployment packages, strict host compilation and generated C Softmax vectors. npu-p5-rtl separately runs the prescribed KWS/VWW inputs on Icarus and Verilator with per-layer write traces; npu-p5-lp-sim and npu-p5-hp-sim establish the two bare-metal submission paths and SYSCTRL verdicts.
• test_npu_p6.py checks deterministic corpus framing and CRCs, exact PRODUCT UART record parsing, cycle-accounting consistency, and fail-closed 1000-case/2x report rules. The npu-p6-* targets, rather than Pytest alone, produce formal, PRODUCT Verilator, synthesized-block, physical and regression evidence.
• test_script_tools.py covers setup, dependency, filelist, warning, metric, archive, and regression-helper behavior.
• test_agent_skills.py checks feature and engineering-workflow skill metadata, local references, eval corpora, default invocation contracts, and documented entrypoints. Run it with python3 -m pytest -q tests/test_agent_skills.py. These are static checks; the eval corpus is reusable scenario data, not proof that an agent executed publication, dependency, or hardware workflows.
• test_rtl_readiness.py covers the machine-readable RTL maturity and synthesis-intent checks.
• test_rtl_style.py covers ownership, named connections, and staged naming rules for new owned RTL.
• test_crypto.py runs directed AES, SHA-2, RSA/Montgomery, streaming, and APB4 V1 reference simulations plus the V2 public lifecycle fixture; test_crypto_register_parity.py checks the handwritten RTL/C register ABI and test_dma.py covers DMA bursts, TCD fetch, CRC, tail-byte writes, and crypto endpoints.
• test_crypto_p0.py checks the independent mathematical constant oracle, corruption rejection and hierarchy-multiplicity/register accounting. make CONFIG=configs/ci/ihp130.mk SYNTH=YOSYS crypto-p0-rtl runs the V1 baseline without invoking Pytest: real Crypto/DMA channel 4/5 traffic, AES CBC/CTR tails, SHA-224/256 padding boundaries and RSA-2048 including equal-schedule private-result verification failure. The deterministic RSA key material is public test data. These are baseline measurements, not V2 initialization/scrub or physical qualification.
• crypto-p1-rtl exercises V2 public initialization and rejection paths, AES key sizes/directions/multiblock/tails, SHA padding, full RSA-2048, held-output abort, concurrent engines, reset boundaries, injected readback and scrub faults, and physical FIFO/bank erasure inspection. Separate crypto_storage_tb.sv and crypto_dma_v2_tb.sv fixtures check all banks, masks, retirements, full-width Montgomery carries and actual DMA 4/5. c/crypto_firmware.c is the focused full-SoC LP HAL/DMA acceptance image; its explicit build invocation is in the Crypto specification. It never preloads Crypto SRAM through hierarchy or replaces hardware algorithms. Review-fix cases cover consecutive-command DONE, CRC-neutral padding faults, initialization timeout/lock boundaries, fatal-fault output drain and real DMA AXI read/write errors. crypto_stream_formal.sv supplements the APB, lifecycle, RSA-release and scrub proofs with arbitrary output backpressure. test_crypto_p1_evidence.py checks that stale source/logs or a failed command cannot qualify an earlier firmware PASS; these Pytest cases are not run when the maintainer has disabled Pytest. crypto_response_fault_tb.sv independently checks delayed, duplicate, stale-epoch and missing SRAM responses while the default product store keeps its fixed one-cycle behavior. crypto_response_fault_tb.sv independently checks delayed, duplicate, stale-epoch and missing SRAM responses while the default product store keeps its fixed one-cycle behavior.
• test_apu.py checks the fail-closed APU APB4/IRQ shell plus the P2 private DMA, ring scheduler, stream router, Gateway A, and verification-only backend; test_apu_register_parity.py keeps its handwritten RTL/C ABI and matrix coverage synchronized. test_apu_primitives.py compares the P4 assembler, BAM, loader, sequencer, local SRAM, FIFOs, and production primitive engines with Icarus and Verilator while keeping its injectors out of product filelists.
• test_apu_codecs.py and test_apu_codec_transport.py check the P5 target, deterministic coefficient/APUMC artifacts, integer WAV/FLAC and PCM models, direct/ring product paths, and identical Icarus/Verilator execution of the production class-6 transport. The explicit apu-p5-corpus target qualifies every pinned official FLAC file against locked libFLAC and records matching released-APUMC production results from identical verification-only Icarus and Verilator fixtures.
• test_apu_p9_coefficients.py checks the frozen APUC hashes and complete logical-to-bank inverse map with an independent frozen oracle. test_apu_p9_storage.py runs the synchronous coefficient clients and macro-memo clear/insert/lookup boundary fixture; the P8 quiesced-loader test covers the successful integrated APUC DMA and readback path. The full corruption/retry/reset/abort lifecycle remains a separate required P9 evidence matrix and is not inferred from that smoke.
• test_apu_p8_quiesce_load.py drives the full apb4_apu shell and checks that MICROCODE_LOAD and MODEL_LOAD DMA fetches are admitted and complete while the LP quiesce is held (the APU-P8 loader-admission regression).
• test_user_ip_register_parity.py keeps the integrated slot 1 timer and slot 2 GPIO register offsets synchronized with their application-owned C definitions and checks their extension-manifest slot assignments.
• test_lp_irq.py checks the 64-bit LP vector, 62-input metadata, Xh3irq wrapper/backend contract, CSR-disabled stubs, and generated routing.
• test_hp_boot_bundle.py checks the HP flash ABI, CRCs, payload placement, and handwritten mailbox RTL/C offset parity. test_hp_platform.py, test_hp_mailbox.py, test_plic.py, and the AXI tests cover the remaining HP integration contracts. test_xpi_fast_flash.py covers the explicitly selected Verilator slot-0 read accelerator, including backpressure and negative completion paths.

Add a host C test when changing deterministic runtime or media logic; add a Python test when changing scripts or build policy. Run:

make sw-host-test
python3 -m pytest -q

These tests complement, but do not replace, firmware builds, RTL simulation, synthesis, timing, or hardware validation.

Historical Tiny publication fixtures also need the main repository history and dependency commit objects named by their archived locks. After ordinary dependency setup, run python3 tests/publication_history.py prepare before Pytest on a fresh checkout. This only fetches missing immutable Git objects; it does not switch current managed checkouts or alter either lock. Historical fixture export remains offline and fails if required inputs are unavailable.