# uiuc-chenlab/scalehls architecture

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

- Interactive diagram: https://gitdiagram.com/uiuc-chenlab/scalehls
- Repository: https://github.com/uiuc-chenlab/scalehls

## Overview

##### Project Type and Purpose
- This is an MLIR-based compiler/framework (not a web app).
- ScaleHLS takes HLS C/C++ or PyTorch models as input, represents them in MLIR at multiple abstraction levels, applies analyses and transformations (including design-space exploration), and emits optimized HLS C++ suitable for downstream RTL generation (e.g., Vivado HLS).
- It also exposes Python and C APIs and ships command-line tools for integration into user workflows.

##### File Structure Analysis
- Top-Level
- CMakeLists.txt, build-scalehls.sh, .github/workflows – build and CI orchestration
- /scalehls – C++ headers for dialects, passes, transforms, translations
- lib/… – C++ implementations: Dialects (HLS), Transforms (Dataflow, Directive, Loop, Memory, Tensor), Translation (EmitHLSCpp)
- lib/Bindings – Python (pybind11) and C API layers
- polygeist – C/C++ front-end integration (cgeist)
- tools – Executables: scalehls-opt, scalehls-translate, pyscalehls
- samples – Example kernels and PyTorch models
- test – Regression tests (MLIR files, Python tests)
- Patterns:
- Compiler front-end(s) → MLIR Dialect/APIs → Transformation Pass Pipelines → Translator back-end
- Modular grouping by functionality (Dialect vs. Transforms vs. Binding vs. Tools)

##### README Insights
- Confirms MLIR foundation, purpose (HLS code optimization & DSE), CLI usage patterns, Python binding usage.

a. Main Components
1. Front-End Layer
- C/C++ Parser: polygeist (cgeist)
- PyTorch Parser: Torch-MLIR front-end (optional Python venv)
2. MLIR Core
- MLIR Context & IR data structures
- ScaleHLS Dialect (HLS dialect definitions in include/scalehls/Dialect)
3. Analysis & Transformation Library
- HLS-dedicated analyses (Estimator, Explorer)
- Transform passes (Dataflow, Directive, Loop, Memory, Tensor)
- Design-Space Exploration Engine (DSE pipeline)
4. Translator / Back-End
- EmitHLSCpp translator
5. Bindings & Tools
- Python binding (pybind11 layer, pyscalehls.py)
- C API
- CLI tools (scalehls-opt, scalehls-translate)
6. External Systems
- LLVM/MLIR infrastructure
- Xilinx Vivado HLS (downstream tool)
- Torch-MLIR package (for PyTorch models)
b. Relationships & Data Flow
1. User code (C/C++ or Python) → Front-End → MLIR IR
2. MLIR IR + ScaleHLS Dialect registration → scalehls-opt CLI
3. scalehls-opt invokes analysis & transform passes → optimized MLIR IR
4. Optimized IR → scalehls-translate → HLS C++ code
5. HLS C++ → downstream HLS tool (Vivado) → RTL
6. Python binding offers the same sequence via API calls
c. Architectural Patterns & Principles
- Multi-Stage Pipeline: separate front-end, IR, transforms, back-end
- Modular Dialects & Passes: plug-and-play transforms
- Design-Space Exploration as a first-class pass pipeline
- Bindings layer to expose core library to Python/C
- CMake-driven build for modular components
d. Key Technologies & Frameworks
- LLVM/MLIR core libraries
- C++17
- CMake + Ninja
- pybind11, numpy (Python binding)
- Torch-MLIR (external PyTorch front-end)
- Vivado HLS (external hardware tool)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-End Layer
    subgraph "Front-End Layer"
        FE1["C/C++ Parser\n(polygeist)"]:::frontend
        FE2["PyTorch Parser\n(Torch-MLIR)"]:::frontend
    end

    %% MLIR Core & Dialect
    subgraph "MLIR Core & Dialect"
        Core["MLIR Core\n(Context & IR)"]:::core
        DialectDef["Dialect Definitions\n(include/scalehls/Dialect/HLS)"]:::core
        DialectImpl["Dialect Implementation\n(lib/Dialect/HLS/)"]:::core
        CoreReg["Core Registration\n(InitAllDialects & Passes)"]:::core
    end

    %% Analysis & Transform & DSE Pipeline
    subgraph "Analysis & Transform & DSE Pipeline"
        DSE["Analysis & DSE Engine"]:::transforms
        DF["Dataflow Passes"]:::transforms
        Dir["Directive Passes"]:::transforms
        LoopP["Loop Passes"]:::transforms
        Mem["Memory Passes"]:::transforms
        Tensor["Tensor Passes"]:::transforms
    end

    %% Translator Back-End
    subgraph "Translator Back-End"
        Translator["EmitHLSCpp Translator"]:::translator
    end

    %% Bindings & CLI Tools
    subgraph "Bindings & CLI Tools"
        PythonBind["Python Bindings\n(pybind11)"]:::binding
        CAPI["C API Layer"]:::binding
        CLI1["scalehls-opt CLI"]:::binding
        CLI2["scalehls-translate CLI"]:::binding
    end

    %% External Systems
    subgraph "External Systems"
        LLVMMLIR["LLVM/MLIR Infrastructure"]:::external
        TorchMLIR["Torch-MLIR Package"]:::external
        Vivado["Xilinx Vivado HLS"]:::external
    end

    %% Build & CI
    BuildCI["Build & CI Orchestration"]:::external

    %% Connections
    FE1 -->|uses| LLVMMLIR
    FE2 -->|uses| TorchMLIR
    LLVMMLIR -->|provides IR| Core
    Core -->|register| CoreReg
    CoreReg --> DialectDef
    CoreReg --> DialectImpl

    DialectDef --> CLI1
    DialectImpl --> CLI1
    CoreReg --> CLI1

    CLI1 -->|".mlir"| DSE
    DSE --> DF
    DSE --> Dir
    DSE --> LoopP
    DSE --> Mem
    DSE --> Tensor
    DSE --> CLI2
    CLI2 -->|HLS C++| Translator
    Translator -->|HLS C++| Vivado

    PythonBind --> Core
    PythonBind --> DSE
    PythonBind --> Translator
    CAPI --> Core
    CAPI --> DSE
    CAPI --> Translator

    BuildCI --> Core
    BuildCI --> CLI1

    %% Click Events
    click FE1 "https://github.com/uiuc-chenlab/scalehls/tree/master/polygeist/"
    click DialectDef "https://github.com/uiuc-chenlab/scalehls/tree/master/include/scalehls/Dialect/HLS/"
    click DialectImpl "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Dialect/HLS/"
    click CoreReg "https://github.com/uiuc-chenlab/scalehls/blob/master/include/scalehls/InitAllDialects.h"
    click CoreReg "https://github.com/uiuc-chenlab/scalehls/blob/master/include/scalehls/InitAllPasses.h"
    click DSE "https://github.com/uiuc-chenlab/scalehls/blob/master/include/scalehls/Transforms/Estimator.h"
    click DSE "https://github.com/uiuc-chenlab/scalehls/blob/master/include/scalehls/Transforms/Explorer.h"
    click DSE "https://github.com/uiuc-chenlab/scalehls/blob/master/lib/Transforms/DesignSpaceExplore.cpp"
    click DF "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Transforms/Dataflow/"
    click Dir "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Transforms/Directive/"
    click LoopP "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Transforms/Loop/"
    click Mem "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Transforms/Memory/"
    click Tensor "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Transforms/Tensor/"
    click Translator "https://github.com/uiuc-chenlab/scalehls/blob/master/include/scalehls/Translation/EmitHLSCpp.h"
    click Translator "https://github.com/uiuc-chenlab/scalehls/blob/master/lib/Translation/EmitHLSCpp.cpp"
    click PythonBind "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/Bindings/Python/"
    click PythonBind "https://github.com/uiuc-chenlab/scalehls/blob/master/tools/pyscalehls/pyscalehls.py"
    click CAPI "https://github.com/uiuc-chenlab/scalehls/tree/master/lib/CAPI/"
    click CLI1 "https://github.com/uiuc-chenlab/scalehls/blob/master/tools/scalehls-opt/scalehls-opt.cpp"
    click CLI2 "https://github.com/uiuc-chenlab/scalehls/blob/master/tools/scalehls-translate/scalehls-translate.cpp"
    click BuildCI "https://github.com/uiuc-chenlab/scalehls/blob/master/CMakeLists.txt"
    click BuildCI "https://github.com/uiuc-chenlab/scalehls/blob/master/build-scalehls.sh"
    click BuildCI "https://github.com/uiuc-chenlab/scalehls/blob/master/.github/workflows/buildAndTest.yml"

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef core fill:#cfc,stroke:#333,stroke-width:1px
    classDef transforms fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef translator fill:#ddf,stroke:#333,stroke-width:1px
    classDef binding fill:#ff9,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px
```
