Important
I need a better name than dumbname --- I'm open to suggestions!
dumbname is a really powerful library (and API) that lets you "import" hardware modules into Rust (or Rust functions into hardware modules!).
No precompilation step and manual updates with verilator harnesses; no
Makefiles and quirky decorators with cocotb.
testbenches. You're writing a regular Rust crate here.
Add this library to your Cargo.toml like any other library. Use hardware
modules as structs like any other Rust struct. Hook them up to tokio or
serde even.
dumbname works out of the box on macOS and Ubuntu (verified under continuous integration).
Why does hardware testing suck? Consider the ways we have to test (System)Verilog:
- Test natively: Verilog is already a terrible enough language, and writing tests in Verilog is really annoying.
- Use verilator harnesses: You have to first run Verilator to get the right headers, recompile manually every time, deal with raw pointers and C++, etc.
- Use cocotb: You have to use Makefiles, performance isn't the greatest, you get no LSP support, etc.
The problem gets worse with custom HDLs, so they've come up with some creative solutions:
- Calyx: the canonical way of testing Calyx code is to read from JSON files representing byte arrays and write to JSON files representing byte arrays.
- Spade:
verilatorintegration involves absurd macro magic and usingcocotbrequires putting the design-under-test in a code comment. - Veryl: you literally write inline Verilog or Python. Yes, inside Veryl code.
Still, a lot of these are less than optimal.
- 🚀 Minimal overhead over directly using
verilator - 🔌 Works completely drop-in in your existing projects
- 🪙 Declarative API for usability + Dynamic API for programmability
- 🔄 DPI support in Rust: call Rust functions from (System)Verilog
- 🦀 Rust. Did I say Rust?
dumbname is currently in development.
You can currently install the crates via git specifications.
(I'm aware that this is not explained well.)
Look at the tutorials in the Usage section for detailed instructions.
I'll write more documentation once I get further in the development process.
- Testing a Verilog project
- Testing a Spade project
- Using dynamic Verilog models
- Calling Rust from Verilog
I'll write more on this once I get further in the development process.
The TLDR is procedural macros + dlopen.
- verilated-rs is a super cool library that uses a build script to statically link in verilated bindings, but is unmaintained for years as of writing this.
dumbname is licensed under the Mozilla Public License 2.0. This license is similar to the Lesser GNU Public License, except that the copyleft applies only to the source code of this library, not any library that uses it. That means you can statically or dynamically link with unfree code (see https://www.mozilla.org/en-US/MPL/2.0/FAQ/#virality).
I use cargo-deny (see the
deny.toml to ensure no licensing violations occur. I also check
this on CI to prevent merging any new dependencies or dependency updates that
introduce incompatible licenses.