# cambridgehackers/open-src-cvc architecture

> Architecture diagram of the GitHub repository cambridgehackers/open-src-cvc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cambridgehackers/open-src-cvc
- Repository: https://github.com/cambridgehackers/open-src-cvc

## Overview

##### Project type and purpose
- OSS-CVC is an open-source Verilog simulator (compiler + runtime engine) written in C, conforming to IEEE P1364. Its purpose is to parse Verilog source, build an internal representation, and execute simulation while exposing PLI/VPI/DPI plugin hooks and coverage support.

##### File structure
- Top-level directories:
- bin – prebuilt CLI executables (checkcvc, checkcvc32, etc.)
- src – core C source: front-end (parser/elaborator), simulation kernel, IR generators, optimization passes, plugin interface implementations, compression libs (fastlz, lz4, zlib)
- pli_incs – public header files for PLI (cv_acc_user.h, vpi_user.h), DPI (svdpi.h)
- doc – user/developer documentation, quick-starts, API guides
- tests_and_examples – categorized Verilog/PLI/DPI examples and open-core demos
- toggle_coverage – standalone helper tools for post-processing coverage toggle data
- Config/build scripts: multiple makefiles (makefile.cvc[64], makefile.lnx, makefile.lnx64), INSTALL, .gitignore.

##### README for additional insights
- Confirms licensing, installation steps, and that CVC is delivered as source + optional binaries.

##### How to represent this
a. Main components:
1. Command-Line Interface Layer
– bin/checkcvc executables
– Command-line parser & driver
2. Compiler Front-End
– Verilog parser (cvc.c, v_src.c series)
– Syntax tree/AST builder
– Elaborator/dig_main.c
3. Intermediate Representation & Optimization
– IR generators (v_bbgen.c, v_prp.c, v_xprop.c)
– Optimization passes (constant folding, coverage instrumentation)
4. Simulation Kernel
– Event queue, time management (v_sim.c, v_ex*.c)
– Gate-level and behavioral model evaluators (v_fx*.c, v_tf.c)
5. Plugin Interface Layer
– PLI/VPI modules (v_vpi*.c, v_dpi.c)
– pli_incs headers for user plugins
6. Compression & Utility Libraries
– fastlz.c/.h, lz4.c/.h, libz.a – for waveform dumps or coverage data
7. Coverage & Toggle-Coverage Tools
– Built-in coverage instrumentation in the simulator
– External toggle_coverage helpers (chk_tgldat, tvcd_to_tgldat)
8. File I/O & Persistence
– Waveform dump writer, coverage data writer
– Log files, .flist input readers
9. Tests & Example Suites
– Structured directories for PLI, DPI, TF, xprop examples
– Open-core RTL simulation examples under tests_and_examples/open_cores
b. Relationships & interactions
- CLI → invokes Front-End → produces IR → handed to Simulation Kernel
- Simulation Kernel ↔ Plugin Interfaces for external callbacks
- Simulation Kernel ↔ Compression Library when writing VCD/TVCD
- Post-run: Coverage data files consumed by toggle_coverage tools
- Tests/examples feed into CLI as input scripts and Verilog files
c. Architectural patterns & design principles
- Modular C components grouped by functionality (lexer/parser, IR, engine, plugin interfaces)
- Plugin pattern for PLI/VPI/DPI integration
- Static linking of utility libraries for portability
- Separation of concerns: parsing vs. simulation vs. post-processing
d. Key technologies
- Core: ISO C, Makefiles
- Plugin APIs: IEEE P1364 PLI, IEEE 1800 DPI, VPI
- Compression: fastlz, lz4, zlib
- Documentation: PDF/README guides

##### Detail without overcomplicating
- Break “src” into its logical submodules rather than listing files
- Essential flows: parsing → elaboration → simulation → plugin callbacks → output

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Command-Line Interface Layer
    subgraph "Command-Line Interface Layer"
        CC1["checkcvc"]:::frontend
        CC2["checkcvc32"]:::frontend
        CC3["checkcvc64"]:::frontend
        EXE["exe_main.c"]:::frontend
    end
    %% Compiler Front-End
    subgraph "Compiler Front-End"
        CVC["cvc.c"]:::frontend
        VS1["v_src.c"]:::frontend
        VS2["v_src2.c"]:::frontend
        VS3["v_src3.c"]:::frontend
        DIG["dig_main.c"]:::frontend
    end
    %% Intermediate Representation & Optimization
    subgraph "IR & Optimization"
        BB1["v_bbgen.c"]:::frontend
        BB2["v_bbgen2.c"]:::frontend
        BB3["v_bbgen3.c"]:::frontend
        OPT["v_bbopt.c"]:::frontend
        PRP1["v_prp.c"]:::frontend
        PRP2["v_prp2.c"]:::frontend
        XPR["v_xprop.c"]:::frontend
    end
    %% Simulation Kernel
    subgraph "Simulation Kernel"
        SIM["v_sim.c"]:::kernel
        EX1["v_ex.c"]:::kernel
        EX2["v_ex2.c"]:::kernel
        EX3["v_ex3.c"]:::kernel
        EX4["v_ex4.c"]:::kernel
        FX1["v_fx.c"]:::kernel
        FX2["v_fx2.c"]:::kernel
        FX3["v_fx3.c"]:::kernel
        GFX["v_genfx.c"]:::kernel
        TF["v_tf.c"]:::kernel
    end
    %% Plugin Interface Layer
    subgraph "Plugin Interface Layer"
        VPI1["v_vpi.c"]:::plugin
        VPI2["v_vpi2.c"]:::plugin
        VPI3["v_vpi3.c"]:::plugin
        DPI["v_dpi.c"]:::plugin
        PLIINC["pli_incs/"]:::plugin
    end
    %% Compression & Utility Libraries
    subgraph "Compression & Utility Libraries"
        FLZC["fastlz.c"]:::util
        FLZH["fastlz.h"]:::util
        LZ4C["lz4.c"]:::util
        LZ4H["lz4.h"]:::util
        ZLIB["libz.a"]:::util
    end
    %% Coverage Post-Processing Tools
    subgraph "Coverage Post-Processing"
        CT1["chk_tgldat.c"]:::util
        CT2["tgldat_merge.c"]:::util
        CT3["tgldat_report.c"]:::util
        CT4["tvcd_to_tgldat.c"]:::util
        CTB["bin/"]:::util
    end
    %% Documentation
    subgraph "Documentation"
        DOC1["README"]:::docs
        DOC2["oss-cvc-quick-start-061014.pdf"]:::docs
        DOC3["cvc_help.txt"]:::docs
        DOC4["how_to_use_new_toggle_coverage_feature.README"]:::docs
    end
    %% Tests & Examples Suite
    subgraph "Tests & Examples"
        TE1["examples.acc/"]:::tests
        TE2["examples.dpi/"]:::tests
        TE3["examples.tf/"]:::tests
        TE4["examples.vpi/"]:::tests
        TE5["examples.xprop/"]:::tests
        TE6["open_cores/"]:::tests
    end

    %% Connections
    CC1 --> EXE
    CC2 --> EXE
    CC3 --> EXE
    TE1 --> CC1
    TE2 --> CC1
    TE3 --> CC1
    TE4 --> CC1
    TE5 --> CC1
    TE6 --> CC1
    DOC1 --> CC1
    DOC2 --> CC1
    DOC3 --> CC1
    DOC4 --> CC1

    EXE --> CVC
    CVC --> BB1
    BB1 --> SIM
    SIM <--> VPI1
    SIM <--> VPI2
    SIM <--> VPI3
    SIM <--> DPI
    SIM --> FLZC
    SIM --> LZ4C
    SIM --> ZLIB
    SIM --> CT1
    CT1 --> CTB

    %% Click Events
    click CC1 "https://github.com/cambridgehackers/open-src-cvc/tree/master/bin/checkcvc"
    click CC2 "https://github.com/cambridgehackers/open-src-cvc/tree/master/bin/checkcvc32"
    click CC3 "https://github.com/cambridgehackers/open-src-cvc/tree/master/chkcvc.src.dir/checkcvc64"
    click EXE "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/exe_main.c"
    click CVC "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/cvc.c"
    click VS1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_src.c"
    click VS2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_src2.c"
    click VS3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_src3.c"
    click DIG "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/dig_main.c"
    click BB1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_bbgen.c"
    click BB2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_bbgen2.c"
    click BB3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_bbgen3.c"
    click OPT "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_bbopt.c"
    click PRP1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_prp.c"
    click PRP2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_prp2.c"
    click XPR "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_xprop.c"
    click SIM "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_sim.c"
    click EX1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_ex.c"
    click EX2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_ex2.c"
    click EX3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_ex3.c"
    click EX4 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_ex4.c"
    click FX1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_fx.c"
    click FX2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_fx2.c"
    click FX3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_fx3.c"
    click GFX "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_genfx.c"
    click TF "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_tf.c"
    click VPI1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_vpi.c"
    click VPI2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_vpi2.c"
    click VPI3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_vpi3.c"
    click DPI "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/v_dpi.c"
    click PLIINC "https://github.com/cambridgehackers/open-src-cvc/tree/master/pli_incs/"
    click FLZC "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/fastlz.c"
    click FLZH "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/fastlz.h"
    click LZ4C "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/lz4.c"
    click LZ4H "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/lz4.h"
    click ZLIB "https://github.com/cambridgehackers/open-src-cvc/blob/master/src/libz.a"
    click CT1 "https://github.com/cambridgehackers/open-src-cvc/blob/master/toggle_coverage/src/chk_tgldat.c"
    click CT2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/toggle_coverage/src/tgldat_merge.c"
    click CT3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/toggle_coverage/src/tgldat_report.c"
    click CT4 "https://github.com/cambridgehackers/open-src-cvc/blob/master/toggle_coverage/src/tvcd_to_tgldat.c"
    click CTB "https://github.com/cambridgehackers/open-src-cvc/tree/master/toggle_coverage/bin/"
    click DOC1 "https://github.com/cambridgehackers/open-src-cvc/tree/master/doc/README"
    click DOC2 "https://github.com/cambridgehackers/open-src-cvc/blob/master/doc/oss-cvc-quick-start-061014.pdf"
    click DOC3 "https://github.com/cambridgehackers/open-src-cvc/blob/master/doc/cvc_help.txt"
    click DOC4 "https://github.com/cambridgehackers/open-src-cvc/blob/master/doc/how_to_use_new_toggle_coverage_feature.README"
    click TE1 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/examples.acc/"
    click TE2 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/examples.dpi/"
    click TE3 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/examples.tf/"
    click TE4 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/examples.vpi/"
    click TE5 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/examples.xprop/"
    click TE6 "https://github.com/cambridgehackers/open-src-cvc/tree/master/tests_and_examples/open_cores/"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef kernel fill:#D5F5E3,stroke:#186A3B,color:#1B2631
    classDef plugin fill:#FDEBD0,stroke:#B9770E,color:#1B2631
    classDef util fill:#E5E7E9,stroke:#626567,color:#1B2631
    classDef docs fill:#F9EBEA,stroke:#943126,color:#1B2631
    classDef tests fill:#FCF3CF,stroke:#B7950B,color:#1B2631
```
