# llvm/circt architecture

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

- Interactive diagram: https://gitdiagram.com/llvm/circt
- Repository: https://github.com/llvm/circt

## Overview

The CIRCT project is a highly modular, compiler-style infrastructure built on top of the LLVM/MLIR ecosystem. At its core, it provides a framework for compiling and translating various circuit intermediate representations (IRs) (such as FIRRTL, HW, ESI, etc.) using the modern compiler techniques established in LLVM. In essence, the system can be seen as a “full-stack” compiler and toolset that integrates with MLIR and exposes a series of dialects, conversion passes, and frontend/back-end tools.

##### Main Components
- Core Compiler Infrastructure: This includes the central libraries in the “lib” directory and the “include” files that define CIRCT APIs, dialect definitions, conversion passes, and transformation utilities.
- Dialect Implementations: CIRCT supports many hardware IR dialects. Each dialect is implemented in its own subdirectory (for example, in include/circt/Dialect, lib/Dialect, and unittests/Dialect) and has associated transformation passes and lowering utilities.
- Frontends and Bindings: The “frontends” directory (including the PyCDE and PyRTG subdirectories) and the “lib/Bindings” (Python and C API) show how CIRCT offers integration with higher-level languages and interactive environments.
- Conversion and Transformation Passes: There is extensive conversion infrastructure (the “lib/Conversion” directory) that translates from one IR or dialect to another (for example, FIRRTLToHW, CombToLLVM, etc.). Group these as the “Compiler Passes” component.
- Tools and Executables: The “tools” directory contains command-line programs (e.g., circt-as, circt-opt, circt-bmc, circt-synth, etc.) that provide different functionalities such as assembly/disassembly, RTL simulation, formal verification, and more.
- Testing Infrastructure: With “test”, “integration_test”, “unittests”, and “docs”, CIRCT places strong emphasis on validation. This component not only tests individual components and dialects but also ensures the correctness of end-to-end flows.
- External Dependencies and Build Infrastructure: The system deeply integrates LLVM/MLIR as a submodule (set up and built with CMake and Ninja). Also include support scripts in “utils” that help set up or interface with external EDA tools.

##### Relationships and Data Flow
- Once inside the compiler pipeline, the IR traverses a series of dialect-specific passes (conversion, lowering, optimization) that eventually lead to output formats such as Verilog, SystemC, or other hardware configuration formats.

##### Architectural Patterns and Design Principles
- Layered Design: The system is layered from high-level frontend interfaces (e.g., Python and TCL) on top, with core C++ libraries in the middle, and low-level backends emitting target-specific output.
- Reusability and Extensibility: Emphasize that many of these modules (e.g., the transformation passes) are designed to be plug‐in in nature, which enables the reusability of infrastructure across different parts of the hardware design space.
- Testability: Include a testing layer that interacts with nearly every component, demonstrating the drive for both unit and integration testing.

##### Practical Steps for the Principal Software Engineer
- Drill down into the “Core Compiler” block by including interrelated modules from the “lib” and “include” directories.
- Out major dialect-specific paths – for instance, indicate that the FIRRTL dialect is processed by dedicated conversion passes leading to hardware outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Frontends (PyCDE, PyRTG)"]:::frontend
        FE2["Bindings (Python/Tcl)"]:::frontend
    end

    %% Core Infrastructure
    subgraph "Core Infrastructure"
        C1["CIRCT APIs & Dialect Definitions"]:::core
        C2["Compiler Libraries"]:::core
        C3["Build & Config"]:::core
    end

    %% Dialect & Conversion
    subgraph "Dialect & Conversion"
        D1["Dialect Headers"]:::dial
        D2["Dialect Implementations"]:::dial
        DD["Dialect Documentation"]:::dial
        X2["Conversion Headers"]:::passes
        X1["Conversion Passes"]:::passes
    end

    %% Output Tools
    subgraph "Output Tools"
        TOL["CLI Tools"]:::tools
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        TINT["Integration Tests"]:::testing
        TREG["Regression Tests"]:::testing
        TUNIT["Unit Tests"]:::testing
    end

    %% External Dependencies
    subgraph "External Dependencies"
        E1["LLVM/MLIR Submodule"]:::external
        E2["Build Support Scripts"]:::external
    end

    %% Data Flow Connections
    FE1 -->|"feeds"| C2
    FE2 -->|"feeds"| C2

    C1 -->|"supplies"| C2
    C3 -->|"configures"| C2

    E1 -->|"integrates with"| C2
    E2 -->|"supports"| C3

    C2 -->|"triggers"| D2
    C2 -->|"initiates"| X1
    D1 -->|"defines"| D2
    D2 -->|"contributes"| X1
    X2 -->|"augments"| X1

    X1 -->|"emits to"| TOL

    TOL -->|"validated by"| TINT
    TOL -->|"validated by"| TREG
    C2 -->|"unit tested by"| TUNIT
    D2 -->|"unit tested by"| TUNIT
    X1 -->|"unit tested by"| TUNIT

    %% Styles
    classDef frontend fill:#92D050,stroke:#333,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef dial fill:#DAA520,stroke:#333,stroke-width:2px;
    classDef passes fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef tools fill:#FF6347,stroke:#333,stroke-width:2px;
    classDef testing fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef external fill:#C0C0C0,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE1 "https://github.com/llvm/circt/tree/main/frontends"
    click FE2 "https://github.com/llvm/circt/tree/main/lib/Bindings"
    click C1 "https://github.com/llvm/circt/tree/main/include/circt"
    click C2 "https://github.com/llvm/circt/tree/main/lib"
    click C3 "https://github.com/llvm/circt/tree/main/cmake/modules"
    click D1 "https://github.com/llvm/circt/tree/main/include/circt/Dialect"
    click D2 "https://github.com/llvm/circt/tree/main/lib/Dialect"
    click DD "https://github.com/llvm/circt/tree/main/docs/Dialects"
    click X2 "https://github.com/llvm/circt/tree/main/include/circt/Conversion"
    click X1 "https://github.com/llvm/circt/tree/main/lib/Conversion"
    click TOL "https://github.com/llvm/circt/tree/main/tools"
    click TINT "https://github.com/llvm/circt/tree/main/integration_test"
    click TREG "https://github.com/llvm/circt/tree/main/test"
    click TUNIT "https://github.com/llvm/circt/tree/main/unittests"
    click E1 "https://github.com/llvm/circt/blob/main/.gitmodules"
    click E2 "https://github.com/llvm/circt/tree/main/utils"
```
