# vj
vj is an event-driven, 4-state SystemVerilog simulator written in Rust. It
targets IEEE 1800-2023, parses and elaborates with
[slang](https://github.com/MikePopoloski/slang) (through the `sv-lang`
bindings) and compiles designs to native code with LLVM, either just in time
(`vj run`) or ahead of time (`vj build-aot`).
**Status: 0.1.0 is a preview release.** It is not yet fully IEEE 1800-2023
compliant; the numbers below say exactly where it stands.
## Conformance (measured, October 2026)
vj tracks every clause of IEEE 1800-2023 (1300 rows) in a compliance matrix:
| pass (whole clause holds, with tests) | 1047 |
| not applicable (headings, informative text) | 196 |
| optional | 37 |
| blocked on the slang frontend | 14 |
| **open (a known gap, refused loudly by name)** | **6** |
Open clauses: 6.9.1 (queues, streams and array methods on values wider than
65535 bits), 15.5 (an `iff` on a signal term in an event list mixed with class
events), 16.9.3 (sampled value functions inside class methods and continuous
assigns), 18.5 (a fixed dimension below the first in a nested random array),
23.3.3.2 (a `ref` port actual with a variable index) and 37.15 (some VPI
reference objects). Every unsupported construct stops with an error naming it; vj does
not knowingly produce a silent wrong answer.
External suites:
- [sv-tests](https://github.com/chipsalliance/sv-tests), non-UVM: 914 pass, 8 fail
(all 8 are test or oracle defects).
- sv-tests UVM tests: 101 of 104 pass (the 3 failures are test defects).
- [ivtest](https://github.com/steveicarus/ivtest): 3218 pass, 330 fail, 66 skipped;
the failures are Icarus-specific behaviour, not IEEE 1800 requirements.
## Install
vj needs **LLVM 22** (development libraries) and a C++ compiler for slang.
```sh
LLVM_SYS_221_PREFIX=/path/to/llvm-22 cargo install vj
```
This installs the `vj` binary.
## Use
```sh
vj run top.sv # compile and simulate
vj run -I inc -D WIDTH=8 a.sv b.sv --top tb
vj run tb.sv --vpi ./libcocotb.so # VPI / cocotb
vj run tb.sv dpi.c # DPI-C
vj --help
```
`vj build-aot` produces a shared library or executable from a design. It links
a runner archive, `libvj_aot.a`, that `cargo install` does not build: build
it from the `vj-aot` crate (`cargo build --release -p vj-aot`) and pass
`--runtime-lib` or set `VJ_AOT_RT`.
## Crates
`vj` is the command-line simulator. The other `vj-*` crates are its parts
(`vj-sim` netlist and scheduler, `vj-codegen` LLVM code generation,
`vj-runtime`, `vj-exec`, `vj-vpi`, `vj-sdf`, `vj-abi`, `vj-aot`, `vj-harness`),
imported in Rust as `vj_sim`, `vj_codegen` and so on.
## License
Licensed under either of [Apache License 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) at your option.