RTLDesignSherpa: Skill for Claude Code

Test patterns

Moved out of the root CLAUDE.md, which loaded all of this into every session whether or not a test was in scope. /GLOBAL_REQUIREMENTS.md remains the enforcement authority and wins on conflict.

Writing Tests

Every RTL module requires a test!

# Run specific test
pytest val/{subsystem}/test_{module}.py -v

# Run all tests in subsystem
pytest val/{subsystem}/ -v

# Run with coverage
pytest val/{subsystem}/ --cov=rtl/{subsystem}/

Test Structure:

1. Use CocoTB framework
2. Import appropriate BFMs from bin/TBClasses/
3. Target >95% functional coverage
4. Document test methodology in file header
5. Include waveform dumps for debugging

Test File Location:

• val/common/test_{module}.py for rtl/common/
• val/math/test_{module}.py for rtl/math/
• val/amba/test_{module}.py for rtl/amba/
• projects/components/{name}/dv/tests/ for project-specific tests (RAPIDS, STREAM, bridge, ...)

🚨 CRITICAL: Test Structure Pattern 🚨

The repository uses TWO different test patterns depending on the location:

Pattern A: Direct CocoTB (val/common/, val/amba/ areas)

import cocotb
from cocotb_test.simulator import run

# CocoTB test function - direct @cocotb.test() decorator
@cocotb.test(timeout_time=3, timeout_unit="ms")
async def fifo_test(dut):
    tb = FifoBufferTB(dut, dut.clk, dut.rst_n)
    await tb.start_clock('clk', 10, 'ns')
    # ... test logic

# Pytest wrapper function
@pytest.mark.parametrize("data_width, depth", params)
def test_fifo_buffer(request, data_width, depth):
    # ... setup paths, filelist, parameters
    run(
        python_search=[tests_dir],
        verilog_sources=verilog_sources,
        toplevel=dut_name,
        module=module,  # Python module containing cocotb tests
        # ... compilation args
    )

Pattern B: CocoTB + Pytest Wrappers (projects/components/ areas)

⚠️ HARD REQUIREMENT for projects/components/: MUST use Pattern B ⚠️

import cocotb
from cocotb_test.simulator import run

# 1. CocoTB test functions - prefix with "cocotb_test_*" to prevent pytest collection
@cocotb.test(timeout_time=100, timeout_unit="ms")
async def cocotb_test_basic(dut):  # ← "cocotb_test_*" prefix!
    """CocoTB test function - NOT collected by pytest"""
    tb = SimpleSRAMTB(dut)
    await tb.setup_clocks_and_reset()
    # ... test logic

@cocotb.test(timeout_time=100, timeout_unit="ms")
async def cocotb_test_stress(dut):  # ← "cocotb_test_*" prefix!
    """Another CocoTB test function"""
    tb = SimpleSRAMTB(dut)
    await tb.setup_clocks_and_reset()
    # ... stress test logic

# 2. Pytest wrapper functions - call specific cocotb_test_* functions
@pytest.mark.parametrize("addr_width, data_width", params)
def test_basic(request, addr_width, data_width):
    """Pytest wrapper - calls cocotb_test_basic"""
    module, repo_root, tests_dir, log_dir, rtl_dict = get_paths({
        'rtl_stream_fub': '../../../../rtl/fub',
    })

    verilog_sources, includes = get_sources_from_filelist(
        repo_root=repo_root,
        filelist_path='projects/components/dmas/stream/rtl/filelists/fub/sram_controller.f'
    )

    run(
        python_search=[tests_dir],
        verilog_sources=verilog_sources,
        includes=includes,
        toplevel=dut_name,
        module=module,
        testcase="cocotb_test_basic",  # ← Explicitly specify which cocotb function to run
        parameters=rtl_parameters,
        # ... compilation args
    )

@pytest.mark.parametrize("addr_width, data_width", params)
def test_stress(request, addr_width, data_width):
    """Pytest wrapper - calls cocotb_test_stress"""
    # ... same setup as above
    run(
        # ... same args except:
        testcase="cocotb_test_stress",  # ← Different cocotb function
        # ...
    )