How diffblue/hw-cbmc works
Project type and purpose
• EBMC is an open-source command-line formal verification tool for hardware designs.
• It reads multiple input languages (Verilog, SystemVerilog, NuSMV, ISCAS89 netlists) and applies several model-checking techniques (bounded BMC, unbounded via IC3, k-induction, CEGAR, interpolation, coverage, etc.).
File structure to surface the core architecture
• Top-level “src/” subdivided by functionality:
• Frontends: smvlang, verilog, vhdl, aiger
• Transformation layers: trans-netlist, trans-word-level
• Core engines: ebmc (BMC, CEGAR, coverage, interpolation, k-induction, IC3 interface), ic3, hw-cbmc, satqe
• Temporal logic utilities: temporal-logic
• Common utilities: util
• Entry points: src/ebmc/main.cpp, src/hw-cbmc/hw_cbmc_main.cpp, src/ic3/m1ain.cc
• Build scripts and options parsing: Makefiles in each subdirectory, parse_options modules
README for workflow insights
• User invokes ebmc CLI → selects top module, bound, input file
• Internally EBMC uses a language factory to dispatch to the appropriate frontend parser
• Frontend produces an intermediate representation (IR) or transition system
• IR is fed into one or more back-end engines (BMC, IC3, k-induction, CEGAR, interpolation, coverage)
• Engines call SAT solvers (Minisat via IC3, possibly other backends) or BDD engine
• Results are formatted and printed; optional waveform or counterexample outputs
Main components
a. Frontend parsers
• Verilog parser (src/verilog/*)
• VHDL parser (src/vhdl/*)
• SMV parser (src/smvlang/*)
• AIG parser (src/aiger/*)
b. Intermediate Representation & Transformation
• IR / transition system (src/ebmc/transition_system.cpp)
• Netlist transformation (src/trans-netlist/*)
• Word-level transformation (src/trans-word-level/*)
c. Core Verification Engines
• Bounded Model Checker (src/ebmc/bmc.cpp)
• CEGAR engine (src/ebmc/cegar/*)
• Coverage analysis (src/ebmc/coverage/*)
• K-induction (src/ebmc/k_induction.cpp)
• Interpolation engine (src/ebmc/interpolation/*)
• IC3 integration (src/ic3/*)
• Hardware CBMC (src/hw-cbmc/*)
• SAT-based QBF engine (src/satqe/*)
d. Solver backends
• SAT solvers (Minisat embedded under src/ic3/minisat)
• BDD engine (src/ebmc/bdd_engine.cpp)
e. Output / Reporting
• Counterexample extraction & waveform (src/ebmc/waveform.cpp)
• Verilog / SMV / word-level output (src/ebmc/output_*.cpp)
Relationships and data flows
1. User CLI → parses command-line (ebmc_parse_options)
2. CLI → Language Factory → appropriate frontend parser
3. Frontend → produces IR / TransitionSystem
4. IR → transformation layers (netlist or word- level) as needed
5. Transformed IR → selected verification engine(s)
6. Engine → calls solver backends (SAT, BDD, IC3)
7. Solver → returns results → engine aggregates proof/counterexample
8. Engine → Reporting modules generate human-readable output
Architectural patterns & principles
• Plugin/factory pattern for language frontends and solver backends
• Layered architecture:
• Presentation (CLI)
• Parsing (frontends)
• Transformation (IR → netlist / word-level)
• Analysis (model checking engines)
• Infrastructure (solvers, BDDs)
• Reporting (output formatting)
• Single responsibility: each directory implements one responsibility
• Dependency injection / factory for solvers and engines
Detailed elements to capture
• CLI entry points and parse_options
• LanguageFactory in ebmc_solver_factory.h
• TransitionSystem IR
• Each engine type (BMC, CEGAR, interpolation, IC3, k-induction)
• SolverFactory and external solver invocation
• Output modules for counterexamples and proofs