Merge pull request #20 from lcapossio/feature/cocotb-regression

Add cocotb regression and Verilator ELA coverage runner

Author: lcapossio

.github/workflows/ci.yml

@@ -126,16 +126,30 @@ jobs:
       - name: Run Verilator lint and MULTIDRIVEN self-test
         run: python sim/run_verilator_lint.py --self-test
 
-  # -- 6. RTL simulation (iverilog + vvp) ---------------------------
+  # -- 6. RTL simulation (cocotb + Icarus) --------------------------
+  # Sharded so the 16-target ELA suite runs in parallel with the protocol
+  # benches; cuts wall-clock at the cost of one extra job slot.
   sim:
-    name: RTL simulation (iverilog + vvp)
+    name: RTL simulation (cocotb + Icarus) [${{ matrix.shard }}]
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [protocol, ela]
     steps:
       - uses: actions/checkout@v4
       - name: Install iverilog
         run: sudo apt-get install -y iverilog
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - name: Run all RTL testbenches
-        run: python sim/run_sim.py
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install cocotb dependencies
+        run: pip install -e ".[hdl]"
+      - name: Run cocotb RTL regression (protocol shard)
+        if: matrix.shard == 'protocol'
+        run: python sim/run_cocotb.py --runner native --clean --skip-ela
+      - name: Run cocotb RTL regression (ELA shard)
+        if: matrix.shard == 'ela'
+        run: python sim/run_cocotb.py --runner native --clean ela

.gitignore

@@ -15,6 +15,9 @@ dfx_runtime.txt
 # Build artifacts
 dist/
 packages/
+build/cocotb_ela/
+build/cocotb/
+build/verilator_ela_coverage/
 *.bit
 *.bin
 !host/fcapz/gui/assets/default_window_state_v6.bin
@@ -23,6 +26,8 @@ packages/
 # Simulation artifacts
 sim/*.vvp
 sim/*.vcd
+sim/ghdl/
+work-obj*.cf
 
 # OS
 .DS_Store
@@ -32,3 +37,6 @@ Thumbs.db
 tests/_tmp/
 .codex_pytest_tmp*/
 .claude/
+
+# Local-only working notes (per PROJECTS.md no_commit/ convention)
+no_commit/

README.md

@@ -124,17 +124,24 @@ and readback behavior without switching cores.
 ### Developer quick start
 
 ```bash
-pip install -e ".[dev]"
+pip install -e ".[dev,hdl]"
 pytest tests/ -v
-python sim/run_sim.py
+python sim/run_cocotb.py --runner native --clean
 ```
 
-`python sim/run_sim.py` runs the shared RTL lint pass (`iverilog -Wall`)
-first, then the default simulation regression.  Use
-`python sim/run_sim.py --lint-only` when you only want the RTL lint check.
+`python sim/run_cocotb.py --runner native --clean` runs the default cocotb RTL
+simulation regression. Use `python sim/run_sim.py --lint-only` when you only
+want the shared RTL lint check (`iverilog -Wall`).
 Run `python sim/run_verilator_lint.py --self-test` when changing RTL; it runs
 the full Verilog RTL matrix through Verilator driver lint for issues such as
 one register assigned from two always blocks.
+Run `python sim/run_verilator_ela_coverage.py --runner wsl` when changing ELA
+behavior and you want Verilator simulation plus merged line/toggle and bound
+functional coverage for the Verilog ELA benches.
+Run `python sim/run_cocotb_ela.py --runner wsl --hdl verilog` to execute the
+shared cocotb ELA core stimulus. The same Python tests can target a VHDL ELA
+core with `--hdl vhdl --vhdl-source <file>` when a VHDL core implementation is
+available.
 
 Use the installed `fcapz` entry point for day-to-day ELA work. The legacy
 `python -m fcapz.cli` form still works, but the package install path is
@@ -695,7 +702,7 @@ GitHub Actions runs on every push and pull request to `main` or `master`:
 | `test-host` | `pytest tests/ -v --tb=short` with the default `not hw` marker filter, plus an explicit JTAG readback pipeline regression for burst and timestamp stabilization paths |
 | `lint-rtl` | `python sim/run_sim.py --lint-only` — shared `iverilog -Wall` elaboration for the core RTL, vendor wrappers, and simulation stubs |
 | `lint-rtl-verilator` | `python sim/run_verilator_lint.py --self-test` -- full-project Verilog RTL driver lint plus an intentional `MULTIDRIVEN` fixture proving the gate catches one reg driven by multiple always blocks |
-| `sim` | `python sim/run_sim.py` — runs the same `iverilog -Wall` lint pass, then the default RTL regression: ELA behavior, ELA focused regressions, ELA configuration matrix, burst readout, single-chain pipe readout, EIO, core manager, and channel mux testbenches |
+| `sim` (matrix: `protocol`, `ela`) | sharded cocotb RTL regression on Icarus, with `iverilog -Wall` enabled per bench and a `pyproject.toml`-keyed pip cache. The `protocol` shard runs `python sim/run_cocotb.py --runner native --clean --skip-ela` (trig compare, JTAG pipe/burst, EIO, core manager, channel mux, Xilinx7 single-chain wrapper, async-FIFO equivalence, EJTAG-AXI, EJTAG-AXI reset regression, EJTAG-UART). The `ela` shard runs `python sim/run_cocotb.py --runner native --clean ela` and exercises the 16-target cocotb ELA suite. |
 
 Hardware integration tests run manually (require physical Arty A7-100T + hw_server).
 Optional **GUI + hardware** checks in `tests/test_gui_hw_capture.py` are
@@ -727,6 +734,9 @@ Produces `examples/arty_a7/arty_a7_top.bit`.
 python sim/run_sim.py
 python sim/run_sim.py --lint-only
 python sim/run_verilator_lint.py --self-test
+python sim/run_cocotb.py --runner wsl
+python sim/run_verilator_ela_coverage.py --runner wsl
+python sim/run_cocotb_ela.py --runner wsl --hdl verilog
 ```
 
 The default command runs `iverilog -Wall` lint before compiling and running
@@ -739,6 +749,29 @@ a full-project Verilog RTL matrix and stricter procedural-driver checks; its
 self-test must fail a deliberately bad multi-driver fixture before the job is
 considered valid.
 
+The Verilator ELA coverage command builds and runs `fcapz_ela`,
+`fcapz_ela_bug_probe`, and `fcapz_ela_config_matrix` as Verilator simulations.
+It writes merged coverage to `build/verilator_ela_coverage/merged.dat` and
+annotated source under `build/verilator_ela_coverage/annotated/`. The runner
+also binds `tb/fcapz_ela_func_cov.sv` into each `fcapz_ela` instance so
+`--coverage-user` records functional events such as arm/reset, trigger commit,
+pre/post stores, overflow, segment completion, burst starts, and optional
+feature register activity.
+
+The cocotb ELA command runs shared Python stimulus and scoreboarding directly
+against an HDL `fcapz_ela` top. It defaults to Icarus for Verilog and GHDL for
+VHDL, relaunching through WSL when requested. The Verilog target uses the same
+core sources as the SystemVerilog benches; the VHDL target expects a VHDL core
+source passed with `--vhdl-source` unless `rtl/vhdl/core/fcapz_ela.vhd` exists.
+It writes a small language-agnostic functional coverage JSON report under
+`build/cocotb_ela/`.
+
+The general cocotb command runs the non-ELA cocotb replacements for the RTL
+simulation benches (`trig_compare`, JTAG pipe/burst, EIO, core manager,
+channel mux, Xilinx7 single-chain wrapper, async FIFO equivalence, EJTAG-AXI,
+EJTAG-AXI reset regression, and EJTAG-UART), and then runs the ELA cocotb suite
+unless `--skip-ela` is passed.
+
 ### Tests
 
 ```bash

pyproject.toml

@@ -43,6 +43,7 @@ include = ["fcapz*"]
 dev = ["pytest>=7.0", "pytest-qt>=4.2", "ruff>=0.4.0"]
 gui = ["PySide6>=6.6", "pyqtgraph>=0.13"]
 gui-preview = ["fpgacapzero[gui]"]
+hdl = ["cocotb>=1.9,<2"]
 litex = ["litex"]
 
 [tool.pytest.ini_options]

rtl/fcapz_ela.v

@@ -1472,7 +1472,10 @@ module fcapz_ela #(
                             ((rd_addr_jtag - ADDR_TS_DATA_BASE[15:0]) >> 2) % TS_WORDS
                         ) * 32;
                     end else if (WORDS_PER_SAMPLE == 1) begin
-                        jtag_rdata <= {{(32-SAMPLE_W){1'b0}}, rd_data_sync1};
+                        // Use sample_chunk_word so SAMPLE_W==32 does not
+                        // emit the {0{1'b0}} zero-replication concat that
+                        // Some lint and synthesis flows reject.
+                        jtag_rdata <= sample_chunk_word(rd_data_sync1, 0);
                     end else begin
                         jtag_rdata <= sample_chunk_word(
                             rd_data_sync1,

sim/_runner_utils.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Leonardo Capossio - bard0 design - <hello@bard0.com>
+
+"""Shared helpers for the cocotb / Verilator simulation runners under sim/.
+
+Keeps WSL relaunch logic and JUnit XML parsing in one place so fixes do not
+have to be mirrored across run_cocotb.py, run_cocotb_ela.py and
+run_verilator_ela_coverage.py.
+"""
+
+from __future__ import annotations
+
+import platform
+import shlex
+import subprocess
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+def windows_to_wsl_path(path: Path) -> str:
+    resolved = path.resolve()
+    drive = resolved.drive.rstrip(":").lower()
+    if not drive:
+        return resolved.as_posix()
+    rest = resolved.as_posix().split(":/", 1)[1]
+    return f"/mnt/{drive}/{rest}"
+
+
+def translate_wsl_arg(arg: str) -> str:
+    """Translate a Windows-style absolute path argument to its WSL equivalent.
+
+    Non-path args pass through untouched. Recognises both `C:\\foo` and `C:/foo`
+    spellings. Backslashes inside non-drive args are not rewritten because they
+    may be meaningful (regex, escapes); callers that want POSIX paths should
+    pass them through windows_to_wsl_path explicitly.
+    """
+    if len(arg) >= 3 and arg[0].isalpha() and arg[1:3] in (":\\", ":/"):
+        drive = arg[0].lower()
+        rest = arg[3:].replace("\\", "/")
+        return f"/mnt/{drive}/{rest}"
+    return arg
+
+
+def running_in_wsl() -> bool:
+    return "microsoft" in platform.release().lower()
+
+
+def relaunch_in_wsl(root: Path, argv: list[str]) -> int:
+    """Re-exec the current script inside WSL bash, translating known path args."""
+    script_args = [
+        windows_to_wsl_path(root / argv[0]),
+        *(translate_wsl_arg(a) for a in argv[1:]),
+    ]
+    script = "cd {} && python3 {}".format(
+        shlex.quote(windows_to_wsl_path(root)),
+        " ".join(shlex.quote(arg) for arg in script_args),
+    )
+    return subprocess.call(["wsl.exe", "-e", "bash", "-lc", script], cwd=root)
+
+
+def check_results(results_xml: Path) -> None:
+    """Raise SystemExit if the cocotb JUnit XML reports any failure/error."""
+    results = ET.parse(results_xml).getroot()
+    failures = len(list(results.iter("failure")))
+    errors = len(list(results.iter("error")))
+    if failures or errors:
+        raise SystemExit(
+            f"cocotb reported failures={failures} errors={errors}: {results_xml}"
+        )