rtl-p4s-unit-test-policy

Tier 2 Unit Test Policy

Coding Convention Requirements

Testbenches MUST follow project conventions:

• Port connections: i_ prefix for inputs, o_ prefix for outputs, io_ for bidirectional
• Clock: clk (single domain) or {domain}_clk (multiple, e.g., sys_clk) — NOT clk_i
• Reset: rst_n (single domain) or {domain}_rst_n (multiple, e.g., sys_rst_n) — NOT rst_ni
• Use logic only (NOT reg/wire)
• DUT instance: u_ prefix (e.g., u_dut)
• Testbench filename: tb_{module}.sv

Execution Policy

• testbench-dev writes SV testbenches per module (parallel), targeting uarch features
• Reference model comparison: Mode A (DPI-C) or Mode B (file compare) — auto-selected
• func-verifier runs simulations via run_sim.sh and reports results
• Failing tests trigger waveform analysis before reporting
• Gate: all unit tests pass AND reference comparison has zero mismatches

Reference Comparison Modes

Mode	Condition	Method
A: DPI-C	refc/build/lib{module}_ref.so exists	SV TB calls ref functions via DPI-C, cycle-level comparison
B: File	DPI-C unavailable	RTL sim → output file, ref binary → output file, diff comparison

DPI-C setup:

cd refc && mkdir -p build
gcc -std=c11 -shared -fPIC -o build/lib{module}_ref.so src/{module}_ref.c

Result JSON Schema

Each feature entry supports an optional ac_ids field for acceptance criteria traceability:

• ac_ids: array of AC IDs covered by this test (e.g., ["REQ-U-012.AC-1", "REQ-U-012.AC-2"])
• When the requirement has acceptance_criteria (structured object array with ac_id fields) in iron-requirements.json, ac_ids MUST be populated for each covered criterion.
• When acceptance_criteria is absent or an empty array [], ac_ids may be omitted (backward compatible).

{
  "module": "{module}",
  "tier": 2,
  "ref_mode": "A_DPI" | "B_FILE",
  "features": [
    {"name": "fsm_idle_to_active", "status": "PASS", "req_ids": ["REQ-U-003"], "ac_ids": ["REQ-U-003.AC-1"]},
    {"name": "pipeline_latency_3cyc", "status": "PASS", "req_ids": ["REQ-U-007"], "ac_ids": ["REQ-U-007.AC-1", "REQ-U-007.AC-2"]},
    {"name": "valid_ready_handshake", "status": "PASS", "req_ids": ["REQ-U-012"], "ac_ids": ["REQ-U-012.AC-1"]},
    {"name": "transform_accuracy", "status": "FAIL", "mismatch_cycle": 47, "req_ids": ["REQ-U-015"]}
  ],
  "ref_mismatches": 0,
  "pass_count": 5,
  "fail_count": 0,
  "total": 5,
  "gap_fill_round": {
    "executed": true,
    "before": {"line_pct": 52.1, "fsm_pct": 40.0},
    "after": {"line_pct": 67.3, "fsm_pct": 55.0}
  },
  // When gap-fill NOT triggered: {"executed": false, "before": null, "after": null}
  "coverage": {
    "line_pct": 67.3,
    "fsm_pct": 55.0,
    "toggle_pct": 42.1
  },
  "func_coverage": {
    "covergroups_defined": 2,
    "bins_hit": 14,
    "bins_total": 20
  },
  "codec_conformance": "PASS" | "FAIL" | "N/A"
}