A template for SystemVerilog RTL projects. cocotb tests run through pytest on
Verilator by default, with Questa and VCS profiles; Verible, Verilator and slang
lint and format the RTL; the flow collects code and functional coverage and
opens waveforms with reusable layouts. A Makefile is the front end to a small
Python package, flow/, that drives the tools.
rtl/: the RTL and its filelists.top.sv: a parameterized counter, the example design.top_abv.sv: assertions, cover properties and a covergroup fortop.sv.sources.vf: the compilation filelist (the defaultSV_SOURCES_FILE).verilator.vlt: Verilator's control file: lint waivers, the coverage exclusion of Verilator's own library, and internal signals that tests access.
tests/: the cocotb tests, launched by pytest.test_top.py: tests fortop.cocotb_configs.py: named HDL parameter configurations.
flow/: the build, run and view flow that the Makefile calls, with its own unit tests inflow/tests/and its README.waves/: reusable waveform layouts, one per viewer, named<DUT>.*.docs/: the documentation below:design/holds the design's specifications, andflow/the flow's guides.Makefile,pyproject.toml(uv-managed Python dependencies and tool settings),mise.tomlandmise.lock(the tools that mise installs), andAGENTS.md(instructions for coding agents).
Generated artifacts are ignored by Git and stay under build/.
Install the external tools first; see Tools.
make doctor # check the installed tools and their versions
make test # run the cocotb regression of every DUT
make lint # run all lint and type checks
make help # list every target, override variable and simulatorCreate a repository from this template (on GitHub, Use this template), make it yours, then delete this section:
- Rename the project:
nameanddescriptioninpyproject.toml, then runuv lock; and this README's title, overview and layout. - Replace the example design,
top, with your own (Workflows describes each part):- the RTL in
rtl/, listed inrtl/sources.vf, with third-party RTL inrtl/vendor/; - a test file per top module,
tests/test_<module>.py, with the module's named configurations intests/cocotb_configs.py; - a specification per module in
docs/design/, linked from this README; - the waveform layouts in
waves/, which are optional.
- the RTL in
- Run
make doctor,make lint,make testandmake coverage, then push: CI runs the same checks.
The design:
- top: the example counter's specification. Give each
module a specification in
docs/design/.
The flow:
- Workflows: running tests, adding RTL and tests, named configurations, assertions, coverage and waveforms.
- Tools: installing the simulators, linters and viewers, how they compare, and the versions this template was verified with.
- Development: conventions, linting, CI and updating dependencies.
- flow/README.md: how the flow package works, its tests, and adding a simulator or viewer.