# cedard234/accelenetor architecture

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

- Interactive diagram: https://gitdiagram.com/cedard234/accelenetor
- Repository: https://github.com/cedard234/accelenetor

## Overview

##### Project Type and Purpose
- This is a hardware accelerator project, specifically a simplified LeNet-5 Convolutional Neural Network (CNN) implemented in SystemVerilog.
- Its purpose is to accelerate MNIST digit recognition, and the accelerator is synthesized on a Cyclone V FPGA.
- The README emphasizes that the loops in the network’s layers (convolution, activation, pooling, fully-connected) have been completely unrolled, leading to high resource usage.

##### Analyzing the File Structure
- Top-level organization:
- Directories like “src” contain most hardware RTL components, broken out into files for each layer (convolution layers, activation layers, max pooling layers, fully connected layer).
- The “kernal_trained” directory holds pre-trained weights or matrix representations used by the accelerator.
- “testbenches” include simulation/test modules for verifying individual components and the whole accelerator.
- “test_images” provides sample inputs used during testing.
- The structure reflects a modular design where each layer or accelerator component is in its own file, making it straightforward to show individual blocks and their interactions.

##### Key Components
- Input/Preprocessing:
- Test images or input module (data captured and fed from the “test_images” set).
- CNN Accelerator Blocks:
- Convolutional Layers: Files like conv_layer_1.sv, conv_layer_2.sv, conv_layer_3.sv.
- Activation Layers: activation_layer_1.sv, activation_layer_2.sv, activation_layer_3.sv.
- Pooling Layers: maxpooling_1.sv and maxpooling_2.sv.
- Fully Connected Layer: fully_connect_layer.sv.
- Supporting Components: convolution_point.sv and kernel_and_matrix.sv are likely used to implement the convolution arithmetic along with integration of kernel values.
- Top-level Accelerator Modules: AcceLeNetor.sv and Lenet_accelerator.sv connect the individual layers.
- Kernel Data:
- Files in the “kernal_trained” directory represent pre-trained kernel and matrix definitions (with variations in bit width—8 bits and 16 bits). These should be shown as data sources feeding the convolution blocks.
- Testbenches:
- Although not part of the operational hardware, indicate that these exist to verify functionality. They illustrate simulation and verification paths.

##### Relationships and Interactions
- A sequential data flow through the accelerator:
Input Image → Conv Layer 1 → Activation Layer 1 → Maxpooling 1 → Conv Layer 2 → Activation Layer 2 → Maxpooling 2 → Conv Layer 3 → Activation Layer 3 → Fully Connected Layer → Output (digit classification)
- Use of pre-trained kernel data (from the “kernal_trained” files) feeding into the convolution blocks.
- Denote how the top-level modules (AcceLeNetor.sv and Lenet_accelerator.sv) instantiate and coordinate all the lower-level modules.

##### Architectural Patterns and Design Principles
- Unrolled Loops:
- That the loops are fully unrolled for each layer. This means that pipeline concurrency is high and that each operation is instantiated separately.
- Modular and Hierarchical Structure:
- Each major CNN component is implemented as a separate module for clarity and reusability.
- Data Flow:
- FPGA-Specific Implementation:
- That the system interfaces with an FPGA (Cyclone V) and may include specific clock domains, reset controllers, and possibly I/O mapping (though not explicitly in the file structure). You might want to include these as context blocks if found elsewhere in your design docs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-Level Nodes
    TestImages["Test Images"]:::data
    TopLevel["AcceLeNetor / Lenet_accelerator"]:::orchestrator
    Output["Digit Classification"]:::accelerator
    Unrolled["Note: Loops_Fully_Unrolled"]:::support

    %% Main Data Flow
    TestImages -->|"feeds"| TopLevel

    %% Verification Environment Subgraph
    subgraph "Verification Environment"
        Testbenches["Testbenches"]:::test
    end
    Testbenches -->|"sim_input"| TopLevel

    %% CNN Accelerator Core Subgraph
    subgraph "CNN Accelerator Core"
        Conv1["conv_layer_1"]:::accelerator
        Act1["activation_layer_1"]:::accelerator
        Pool1["maxpooling_1"]:::accelerator
        Conv2["conv_layer_2"]:::accelerator
        Act2["activation_layer_2"]:::accelerator
        Pool2["maxpooling_2"]:::accelerator
        Conv3["conv_layer_3"]:::accelerator
        Act3["activation_layer_3"]:::accelerator
        FullyConn["fully_connect_layer"]:::accelerator
    end

    TopLevel -->|"orchestrates"| Conv1
    Conv1 -->|"processes"| Act1
    Act1 -->|"processes"| Pool1
    Pool1 -->|"processes"| Conv2
    Conv2 -->|"processes"| Act2
    Act2 -->|"processes"| Pool2
    Pool2 -->|"processes"| Conv3
    Conv3 -->|"processes"| Act3
    Act3 -->|"processes"| FullyConn
    FullyConn -->|"outputs"| Output

    %% Kernel Data Subgraph
    subgraph "Kernel Data"
        KernelData16["kernel_and_matrix_16bits"]:::data
        KernelData8["kernel_and_matrix_8bits"]:::data
    end

    KernelData16 -->|"feeds"| Conv1
    KernelData8 -->|"feeds"| Conv1

    %% Support Modules
    ConvPoint["convolution_point"]:::support
    KernelMatrix["kernel_and_matrix"]:::support

    ConvPoint -->|"supports"| Conv1
    KernelMatrix -->|"integrates"| Conv1

    %% Annotation for Unrolled Loops (non-connected note)
    Unrolled --- TopLevel

    %% Click Events
    click TestImages "https://github.com/cedard234/accelenetor/tree/master/test_images/"
    click TopLevel "https://github.com/cedard234/accelenetor/blob/master/src/AcceLeNetor.sv"
    click TopLevel "https://github.com/cedard234/accelenetor/blob/master/src/Lenet_accelerator.sv"
    click Conv1 "https://github.com/cedard234/accelenetor/blob/master/src/conv_layer_1.sv"
    click Conv2 "https://github.com/cedard234/accelenetor/blob/master/src/conv_layer_2.sv"
    click Conv3 "https://github.com/cedard234/accelenetor/blob/master/src/conv_layer_3.sv"
    click Act1 "https://github.com/cedard234/accelenetor/blob/master/src/activation_layer_1.sv"
    click Act2 "https://github.com/cedard234/accelenetor/blob/master/src/activation_layer_2.sv"
    click Act3 "https://github.com/cedard234/accelenetor/blob/master/src/activation_layer_3.sv"
    click Pool1 "https://github.com/cedard234/accelenetor/blob/master/src/maxpooling_1.sv"
    click Pool2 "https://github.com/cedard234/accelenetor/blob/master/src/maxpooling_2.sv"
    click FullyConn "https://github.com/cedard234/accelenetor/blob/master/src/fully_connect_layer.sv"
    click ConvPoint "https://github.com/cedard234/accelenetor/blob/master/src/convolution_point.sv"
    click KernelMatrix "https://github.com/cedard234/accelenetor/blob/master/src/kernel_and_matrix.sv"
    click KernelData16 "https://github.com/cedard234/accelenetor/blob/master/kernal_trained/kernel_and_matrix_16bits.sv"
    click KernelData8 "https://github.com/cedard234/accelenetor/blob/master/kernal_trained/kernel_and_matrix_8bits.sv"
    click Testbenches "https://github.com/cedard234/accelenetor/tree/master/testbenches/"

    %% Styles
    classDef orchestrator fill:#ccffcc,stroke:#000,stroke-width:2px;
    classDef accelerator fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef data fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef support fill:#ffcccc,stroke:#000,stroke-width:2px;
    classDef test fill:#e6ccff,stroke:#000,stroke-width:2px;
```
