# lucas-farimart/arandu architecture

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

- Interactive diagram: https://gitdiagram.com/lucas-farimart/arandu
- Repository: https://github.com/lucas-farimart/arandu

## Overview

Arandu is a naive DNN accelerator implemented in RTL. Its documented focus is an SRAM subsystem that stores weights and activations while providing latency-hidden bandwidth. The tree also contains software and data-memory utilities for quantization, network-memory layout, and packing analysis. RTL excerpts were not supplied, so the hardware component relationships below are documented at subsystem level rather than asserted as source-verified calls; the evidence limit is noted with dashed links.

Main entry points: [`rtl/sram_subsystem.sv`](https://github.com/lucas-farimart/arandu/blob/main/rtl/sram_subsystem.sv) (SRAM subsystem), [`rtl/arandu_core.sv`](https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu_core.sv) (Accelerator core), [`data_mem/mem_generator.py`](https://github.com/lucas-farimart/arandu/blob/main/data_mem/mem_generator.py) (Model memory export), [`rtl/neuron_int8.sv`](https://github.com/lucas-farimart/arandu/blob/main/rtl/neuron_int8.sv) (INT8 neuron)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hw["Accelerator RTL"]
  node_arandu["Arandu top<br/>[arandu.sv]"]
  node_core["Accelerator core<br/>[arandu_core.sv]"]
  node_control["Control logic<br/>[arandu_ctrl.sv]"]
  node_fsm["FSM controller<br/>[fsm_controller.sv]"]
  node_npu8["INT8 NPU<br/>[npu_int8.sv]"]
  node_npu32["FP32 NPU<br/>[npu_fp32.sv]"]
  node_neuron8["INT8 neuron<br/>[neuron_int8.sv]"]
  node_neuron32["FP32 neuron<br/>[neuron_fp32.sv]"]
  node_requant["Requantization<br/>[requant_unit.sv]"]
  node_mac["Booth multiplier<br/>[booth_radix4.sv]"]
  node_fpadd["FP32 adder<br/>[fp32_add.sv]"]
end

subgraph group_mem["On-chip Memory"]
  node_memory["SRAM subsystem<br/>[sram_subsystem.sv]"]
  node_activations[("Activation SRAM<br/>[mem_actvs.sv]")]
  node_weights[("Weight SRAM<br/>[mem_weights.sv]")]
  node_metadata["Metadata map<br/>[metadata_map.sv]"]
  node_dram["DRAM controller<br/>[dram_controller.sv]"]
  node_sram[("SRAM macro<br/>[sram_32x512_1rw.v]")]
end

subgraph group_prep["Model and Data Preparation"]
  node_quant["TFLite quantization<br/>[quant_tflite.py]"]
  node_export["Model memory export<br/>[mem_generator.py]"]
  node_map["Network memory map<br/>[memory_mapping.py]"]
  node_layer["Layer data generator<br/>[gen_layer64.py]"]
end

subgraph group_analysis["Layout Analysis"]
  node_packing["Word packing study<br/>[word_analisys.py]"]
  node_memoryanalysis["Memory comparison<br/>[mem_analisys.py]"]
  node_packageanalysis["Package comparison<br/>[pkg_analysis.py]"]
  node_matrixanalysis["Matrix behavior<br/>[matrix_analysis.py]"]
  node_stack["Stack simulation<br/>[stack_analysis.py]"]
  node_tfstack["TensorFlow stack simulation"]
end

node_user(("Model developer"))

node_user -->|"trains and quantizes"| node_quant
node_user -->|"exports model"| node_export
node_user -->|"configures shape"| node_map
node_arandu -.->|"routes to"| node_core
node_core -.->|"coordinates"| node_control
node_core -.->|"dispatches"| node_npu8
node_core -.->|"dispatches"| node_npu32
node_control -.->|"controls"| node_fsm
node_npu8 -.->|"computes with"| node_neuron8
node_npu32 -.->|"computes with"| node_neuron32
node_neuron8 -.->|"multiplies with"| node_mac
node_neuron8 -.->|"requantizes with"| node_requant
node_neuron32 -.->|"adds with"| node_fpadd
node_core -.->|"accesses"| node_memory
node_memory -.->|"stores activations"| node_activations
node_memory -.->|"stores weights"| node_weights
node_memory -.->|"uses map"| node_metadata
node_memory -.->|"uses macro"| node_sram
node_memory -.->|"interfaces with"| node_dram
node_quant -.->|"provides model weights"| node_export
node_export -.->|"prepares weight data"| node_weights
node_map -.->|"describes dimensions"| node_metadata
node_layer -.->|"generates sample data"| node_export

click node_arandu "https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu.sv"
click node_core "https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu_core.sv"
click node_control "https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu_ctrl.sv"
click node_fsm "https://github.com/lucas-farimart/arandu/blob/main/rtl/fsm_controller.sv"
click node_npu8 "https://github.com/lucas-farimart/arandu/blob/main/rtl/npu_int8.sv"
click node_npu32 "https://github.com/lucas-farimart/arandu/blob/main/rtl/npu_fp32.sv"
click node_neuron8 "https://github.com/lucas-farimart/arandu/blob/main/rtl/neuron_int8.sv"
click node_neuron32 "https://github.com/lucas-farimart/arandu/blob/main/rtl/neuron_fp32.sv"
click node_requant "https://github.com/lucas-farimart/arandu/blob/main/rtl/requant_unit.sv"
click node_mac "https://github.com/lucas-farimart/arandu/blob/main/rtl/booth_radix4.sv"
click node_fpadd "https://github.com/lucas-farimart/arandu/blob/main/rtl/fp32_add.sv"
click node_memory "https://github.com/lucas-farimart/arandu/blob/main/rtl/sram_subsystem.sv"
click node_activations "https://github.com/lucas-farimart/arandu/blob/main/rtl/mem_actvs.sv"
click node_weights "https://github.com/lucas-farimart/arandu/blob/main/rtl/mem_weights.sv"
click node_metadata "https://github.com/lucas-farimart/arandu/blob/main/rtl/metadata_map.sv"
click node_dram "https://github.com/lucas-farimart/arandu/blob/main/rtl/dram_controller.sv"
click node_sram "https://github.com/lucas-farimart/arandu/blob/main/rtl/sram_32x512_1rw.v"
click node_quant "https://github.com/lucas-farimart/arandu/blob/main/software/quant_tflite.py"
click node_export "https://github.com/lucas-farimart/arandu/blob/main/data_mem/mem_generator.py"
click node_map "https://github.com/lucas-farimart/arandu/blob/main/data_mem/memory_mapping.py"
click node_layer "https://github.com/lucas-farimart/arandu/blob/main/data_mem/gen_layer64.py"
click node_packing "https://github.com/lucas-farimart/arandu/blob/main/data_mem/word_analisys.py"
click node_memoryanalysis "https://github.com/lucas-farimart/arandu/blob/main/data_mem/mem_analisys.py"
click node_packageanalysis "https://github.com/lucas-farimart/arandu/blob/main/software/pkg_analysis.py"
click node_matrixanalysis "https://github.com/lucas-farimart/arandu/blob/main/software/matrix_analysis.py"
click node_stack "https://github.com/lucas-farimart/arandu/blob/main/software/stack_analysis.py"
click node_tfstack "https://github.com/lucas-farimart/arandu/blob/main/software/tensorflow_stack.py"

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_arandu,node_core,node_control,node_fsm,node_npu8,node_npu32,node_neuron8,node_neuron32,node_requant,node_mac,node_fpadd toneBlue
class node_memory,node_activations,node_weights,node_metadata,node_dram,node_sram toneAmber
class node_quant,node_export,node_map,node_layer toneMint
class node_packing,node_memoryanalysis,node_packageanalysis,node_matrixanalysis,node_stack,node_tfstack toneRose
class node_user toneIndigo
```

## Components

### Accelerator RTL

- [Arandu top](https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu.sv): `rtl/arandu.sv`
- [Accelerator core](https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu_core.sv): `rtl/arandu_core.sv`
- [Control logic](https://github.com/lucas-farimart/arandu/blob/main/rtl/arandu_ctrl.sv): `rtl/arandu_ctrl.sv`
- [FSM controller](https://github.com/lucas-farimart/arandu/blob/main/rtl/fsm_controller.sv): `rtl/fsm_controller.sv`
- [INT8 NPU](https://github.com/lucas-farimart/arandu/blob/main/rtl/npu_int8.sv): `rtl/npu_int8.sv`
- [FP32 NPU](https://github.com/lucas-farimart/arandu/blob/main/rtl/npu_fp32.sv): `rtl/npu_fp32.sv`
- [INT8 neuron](https://github.com/lucas-farimart/arandu/blob/main/rtl/neuron_int8.sv): `rtl/neuron_int8.sv`
- [FP32 neuron](https://github.com/lucas-farimart/arandu/blob/main/rtl/neuron_fp32.sv): `rtl/neuron_fp32.sv`
- [Requantization](https://github.com/lucas-farimart/arandu/blob/main/rtl/requant_unit.sv): `rtl/requant_unit.sv`
- [Booth multiplier](https://github.com/lucas-farimart/arandu/blob/main/rtl/booth_radix4.sv): `rtl/booth_radix4.sv`
- [FP32 adder](https://github.com/lucas-farimart/arandu/blob/main/rtl/fp32_add.sv): `rtl/fp32_add.sv`

### On-chip Memory

- [SRAM subsystem](https://github.com/lucas-farimart/arandu/blob/main/rtl/sram_subsystem.sv): `rtl/sram_subsystem.sv`
- [Activation SRAM](https://github.com/lucas-farimart/arandu/blob/main/rtl/mem_actvs.sv): `rtl/mem_actvs.sv`
- [Weight SRAM](https://github.com/lucas-farimart/arandu/blob/main/rtl/mem_weights.sv): `rtl/mem_weights.sv`
- [Metadata map](https://github.com/lucas-farimart/arandu/blob/main/rtl/metadata_map.sv): `rtl/metadata_map.sv`
- [DRAM controller](https://github.com/lucas-farimart/arandu/blob/main/rtl/dram_controller.sv): `rtl/dram_controller.sv`
- [SRAM macro](https://github.com/lucas-farimart/arandu/blob/main/rtl/sram_32x512_1rw.v): `rtl/sram_32x512_1rw.v`

### Model and Data Preparation

- [TFLite quantization](https://github.com/lucas-farimart/arandu/blob/main/software/quant_tflite.py): `software/quant_tflite.py`
- [Model memory export](https://github.com/lucas-farimart/arandu/blob/main/data_mem/mem_generator.py): `data_mem/mem_generator.py`
- [Network memory map](https://github.com/lucas-farimart/arandu/blob/main/data_mem/memory_mapping.py): `data_mem/memory_mapping.py`
- [Layer data generator](https://github.com/lucas-farimart/arandu/blob/main/data_mem/gen_layer64.py): `data_mem/gen_layer64.py`

### Layout Analysis

- [Word packing study](https://github.com/lucas-farimart/arandu/blob/main/data_mem/word_analisys.py): `data_mem/word_analisys.py`
- [Memory comparison](https://github.com/lucas-farimart/arandu/blob/main/data_mem/mem_analisys.py): `data_mem/mem_analisys.py`
- [Package comparison](https://github.com/lucas-farimart/arandu/blob/main/software/pkg_analysis.py): `software/pkg_analysis.py`
- [Matrix behavior](https://github.com/lucas-farimart/arandu/blob/main/software/matrix_analysis.py): `software/matrix_analysis.py`
- [Stack simulation](https://github.com/lucas-farimart/arandu/blob/main/software/stack_analysis.py): `software/stack_analysis.py`
- [TensorFlow stack simulation](https://github.com/lucas-farimart/arandu/blob/main/software/tensorflow_stack.py): `software/tensorflow_stack.py`

### Other components

- **Model developer**

## Connections

- Model developer → TFLite quantization: trains and quantizes (evidence: `software/quant_tflite.py`)
- Model developer → Model memory export: exports model (evidence: `data_mem/mem_generator.py`)
- Model developer → Network memory map: configures shape (evidence: `data_mem/memory_mapping.py`)
- Arandu top → Accelerator core: routes to (evidence: `README.md`)
- Accelerator core → Control logic: coordinates
- Accelerator core → INT8 NPU: dispatches
- Accelerator core → FP32 NPU: dispatches
- Control logic → FSM controller: controls
- INT8 NPU → INT8 neuron: computes with
- FP32 NPU → FP32 neuron: computes with
- INT8 neuron → Booth multiplier: multiplies with
- INT8 neuron → Requantization: requantizes with
- FP32 neuron → FP32 adder: adds with
- Accelerator core → SRAM subsystem: accesses
- SRAM subsystem → Activation SRAM: stores activations
- SRAM subsystem → Weight SRAM: stores weights
- SRAM subsystem → Metadata map: uses map
- SRAM subsystem → SRAM macro: uses macro
- SRAM subsystem → DRAM controller: interfaces with
- TFLite quantization → Model memory export: provides model weights
- Model memory export → Weight SRAM: prepares weight data
- Network memory map → Metadata map: describes dimensions
- Layer data generator → Model memory export: generates sample data