# tzlin1001/2024_aaml architecture

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

- Interactive diagram: https://gitdiagram.com/tzlin1001/2024_aaml
- Repository: https://github.com/tzlin1001/2024_aaml

## Overview

##### Project type and purpose
- This is a hardware‐accelerator research project (an academic “Final Project” for an Accelerator Architectures for Machine Learning course).
- It combines:
- Verilog RTL for a custom CFU/systolic-array accelerator
- Host-side C++ driver and a minimal TFLite Micro inference engine
- Python scripts to convert and evaluate ML models
- A large set of performance input samples

##### File structure
Top level:
– AAML2024_Final_Project/
- *.v (Verilog modules: CFU, controller, PE, systolic_array, gemm, global_buffer_bram)
- model_converter.py (turns a trained TFLite model into binary tensors)
- eval_script.py (loads perf_samples and runs inference)
- perf_samples/*.bin (quantized input data)
- src/ (host software + TFLite-Micro + MLPerf-Tiny code)
– README.md (project summary & performance)
Patterns:
– Hardware: pure RTL modules under project root
– Software: src/proj_menu.cc, src/tflite.cc/h, third_party MLPerf Tiny API
– Scripts: Python conversion & evaluation

##### Key insights from the README
– Final design achieved 7.25× speedup
– Bottlenecks: circuit synthesis time, initialization overhead

##### Main components
A. Host Software Layer
1. Model Converter (Python)
2. TFLite-Micro Inference Engine (C++: tflite.cc/h + third_party/mlperf_tiny)
3. Driver/Proj Menu (proj_menu.cc)
4. Eval Script (eval_script.py)
5. Perf Samples (binary input)
B. Hardware Accelerator
1. Controller.v (top-level handshake & scheduling)
2. Global_Buffer_BRAM.v (on-chip memory interface)
3. CFU.v family (custom fused ops: conv, add, SIMD, SA, post-add-FC)
4. Systolic_Array.v (MxK_KxN datapath for matrix multiply)
5. Proc_Element.v (PE unit inside array)
6. GEMM.v (matrix-multiply wrapper)
C. Data Paths and Interfaces
1. AXI-like or streamed data from host into BRAM
2. Controller commands CFU, array, GEMM
3. CFU returns activation results to host

##### Relationships and interactions
- Model Converter → produces binary weight/data blobs → loaded by Eval Script
- Eval Script + Proj Menu → call TFLite-Micro → parse network → for each op:
- Host code invokes CFU driver (memory‐mapped writes/reads)
- Controller module on hardware → orchestrates data movement between BRAM & PE array
- PE array & CFU modules perform kernels → results returned to host

##### Architectural patterns and design principles
- Heterogeneous co-design: tight host/software & custom hardware
- Data-flow accelerator: systolic array + CFU for fused operations
- Layered software stack: model conversion → inference engine → driver → hardware
- Parameterization: PE array dimensions and CFU op selection are modular

##### Essential elements to capture
– Component names exactly as directories/files
– Annotations of speedup measurement point (between TFLite baseline vs. CFU accel)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data & Conversion"
        MC["Model Converter"]:::python
        PS["Perf Samples"]:::data
    end

    subgraph "Host Software Layer"
        ES["Eval Script"]:::python
        TM["TFLite-Micro Inference Engine"]:::software
        PM["Proj Menu / Driver"]:::software
    end

    subgraph "Hardware Accelerator"
        CTRL["Controller.v"]:::hardware
        BRAM["Global_Buffer_BRAM.v"]:::hardware
        CFU["CFU Family"]:::hardware
        SA["Systolic_Array.v"]:::hardware
        GEMM["GEMM.v"]:::hardware
        PE["Proc_Element.v"]:::hardware
    end

    MC -->|"generates binary blobs"| ES
    PS -->|"input data"| ES
    ES -->|"calls inference"| TM
    PM -->|"invokes ops via driver"| TM
    TM -->|"Host-to-BRAM bus / MMIO"| CTRL
    TM -->|"Host-to-BRAM bus / MMIO"| BRAM
    CTRL -->|"control signals"| CFU
    CTRL -->|"control signals"| SA
    CTRL -->|"control signals"| GEMM
    SA -->|"computes multiply"| PE
    CFU -->|"returns activations"| CTRL
    CTRL -->|"returns results"| TM

    click MC "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/model_converter.py"
    click PS "https://github.com/tzlin1001/2024_aaml/tree/main/AAML2024_Final_Project/perf_samples"
    click ES "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/eval_script.py"
    click PM "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/src/proj_menu.cc"
    click TM "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/src/tflite.cc"
    click TM "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/src/tflite.h"
    click TM "https://github.com/tzlin1001/2024_aaml/tree/main/AAML2024_Final_Project/src/third_party/mlperf_tiny/api"
    click CTRL "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/controller.v"
    click BRAM "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/global_buffer_bram.v"
    click CFU "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/cfu.v"
    click CFU "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/cfu_conv.v"
    click CFU "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/cfuop_add.v"
    click CFU "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/cfuop_sa.v"
    click CFU "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/cfuop_simd.v"
    click SA "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/systolic_array.v"
    click PE "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/proc_element.v"
    click GEMM "https://github.com/tzlin1001/2024_aaml/blob/main/AAML2024_Final_Project/gemm.v"

    classDef python fill:#7be39b,stroke:#333,stroke-width:1px
    classDef data fill:#a3e7fc,stroke:#333,stroke-width:1px
    classDef software fill:#80b3ff,stroke:#333,stroke-width:1px
    classDef hardware fill:#ffa500,stroke:#333,stroke-width:1px
```
