# cornell-zhang/allo architecture

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

- Interactive diagram: https://gitdiagram.com/cornell-zhang/allo
- Repository: https://github.com/cornell-zhang/allo

## Overview

##### Project Type and Purpose
- Allo is a Python-embedded Accelerator Design Language (ADL) and compiler built on MLIR.
- It provides a DSL (in Python) for specifying hardware kernels, a progressive transformation framework (passes), and multiple backends (AIE, HLS, LLVM, Simulator, TAPA, Vitis) that emit FPGA/ASIC-targeted code or perform simulation.

##### File-Structure Analysis
- Top-level “allo/” directory: core Python DSL, IR builder, transformations, autoscheduler, passes, frontends (PyTorch), backends, dataflow abstraction, memory model, verification, utilities.
- “mlir/”: C++ MLIR dialect definitions, conversion passes, translation to HLS, C API bindings.
- “allo/backend/…”: backend-specific codegen and runtime config for AIE, HLS, LLVM IR, Vitis, simulator, TAPA.
- “allo/autoscheduler/…”: DFG construction, loop outlining, schedule primitives.
- “allo/ir/…”: MLIR IR builder, type system, transforms, template engine, symbol resolution, visitor framework.
- “aio/harness/…”: generated build scripts and runtime stubs for different target flows (Vivado, Vitis, AIE, TAPA).
- “examples/” and “tests/”: usage scenarios and validation.
- Configuration files: setup.py, .github/workflows, scripts/lint, docker/ for containerized builds.

##### Key README Insights
- Emphasis on “progressive hardware customizations” via MLIR passes.
- “Composable schedules” that .compose() transformations.
- Multiple backends and formal verification.

a. Main Components
1) Python Frontend & DSL
2) IR Builder (MLIR Python binding)
3) MLIR Dialect & Compiler Pipeline
- Parsing/Tracing
- IR canonicalization
- Dataflow Graph (DFG) construction
- Autoscheduler passes
- Loop & memory transformation passes
- Type lowering & verification
- Backend-agnostic optimizations
4) Backend Codegens
- LLVM IR
- HLS (Vivado/TAPA/Vitis)
- AIE (AI Engine)
- Simulator
5) Harness Generator & Build System
6) External Services & Tools
- MLIR Core
- LLVM Project
- Dockerized environments
- CI workflows
7) User-Facing Artifacts
- Generated HLS C++
- Hardware bitstreams (Vivado, Vitis)
- Simulation outputs

b. Relationships & Data Flow
- User writes Python DSL → Tracer/frontends produce an MLIR module → IR Builder emits Allo dialect → Sequence of compiler passes (canonicalization, DFG, autoscheduler, transform passes) → Lowering passes generate either LLVM IR or target-specific HLS C++ → Harness Generator produces build scripts & stubs → External toolchains (Vivado/Vitis/aienginesimulator) consume artifacts → Hardware/SW binary.
- Verification pass hooks inserted post-transforms.
- Tests and examples invoke Python API, triggering end-to-end pipeline.

c. Architectural Patterns & Principles
- Progressive, composable pass pipeline.
- Separation of concerns: DSL vs. IR vs. backends.
- Plugin-style backends for extensibility.
- Parameterized kernel templates for reuse.
- Formal verification integrated as a pass.

d. Technologies & Frameworks
- Python 3 DSL
- MLIR (C++ dialects & Python bindings)
- LLVM (codegen)
- Vivado HLS, Vitis HLS, TAPA
- Docker for reproducible builds
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Python Frontend & DSL
    subgraph "Python Frontend & DSL"
        direction TB
        DSL["DSL Core"]:::python
        Lib["Frontend Library"]:::python
        PT["PyTorch Frontend"]:::python
        Tracer["Parsing/Tracing"]:::python
    end

    %% IR Builder
    IRB["IR Builder (MLIR Python binding)"]:::python

    %% Compiler Pass Pipeline
    subgraph "Compiler Pass Pipeline"
        direction TB
        CP1["DFG Construction Pass"]:::passes
        CP2["IR Canonicalization Passes"]:::passes
        CP3["Autoscheduler Passes & Primitives"]:::passes
        CP4["Loop Outline Pass"]:::passes
        CP5["Loop & Memory Transformation Passes"]:::passes
        CP6["Backend-Agnostic Optimizations"]:::passes
        CP7["Type Lowering & Verification"]:::passes
    end

    %% Backend Codegens
    subgraph "Backend Codegens"
        direction TB
        BL["LLVM IR Codegen"]:::backend
        BH["HLS Codegen (Vivado/Vitis/TAPA)"]:::backend
        BA["AI Engine (AIE) Codegen"]:::backend
        BS["Simulator"]:::backend
        BI["IP Generation"]:::backend
    end

    %% Harness Generator
    HG["Harness Generator & Build System"]:::python

    %% External Tools & Services
    subgraph "External Tools & CI"
        direction TB
        Vivado["Vivado HLS"]:::external
        Vitis["Vitis HLS"]:::external
        TAPA["TAPA HLS"]:::external
        AIESim["AI Engine Simulator"]:::external
        Docker["Docker Environments"]:::external
        CI["CI Workflows"]:::external
        LLVMProj["LLVM Project"]:::external
    end

    %% User Artifacts
    subgraph "User-Facing Artifacts"
        direction TB
        HLSCode["Generated HLS C++"]:::artifacts
        Bitstream["Hardware Bitstreams"]:::artifacts
        SimLog["Simulation Outputs"]:::artifacts
    end

    %% Connections - Data Flow
    DSL -->|writes DSL code| Tracer
    Tracer -->|emits MLIR module| IRB
    IRB -->|builds Allo dialect| CP1
    CP1 -->|DFG| CP2
    CP2 -->|canonical MLIR| CP3
    CP3 -->|scheduled DFG| CP4
    CP4 -->|outlined loops| CP5
    CP5 -->|transformed loops/memory| CP6
    CP6 -->|optimized IR| CP7
    CP7 -->|verified IR| BL
    CP7 -->|"verified IR"| BH
    CP7 -->|IR| BA
    CP7 -->|IR| BS
    CP7 -->|IR| BI

    BL -->|LLVM IR| HG
    BH -->|C++ HLS code| HG
    BA -->|AIE kernels| HG
    BS -->|sim inputs| HG
    BI -->|IP cores| HG

    HG -->|build scripts + stubs| Vivado
    HG -->|build scripts + stubs| Vitis
    HG -->|build scripts + stubs| TAPA
    HG -->|build scripts + stubs| AIESim

    Vivado -->|bitstream| Bitstream
    Vitis -->|bitstream| Bitstream
    TAPA -->|bitstream| Bitstream
    AIESim -->|simulation log| SimLog

    %% CI and Docker
    Docker -.->|env| HG
    CI -.->|tests/examples| DSL
    LLVMProj -.->|compiler core| CP2

    %% Styles
    classDef python fill:#aec7e8,stroke:#333,stroke-width:1px;
    classDef passes fill:#98df8a,stroke:#333,stroke-width:1px;
    classDef backend fill:#ffdb58,stroke:#333,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef artifacts fill:#c7c7c7,stroke:#333,stroke-width:1px;

    %% Click Events
    click DSL "https://github.com/cornell-zhang/allo/blob/main/allo/dsl.py"
    click Lib "https://github.com/cornell-zhang/allo/blob/main/allo/frontend/__init__.py"
    click PT "https://github.com/cornell-zhang/allo/blob/main/allo/frontend/pytorch.py"
    click Tracer "https://github.com/cornell-zhang/allo/blob/main/allo/frontend/tracer.py"
    click IRB "https://github.com/cornell-zhang/allo/blob/main/allo/ir/builder.py"
    click CP2 "https://github.com/cornell-zhang/allo/blob/main/allo/autoscheduler/passes.py"
    click CP1 "https://github.com/cornell-zhang/allo/blob/main/allo/autoscheduler/dfg.py"
    click CP3 "https://github.com/cornell-zhang/allo/blob/main/allo/autoscheduler/primitives.py"
    click CP4 "https://github.com/cornell-zhang/allo/blob/main/allo/autoscheduler/outline_loops.mlir"
    click CP5 "https://github.com/cornell-zhang/allo/blob/main/allo/ir/transform.py"
    click CP7 "https://github.com/cornell-zhang/allo/blob/main/allo/verify.py"
    click BL "https://github.com/cornell-zhang/allo/blob/main/allo/backend/llvm.py"
    click BH "https://github.com/cornell-zhang/allo/blob/main/allo/backend/hls.py"
    click BH "https://github.com/cornell-zhang/allo/blob/main/allo/backend/vitis.py"
    click BH "https://github.com/cornell-zhang/allo/blob/main/allo/backend/tapa.py"
    click BA "https://github.com/cornell-zhang/allo/blob/main/allo/backend/aie.py"
    click BS "https://github.com/cornell-zhang/allo/blob/main/allo/backend/simulator.py"
    click BI "https://github.com/cornell-zhang/allo/blob/main/allo/backend/ip.py"
    click HG "https://github.com/cornell-zhang/allo/tree/main/allo/harness/"
    click Vivado "https://github.com/cornell-zhang/allo/tree/main/docker/"
    click CI "https://github.com/cornell-zhang/allo/tree/main/.github/workflows/"
    click LLVMProj "https://github.com/cornell-zhang/allo/tree/main/externals/llvm-project"
```
