# diffblue/hw-cbmc architecture

> Architecture diagram of the GitHub repository diffblue/hw-cbmc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/diffblue/hw-cbmc
- Repository: https://github.com/diffblue/hw-cbmc

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry Points
    EBMC_CLI["EBMC CLI\n(main.cpp)"]:::cli
    HWCBMC_CLI["HW-CBMC CLI\n(hw_cbmc_main.cpp)"]:::cli
    IC3_CLI["IC3 CLI\n(m1ain.cc)"]:::cli

    %% Factory
    LanguageFactory["LanguageFactory\n(ebmc_solver_factory.h)"]:::core

    %% Frontend Parsers
    subgraph "Frontend Parsers"
        direction TB
        VerilogParser["Verilog Parser"]:::frontend
        VHDLParser["VHDL Parser"]:::frontend
        SMVParser["SMV Parser"]:::frontend
        AIGParser["AIG Parser"]:::frontend
    end

    %% Intermediate Representation
    TransitionSystem["Transition System IR"]:::core

    %% Transformation Layers
    subgraph "Transformation Layers"
        direction TB
        NetlistTrans["Netlist Transformation"]:::transform
        WordLevelTrans["Word-Level Transformation"]:::transform
    end

    %% Verification Engines
    subgraph "Verification Engines"
        direction TB
        BMC["Bounded Model Checker (BMC)"]:::engine
        CEGAR["CEGAR Engine"]:::engine
        Coverage["Coverage Analysis"]:::engine
        KInduction["K-Induction Engine"]:::engine
        Interpolation["Interpolation Engine"]:::engine
        IC3Engine["IC3 Integration"]:::engine
        HWCBMCEngine["Hardware CBMC Engine"]:::engine
        SATQE["SAT-based QBF Engine"]:::engine
    end

    %% Solver Backends
    subgraph "Solver Backends"
        direction TB
        Minisat["Minisat Solver"]:::solver
        BDDEngine["BDD Engine"]:::solver
    end

    %% Reporting / Output
    subgraph "Reporting / Output"
        direction TB
        Waveform["Waveform Generation"]:::report
        VerilogOut["Verilog Export"]:::report
        SMVWordOut["SMV/Word-Level Export"]:::report
        GeneralReport["General Results Reporting"]:::report
    end

    %% Data Flow
    EBMC_CLI --> LanguageFactory
    LanguageFactory --> VerilogParser
    LanguageFactory --> VHDLParser
    LanguageFactory --> SMVParser
    LanguageFactory --> AIGParser

    VerilogParser --> TransitionSystem
    VHDLParser --> TransitionSystem
    SMVParser --> TransitionSystem
    AIGParser --> TransitionSystem

    TransitionSystem --> NetlistTrans
    TransitionSystem --> WordLevelTrans

    NetlistTrans --> BMC
    NetlistTrans --> CEGAR
    NetlistTrans --> Coverage
    NetlistTrans --> KInduction
    NetlistTrans --> Interpolation

    WordLevelTrans --> BMC
    WordLevelTrans --> CEGAR
    WordLevelTrans --> Coverage
    WordLevelTrans --> KInduction
    WordLevelTrans --> Interpolation

    %% Alternative Engine entry points
    HWCBMC_CLI --> HWCBMCEngine
    IC3_CLI --> IC3Engine

    %% Engines to Solvers
    BMC --> Minisat
    CEGAR --> BDDEngine
    Coverage --> BDDEngine
    KInduction --> Minisat
    Interpolation --> Minisat
    IC3Engine --> Minisat
    HWCBMCEngine --> Minisat
    SATQE --> Minisat

    %% Engines to Reporting
    BMC --> Waveform
    BMC --> VerilogOut
    BMC --> SMVWordOut
    BMC --> GeneralReport

    CEGAR --> GeneralReport
    Coverage --> GeneralReport
    KInduction --> GeneralReport
    Interpolation --> GeneralReport
    IC3Engine --> GeneralReport
    HWCBMCEngine --> GeneralReport
    SATQE --> GeneralReport

    %% Click Events
    click VerilogParser "https://github.com/diffblue/hw-cbmc/tree/main/src/verilog/"
    click VHDLParser "https://github.com/diffblue/hw-cbmc/tree/main/src/vhdl/"
    click SMVParser "https://github.com/diffblue/hw-cbmc/tree/main/src/smvlang/"
    click AIGParser "https://github.com/diffblue/hw-cbmc/blob/main/src/aiger/aiger_language.cpp"
    click AIGParser "https://github.com/diffblue/hw-cbmc/blob/main/src/aiger/aiger_language.h"
    click TransitionSystem "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/transition_system.cpp"
    click TransitionSystem "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/transition_system.h"
    click NetlistTrans "https://github.com/diffblue/hw-cbmc/tree/main/src/trans-netlist/"
    click WordLevelTrans "https://github.com/diffblue/hw-cbmc/tree/main/src/trans-word-level/"
    click BMC "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/bmc.cpp"
    click BMC "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/bmc.h"
    click CEGAR "https://github.com/diffblue/hw-cbmc/tree/main/src/ebmc/cegar/"
    click Coverage "https://github.com/diffblue/hw-cbmc/tree/main/src/ebmc/coverage/"
    click KInduction "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/k_induction.cpp"
    click KInduction "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/k_induction.h"
    click Interpolation "https://github.com/diffblue/hw-cbmc/tree/main/src/ebmc/interpolation/"
    click IC3Engine "https://github.com/diffblue/hw-cbmc/tree/main/src/ic3/"
    click IC3_CLI "https://github.com/diffblue/hw-cbmc/blob/main/src/ic3/m1ain.cc"
    click HWCBMCEngine "https://github.com/diffblue/hw-cbmc/tree/main/src/hw-cbmc/"
    click HWCBMC_CLI "https://github.com/diffblue/hw-cbmc/blob/main/src/hw-cbmc/hw_cbmc_main.cpp"
    click SATQE "https://github.com/diffblue/hw-cbmc/tree/main/src/satqe/"
    click Minisat "https://github.com/diffblue/hw-cbmc/tree/main/src/ic3/minisat/"
    click BDDEngine "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/bdd_engine.cpp"
    click BDDEngine "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/bdd_engine.h"
    click EBMC_CLI "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/main.cpp"
    click Waveform "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/waveform.cpp"
    click Waveform "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/waveform.h"
    click VerilogOut "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/output_verilog.cpp"
    click VerilogOut "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/output_verilog.h"
    click SMVWordOut "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/output_smv_word_level.cpp"
    click SMVWordOut "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/output_smv_word_level.h"
    click GeneralReport "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/report_results.cpp"
    click GeneralReport "https://github.com/diffblue/hw-cbmc/blob/main/src/ebmc/report_results.h"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef transform fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef engine fill:#ffcc80,stroke:#fb8c00,color:#e65100
    classDef solver fill:#d1c4e9,stroke:#8e24aa,color:#4a148c
    classDef cli fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef report fill:#eceff1,stroke:#607d8b,color:#263238
    classDef core fill:#f5f5f5,stroke:#bdbdbd,color:#212121
```
