CIRCT — Circuit IR Compilers and Tools

This is a fork of llvm/circt that adds a SystemVerilog simulator (circt-sim) capable of running full UVM testbenches end-to-end. It compiles SystemVerilog through slang into MLIR, lowers it through CIRCT's Moore/LLHD dialects, and interprets the result with 4-state semantics, fork/join process control, VPI, and a built-in UVM runtime.

What works today

Area	Status
SystemVerilog parsing	Full IEEE 1800-2017 via slang (550/550 ImportVerilog tests)
Simulation	907 sv-tests (901 pass + 6 expected-fail)
UVM testbenches	9 protocol AVIPs run to completion (APB, AHB, AXI4, AXI4-Lite, SPI, I2S, I3C, JTAG, UART)
VPI / cocotb	50/50 cocotb tests pass
Coverage	Covergroups, cross coverage, parametric sample
Formal verification	BMC + LEC via circt-bmc / circt-lec; OpenTitan connectivity LEC: 368/368 PASS
Mutation testing	circt-mut cover/matrix/report with formal pre-qualification

Latest formal milestones (as of March 2, 2026)

• OpenTitan connectivity LEC (real Z3) full shard closure: 368/368 PASS across deterministic 8-shard execution (46 cases per shard).
• Production timeout profile: validated at CIRCT_TIMEOUT_SECS=120 with bind-top batching and precheck split/fallback paths.
• Parallel stability hardening: run_opentitan_connectivity_circt_lec.py now supports LEC_TOOL_SNAPSHOT_MODE=on to run from immutable per-run snapshots of circt-verilog, circt-opt, and circt-lec.

Fork highlights

Compared to upstream CIRCT, this fork adds:

• circt-sim — an MLIR-based simulator with an event-driven process scheduler, 4-state value semantics, and a UVM runtime (config_db, factory, phase sequencing, objections, sequencer, coverage, and more).
• Class OOP — full class hierarchy, virtual methods, vtable dispatch, parameterized classes, static properties.
• Virtual interfaces — shadow signal propagation, modport support, interface-to-ref conversion.
• Fork/join — fork/join, join_any, join_none, wait fork, disable fork.
• Constraint randomization — range, multi-range, soft constraints, inline implication; 94% operator coverage.
• File I/O & system tasks — $fopen/$fwrite/$fclose, $display/$sformatf, $finish/$fatal, $readmemh.
• Coverage — covergroups, coverpoints, cross coverage, sample().
• VPI runtime — enough of IEEE 1364 VPI for cocotb integration.
• Mutation testing — circt-mut for RTL mutation campaigns with formal pre-qualification (see docs/FormalRegression.md).
• LSP / IDE — UVM-aware circt-lsp-server with --uvm-path support.

For a full changelog, see docs/CHANGES.md.

Getting started

Prerequisites

You need git, ninja, python3, cmake, and a C++ compiler. See the LLVM requirements for details.

Build

# Clone with submodules
git clone --recursive git@github.com:thomasnormal/circt.git
cd circt

# Build (add -DCIRCT_SLANG_FRONTEND_ENABLED=ON for circt-verilog)
cmake -G Ninja llvm/llvm -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_TARGETS_TO_BUILD=host \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_EXTERNAL_PROJECTS=circt \
    -DLLVM_EXTERNAL_CIRCT_SOURCE_DIR=$PWD \
    -DLLVM_ENABLE_LLD=ON

# Build just circt-sim and circt-verilog
ninja -C build circt-sim circt-verilog

# Run tests
ninja -C build check-circt

To build a specific tool only (faster):

ninja -C build bin/circt-sim      # simulator
ninja -C build bin/circt-verilog  # SV frontend
ninja -C build bin/circt-opt      # MLIR optimizer
ninja -C build bin/firtool        # FIRRTL compiler

Running a simulation

# Compile SystemVerilog to MLIR
circt-verilog input.sv -o design.mlir

# Simulate
circt-sim design.mlir --top top_module

For UVM testbenches, compile with --uvm-path pointing at a UVM library and use --top for both HVL and HDL top modules:

circt-sim design.mlir --top hvl_top --top hdl_top --max-time=500000000

Building LLVM separately

You can build LLVM/MLIR separately and point CIRCT at it, which lets you use different build types (e.g., LLVM in release, CIRCT in debug):

# Build LLVM/MLIR
cd llvm
cmake -G Ninja llvm -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DLLVM_ENABLE_PROJECTS=mlir \
    -DLLVM_TARGETS_TO_BUILD=host
ninja -C build
cd ..

# Build CIRCT against it
cmake -G Ninja . -B build \
    -DCMAKE_BUILD_TYPE=Debug \
    -DLLVM_ENABLE_ASSERTIONS=ON \
    -DMLIR_DIR=$PWD/llvm/build/lib/cmake/mlir \
    -DLLVM_DIR=$PWD/llvm/build/lib/cmake/llvm
ninja -C build check-circt

Submodules

CIRCT pins LLVM as a git submodule. After switching branches:

git submodule update

Mutation testing

This fork includes circt-mut for Certitude/MCY-style RTL mutation campaigns with formal pre-qualification via circt-bmc and circt-lec.

# Build mutation tools
ninja -C build circt-mut circt-bmc circt-lec circt-verilog

# Bootstrap a campaign
circt-mut init --project-dir my-campaign

# Run it
circt-mut run --project-dir my-campaign --mode all

# Report results
circt-mut report --project-dir my-campaign --mode all --out report.tsv

For the full CLI reference, lane TSV schema, global-filter modes, and CI integration guide, see docs/FormalRegression.md.

Tool resource guard

Most CIRCT tools include a built-in resource guard to prevent runaway memory or time usage:

• Disable: --no-resource-guard
• Adjust: --max-rss-mb=... / --max-wall-ms=... (or env vars CIRCT_MAX_RSS_MB, CIRCT_MAX_WALL_MS, etc.)
• Debug: --resource-guard-verbose

Upstream CIRCT

This fork tracks llvm/circt. For upstream documentation, community links, and the project charter:

• Discourse forum
• Discord channel
• Weekly meeting notes
• Charter
• Getting started (upstream)
• Python bindings