# gwokhiujin/avelang architecture

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

- Interactive diagram: https://gitdiagram.com/gwokhiujin/avelang
- Repository: https://github.com/gwokhiujin/avelang

## Overview

1. **Overall shape**
   Ave is a mixed Python/C++ GPU-kernel compiler stack. The Python package `avelang` is the user-facing layer, while the C++ code implements parsing, IR construction, lowering passes, and backend code generation through an MLIR-based pipeline.

2. **User-facing entry point**
   Kernel authors import `avelang` from Python and write “AveLang” kernels in a Pythonic style. The package exposes language constructs, runtime helpers, backend selection, specialization logic, and compilation/JIT entry points. This is the top boundary of the system.

3. **Frontend and parsing**
   The C++ frontend in `lib/Frontend` parses AveLang source into an AST. `lib/AST` contains the language tree, visitors, context, and casting utilities. Diagnostics live in `lib/Basic`, so parse/type errors are reported before IR generation.

4. **Language and type model**
   `lib/IR/type_system.cc`, `type_promotion.cc`, `symbol_table.cc`, `symbol_scope.cc`, and `named_module.cc` define the semantic layer that sits between parsing and MLIR generation. This subsystem resolves names, manages scopes, enforces tensor/layout rules, and handles type promotion and symbol lookup.

5. **MLIR generation core**
   `lib/IR/mlir_generator.cc` and related files translate the AveLang AST and semantic model into MLIR. Supporting pieces such as `expr_generator.cc`, `function_generator.cc`, `layout_operation.cc`, `constant_folder.cc`, and `mangler.cc` shape the generated IR, preserve naming/symbol identity, and fold compile-time values.

6. **Built-in modules and intrinsics**
   The IR layer also contains embedded built-in dialect content and intrinsic libraries. `lib/IR/builtin_module.cc` and `lib/IR/Intrinsics/*` provide AMDGPU and NVVM intrinsic definitions, signatures, and support code. These are the bridge from high-level kernel code to backend-specific GPU operations.

7. **Custom AveLang dialect**
   Under `lib/Dialect/AveLang`, the project defines an MLIR dialect for AveLang-specific ops, types, and transforms. TableGen files (`*.td`) plus generated/handwritten dialect code establish the intermediate representation used before lowering to more standard MLIR or LLVM forms.

8. **Lowering and normalization passes**
   `lib/Dialect/AveLang/Transforms` contains the first lowering stages: return normalization, stack allocation hoisting, lowering AveLang ops to memref, and lowering GPU ops to intrinsics. These passes are the main boundary where the high-level dialect becomes backend-oriented IR.

9. **GPU-target pipeline**
   `lib/Target/GPU` provides target-agnostic GPU lowering support: outlining, linking intrinsic implementations, and lowering to LLVM. This layer is shared by backends and acts as the common GPU compilation backbone before vendor-specific codegen.

10. **Vendor backends**
   There are two concrete GPU backends:
   - `lib/Target/NVVM` for NVIDIA / CUDA-style codegen
   - `lib/Target/AMDGPU` for AMD / ROCm / HIP-style codegen  
   Each backend has its own pipeline, backend driver, and tests, with AMDGPU additionally including ROCm installation detection and math/legalization passes.

11. **Python compilation and runtime packages**
   The Python code is split into logical layers:
   - `python/avelang/language`: language surface syntax/constructs
   - `python/avelang/compiler`: code generation and compiler orchestration
   - `python/avelang/runtime`: build, driver, JIT, and specialization
   - `python/avelang/backends`: backend-facing compiler/driver wrappers for AMDGPU and NVIDIA  
   This is the orchestration layer that invokes the native compiler and runtime machinery.

12. **Native Python bindings**
   `python/src/avelang_bindings.cc` provides the compiled extension that connects Python to the C++ implementation. This is the key interop boundary: Python constructs and runtime helpers call into native compilation and execution facilities rather than implementing the compiler in pure Python.

13. **Tests and validation**
   The `test/` tree covers language primitives, memory/layout behavior, JIT behavior, and end-to-end examples for GEMM/GEMV on both AMDGPU and NVIDIA. C++ tests also exist beside the IR and backend code. This indicates the repo validates both compiler correctness and target-specific code generation.

14. **Docs, examples, and tooling**
   The `docs/` site describes installation, tutorials, and language reference. `benchmark/` and `python/avelang_kernels/` provide performance and example kernels. Utility scripts in `tools/` dump LLVM IR or assembly, which are useful for inspecting the compiler pipeline output.

15. **Build and packaging**
   The project uses CMake for the native code, plus Python packaging via `pyproject.toml` and `setup.py`. The repository is therefore a hybrid source tree: native libraries and targets are built with CMake, while the Python package is installed as `ave-lang` and exposes the end-user API as `avelang`.

Main entry points: [`lib/IR/mlir_generator.cc`](https://github.com/gwokhiujin/avelang/blob/master/lib/IR/mlir_generator.cc) (MLIR Gen), [`lib/Target/GPU`](https://github.com/gwokhiujin/avelang/tree/master/lib/Target/GPU) (GPU Core), [`python/src/avelang_bindings.cc`](https://github.com/gwokhiujin/avelang/blob/master/python/src/avelang_bindings.cc) (Native Bindings), [`python/avelang/backends`](https://github.com/gwokhiujin/avelang/tree/master/python/avelang/backends) (Backend Wrappers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python stack"]
  node_python_language["Language API<br/>python surface"]
  node_python_compiler["Compiler API<br/>python orchestration"]
  node_python_runtime["Runtime<br/>python execution"]
  node_python_backends["Backend Wrappers<br/>python backend layer"]
  node_python_bindings["Native Bindings<br/>pybind bridge"]
end

subgraph group_cpp["C++ core"]
  node_frontend["Frontend<br/>parser"]
  node_ast["AST<br/>syntax tree"]
  node_basic["Diagnostics<br/>errors"]
  node_type_system["Type Model<br/>semantic analysis<br/>[type_system.cc]"]
  node_mlir_gen["MLIR Gen<br/>ir generation<br/>[mlir_generator.cc]"]
  node_ir_support["IR Helpers<br/>ir utilities"]
  node_builtin_intrinsics["Builtins<br/>intrinsic libraries"]
  node_dialect["AveLang Dialect<br/>mlir dialect"]
  node_dialect_transforms["Lowering Passes<br/>mlir passes"]
end

subgraph group_gpu["GPU targets"]
  node_gpu_core["GPU Core<br/>gpu lowering"]
  node_nvvm["NVVM Backend<br/>nvidia backend"]
  node_amdgpu["AMDGPU Backend<br/>amd backend"]
end

subgraph group_docs["Docs and tests"]
  node_tests["Tests<br/>validation"]
  node_docs_site["Docs Site<br/>documentation"]
  node_benchmarks["Benchmarks<br/>performance examples"]
end

node_python_language -->|"kernel code"| node_python_compiler
node_python_compiler -->|"invoke"| node_python_bindings
node_python_runtime -->|"execute"| node_python_bindings
node_python_backends -->|"wrap"| node_python_bindings
node_python_bindings -->|"parse"| node_frontend
node_frontend -->|"build"| node_ast
node_frontend -->|"report"| node_basic
node_ast -->|"analyze"| node_type_system
node_type_system -->|"lower"| node_mlir_gen
node_mlir_gen -->|"use"| node_ir_support
node_mlir_gen -->|"inline"| node_builtin_intrinsics
node_mlir_gen -->|"emit"| node_dialect
node_dialect -->|"lower"| node_dialect_transforms
node_dialect_transforms -->|"handoff"| node_gpu_core
node_builtin_intrinsics -->|"bridge"| node_gpu_core
node_gpu_core -->|"target"| node_nvvm
node_gpu_core -->|"target"| node_amdgpu
node_python_backends -->|"select"| node_nvvm
node_python_backends -->|"select"| node_amdgpu
node_nvvm -->|"verify"| node_tests
node_amdgpu -->|"verify"| node_tests
node_docs_site -->|"describe"| node_python_language
node_benchmarks -->|"exercise"| node_tests

click node_python_language "https://github.com/gwokhiujin/avelang/tree/master/python/avelang/language"
click node_python_compiler "https://github.com/gwokhiujin/avelang/tree/master/python/avelang/compiler"
click node_python_runtime "https://github.com/gwokhiujin/avelang/tree/master/python/avelang/runtime"
click node_python_backends "https://github.com/gwokhiujin/avelang/tree/master/python/avelang/backends"
click node_python_bindings "https://github.com/gwokhiujin/avelang/blob/master/python/src/avelang_bindings.cc"
click node_frontend "https://github.com/gwokhiujin/avelang/tree/master/lib/Frontend"
click node_ast "https://github.com/gwokhiujin/avelang/tree/master/lib/AST"
click node_basic "https://github.com/gwokhiujin/avelang/tree/master/lib/Basic"
click node_type_system "https://github.com/gwokhiujin/avelang/blob/master/lib/IR/type_system.cc"
click node_mlir_gen "https://github.com/gwokhiujin/avelang/blob/master/lib/IR/mlir_generator.cc"
click node_ir_support "https://github.com/gwokhiujin/avelang/tree/master/lib/IR"
click node_builtin_intrinsics "https://github.com/gwokhiujin/avelang/tree/master/lib/IR/Intrinsics"
click node_dialect "https://github.com/gwokhiujin/avelang/tree/master/lib/Dialect/AveLang/IR"
click node_dialect_transforms "https://github.com/gwokhiujin/avelang/tree/master/lib/Dialect/AveLang/Transforms"
click node_gpu_core "https://github.com/gwokhiujin/avelang/tree/master/lib/Target/GPU"
click node_nvvm "https://github.com/gwokhiujin/avelang/tree/master/lib/Target/NVVM"
click node_amdgpu "https://github.com/gwokhiujin/avelang/tree/master/lib/Target/AMDGPU"
click node_tests "https://github.com/gwokhiujin/avelang/tree/master/test"
click node_docs_site "https://github.com/gwokhiujin/avelang/tree/master/docs"
click node_benchmarks "https://github.com/gwokhiujin/avelang/tree/master/benchmark"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_language,node_python_compiler,node_python_runtime,node_python_backends,node_python_bindings toneBlue
class node_frontend,node_ast,node_basic,node_type_system,node_mlir_gen,node_ir_support,node_builtin_intrinsics,node_dialect,node_dialect_transforms toneAmber
class node_gpu_core,node_nvvm,node_amdgpu toneMint
class node_tests,node_docs_site,node_benchmarks toneRose
```

## Components

### Python stack

User-facing language, compiler orchestration, runtime, and backend wrappers.

- [Language API](https://github.com/gwokhiujin/avelang/tree/master/python/avelang/language): python surface · Pythonic AveLang syntax and built-in language constructs. · `python/avelang/language`
- [Compiler API](https://github.com/gwokhiujin/avelang/tree/master/python/avelang/compiler): python orchestration · Python-side code generation and compiler entry points. · `python/avelang/compiler`
- [Runtime](https://github.com/gwokhiujin/avelang/tree/master/python/avelang/runtime): python execution · Build, driver, JIT, and specialization helpers. · `python/avelang/runtime`
- [Backend Wrappers](https://github.com/gwokhiujin/avelang/tree/master/python/avelang/backends): python backend layer · Python wrappers for AMDGPU and NVIDIA compilation/driver flows. · `python/avelang/backends`
- [Native Bindings](https://github.com/gwokhiujin/avelang/blob/master/python/src/avelang_bindings.cc): pybind bridge · Compiled extension connecting Python to the C++ implementation. · `python/src/avelang_bindings.cc`

### C++ core

Frontend, IR, MLIR generation, dialects, and shared utilities.

- [Frontend](https://github.com/gwokhiujin/avelang/tree/master/lib/Frontend): parser · Parses AveLang source into an AST. · `lib/Frontend`
- [AST](https://github.com/gwokhiujin/avelang/tree/master/lib/AST): syntax tree · Language tree, visitors, casting, and AST context. · `lib/AST`
- [Diagnostics](https://github.com/gwokhiujin/avelang/tree/master/lib/Basic): errors · Compile-time diagnostics and reporting. · `lib/Basic`
- [Type Model](https://github.com/gwokhiujin/avelang/blob/master/lib/IR/type_system.cc): semantic analysis · Type promotion, symbols, scopes, and semantic module state. · `lib/IR/type_system.cc`
- [MLIR Gen](https://github.com/gwokhiujin/avelang/blob/master/lib/IR/mlir_generator.cc): ir generation · Translates AST and semantic state into MLIR. · `lib/IR/mlir_generator.cc`
- [IR Helpers](https://github.com/gwokhiujin/avelang/tree/master/lib/IR): ir utilities · Expression/function generation, layout ops, mangling, folding, and parsing utilities. · `lib/IR`
- [Builtins](https://github.com/gwokhiujin/avelang/tree/master/lib/IR/Intrinsics): intrinsic libraries · Embedded builtin modules plus AMDGPU and NVVM intrinsic definitions. · `lib/IR/Intrinsics`
- [AveLang Dialect](https://github.com/gwokhiujin/avelang/tree/master/lib/Dialect/AveLang/IR): mlir dialect · Custom AveLang ops, types, and dialect definitions. · `lib/Dialect/AveLang/IR`
- [Lowering Passes](https://github.com/gwokhiujin/avelang/tree/master/lib/Dialect/AveLang/Transforms): mlir passes · Normalizes returns, hoists allocations, and lowers AveLang/GPU ops. · `lib/Dialect/AveLang/Transforms`

### GPU targets

Shared GPU lowering plus NVIDIA and AMDGPU backend pipelines.

- [GPU Core](https://github.com/gwokhiujin/avelang/tree/master/lib/Target/GPU): gpu lowering · Shared GPU outlining, intrinsic linking, and lowering to LLVM. · `lib/Target/GPU`
- [NVVM Backend](https://github.com/gwokhiujin/avelang/tree/master/lib/Target/NVVM): nvidia backend · NVIDIA-specific GPU-to-NVVM pipeline and codegen. · `lib/Target/NVVM`
- [AMDGPU Backend](https://github.com/gwokhiujin/avelang/tree/master/lib/Target/AMDGPU): amd backend · AMDGPU pipeline, ROCm detection, legalization, and codegen. · `lib/Target/AMDGPU`

### Docs and tests

Documentation, examples, benchmarks, and validation coverage.

- [Tests](https://github.com/gwokhiujin/avelang/tree/master/test): validation · End-to-end examples and primitive behavior coverage across targets. · `test`
- [Docs Site](https://github.com/gwokhiujin/avelang/tree/master/docs): documentation · Installation, tutorials, language reference, and developer notes. · `docs`
- [Benchmarks](https://github.com/gwokhiujin/avelang/tree/master/benchmark): performance examples · Performance-oriented sample kernels and benchmark entry points. · `benchmark`

## Connections

- Language API → Compiler API: kernel code · Language constructs feed compilation orchestration.
- Compiler API → Native Bindings: invoke · Python compilation calls into native bindings.
- Runtime → Native Bindings: execute · Runtime and JIT paths cross the native boundary.
- Backend Wrappers → Native Bindings: wrap · Backend wrappers delegate to the extension module.
- Native Bindings → Frontend: parse · Native layer enters the C++ compilation pipeline.
- Frontend → AST: build · Parser produces the AveLang AST.
- Frontend → Diagnostics: report · Parsing failures and diagnostics are emitted through the basic error layer.
- AST → Type Model: analyze · AST nodes are resolved into semantic types and scopes.
- Type Model → MLIR Gen: lower · Semantic resolution feeds MLIR generation.
- MLIR Gen → IR Helpers: use · Core generation relies on helper modules for expressions, functions, layouts, and folding.
- MLIR Gen → Builtins: inline · Generated IR incorporates builtin and GPU intrinsic modules.
- MLIR Gen → AveLang Dialect: emit · High-level AveLang semantics are materialized as a custom MLIR dialect.
- AveLang Dialect → Lowering Passes: lower · Dialect ops are normalized and lowered by AveLang transforms.
- Lowering Passes → GPU Core: handoff · Lowered GPU-oriented IR enters the shared GPU backend pipeline.
- Builtins → GPU Core: bridge · Intrinsic implementations connect high-level kernels to backend GPU ops.
- GPU Core → NVVM Backend: target · Shared GPU lowering feeds the NVIDIA backend.
- GPU Core → AMDGPU Backend: target · Shared GPU lowering feeds the AMD backend.
- Backend Wrappers → NVVM Backend: select · Python backend selection chooses the NVIDIA path.
- Backend Wrappers → AMDGPU Backend: select · Python backend selection chooses the AMDGPU path.
- NVVM Backend → Tests: verify · NVIDIA backend behavior is covered by target tests.
- AMDGPU Backend → Tests: verify · AMDGPU backend behavior is covered by target tests.
- Docs Site → Language API: describe · Documentation explains language constructs and usage.
- Benchmarks → Tests: exercise · Benchmarks and sample kernels validate performance-sensitive paths.