# vca-epfl/fsa architecture

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

- Interactive diagram: https://gitdiagram.com/vca-epfl/fsa
- Repository: https://github.com/vca-epfl/fsa

## Overview

FSA is a FlashAttention accelerator implemented as a single systolic array, with a Python API that schedules attention work and runs it on Verilator or an XDMA-connected FPGA. The principal workflow constructs tiled attention instructions, transfers tensors and instructions to an execution engine, runs DMA and matrix operations in hardware, and retrieves the output for optional comparison with Torch or the Python reference. The README documents both TileLink and direct AXI4 integration. Hardware links reflect the documented top-level architecture and sampled module responsibilities; unsampled subsystem wiring is not expanded.

Main entry points: [`python/main.py`](https://github.com/vca-epfl/fsa/blob/main/python/main.py) (Attention runner), [`src/main/scala/fsa/frontend/Decoder.scala`](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/frontend/Decoder.scala) (Instruction decoder), [`src/main/scala/fsa/MatrixEngineController.scala`](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/MatrixEngineController.scala) (Matrix controller), [`src/main/scala/fsa/sa/SystolicArray.scala`](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/SystolicArray.scala) (Systolic array)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python workflow"]
  node_main["Attention runner<br/>[main.py]"]
  node_kernel["Attention kernel<br/>[kernel.py]"]
  node_engine["Execution engines<br/>[engine.py]"]
  node_tensor["Tensor model<br/>[tensor.py]"]
  node_reference["Reference attention<br/>[fa_ref.py]"]
end

subgraph group_frontend["Instruction frontend"]
  node_decoder["Instruction decoder<br/>[Decoder.scala]"]
  node_isa["Instruction formats<br/>[ISA.scala]"]
  node_plan["Execution plans"]
  node_control["Matrix controller"]
end

subgraph group_compute["Attention compute"]
  node_array["Systolic array"]
  node_pe["Processing elements<br/>[PE.scala]"]
  node_cmp["Compare units<br/>[CMP.scala]"]
  node_acc["Accumulator<br/>[Accumulator.scala]"]
  node_arithmetic["FP arithmetic"]
end

subgraph group_memory["Data movement"]
  node_dma["DMA controller<br/>[DMA.scala]"]
  node_queues["Load/store queues<br/>[LSQ.scala]"]
  node_sram["Banked SRAM<br/>[BankedSRAM.scala]"]
end

subgraph group_integration["Simulation and integration"]
  node_top["FSA top<br/>[AXI4FSA.scala]"]
  node_verilator["Verilator simulator<br/>[engine.py]"]
  node_fpga["FPGA engine<br/>[engine.py]"]
end

node_user(("Caller"))
node_xdma["XDMA devices"]
node_memory_ext[("Backing memory")]
node_torch["PyTorch reference"]

node_user -->|"runs"| node_main
node_main -->|"builds kernel"| node_kernel
node_main -->|"converts tensors"| node_tensor
node_main -->|"executes kernel"| node_engine
node_main -.->|"compares results"| node_reference
node_main -.->|"compares results"| node_torch
node_kernel -->|"provides instructions"| node_engine
node_engine -->|"selects simulator"| node_verilator
node_engine -->|"selects FPGA"| node_fpga
node_verilator -->|"runs RTL"| node_top
node_fpga -->|"transfers data"| node_xdma
node_fpga -->|"controls device"| node_top
node_top -->|"dispatches instructions"| node_decoder
node_decoder -->|"decodes formats"| node_isa
node_decoder -->|"dispatches matrix ops"| node_control
node_decoder -->|"dispatches DMA ops"| node_dma
node_control -->|"generates controls"| node_plan
node_control -->|"drives compute"| node_array
node_array -->|"composes mesh"| node_pe
node_array -->|"uses compare units"| node_cmp
node_array -->|"uses arithmetic"| node_arithmetic
node_control -->|"controls accumulation"| node_acc
node_dma -->|"issues requests"| node_queues
node_queues -->|"reads and writes"| node_sram
node_queues -->|"transfers AXI data"| node_memory_ext
node_top -->|"exposes AXI channels"| node_memory_ext
node_xdma -->|"accesses device memory"| node_memory_ext

click node_main "https://github.com/vca-epfl/fsa/blob/main/python/main.py"
click node_kernel "https://github.com/vca-epfl/fsa/blob/main/python/fsa/kernel.py"
click node_engine "https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.py"
click node_tensor "https://github.com/vca-epfl/fsa/blob/main/python/fsa/tensor.py"
click node_reference "https://github.com/vca-epfl/fsa/blob/main/python/fa_ref.py"
click node_top "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/AXI4FSA.scala"
click node_decoder "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/frontend/Decoder.scala"
click node_isa "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/isa/ISA.scala"
click node_plan "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/ExecutionPlan.scala"
click node_control "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/MatrixEngineController.scala"
click node_dma "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/dma/DMA.scala"
click node_queues "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/dma/LSQ.scala"
click node_sram "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/BankedSRAM.scala"
click node_array "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/SystolicArray.scala"
click node_pe "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/PE.scala"
click node_cmp "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/CMP.scala"
click node_acc "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/Accumulator.scala"
click node_arithmetic "https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/arithmetic/FPArithmeticImpl.scala"
click node_verilator "https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.py"
click node_fpga "https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.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_main,node_kernel,node_engine,node_tensor,node_reference toneBlue
class node_decoder,node_isa,node_plan,node_control,node_memory_ext toneAmber
class node_array,node_pe,node_cmp,node_acc,node_arithmetic toneMint
class node_dma,node_queues,node_sram toneRose
class node_top,node_verilator,node_fpga,node_user,node_xdma,node_torch toneIndigo
```

## Components

### Python workflow

- [Attention runner](https://github.com/vca-epfl/fsa/blob/main/python/main.py): `python/main.py`
- [Attention kernel](https://github.com/vca-epfl/fsa/blob/main/python/fsa/kernel.py): `python/fsa/kernel.py`
- [Execution engines](https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.py): `python/fsa/engine.py`
- [Tensor model](https://github.com/vca-epfl/fsa/blob/main/python/fsa/tensor.py): `python/fsa/tensor.py`
- [Reference attention](https://github.com/vca-epfl/fsa/blob/main/python/fa_ref.py): `python/fa_ref.py`

### Instruction frontend

- [Instruction decoder](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/frontend/Decoder.scala): `src/main/scala/fsa/frontend/Decoder.scala`
- [Instruction formats](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/isa/ISA.scala): `src/main/scala/fsa/isa/ISA.scala`
- [Execution plans](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/ExecutionPlan.scala): `src/main/scala/fsa/ExecutionPlan.scala`
- [Matrix controller](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/MatrixEngineController.scala): `src/main/scala/fsa/MatrixEngineController.scala`

### Attention compute

- [Systolic array](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/SystolicArray.scala): `src/main/scala/fsa/sa/SystolicArray.scala`
- [Processing elements](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/PE.scala): `src/main/scala/fsa/sa/PE.scala`
- [Compare units](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/sa/CMP.scala): `src/main/scala/fsa/sa/CMP.scala`
- [Accumulator](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/Accumulator.scala): `src/main/scala/fsa/Accumulator.scala`
- [FP arithmetic](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/arithmetic/FPArithmeticImpl.scala): `src/main/scala/fsa/arithmetic/FPArithmeticImpl.scala`

### Data movement

- [DMA controller](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/dma/DMA.scala): `src/main/scala/fsa/dma/DMA.scala`
- [Load/store queues](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/dma/LSQ.scala): `src/main/scala/fsa/dma/LSQ.scala`
- [Banked SRAM](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/BankedSRAM.scala): `src/main/scala/fsa/BankedSRAM.scala`

### Simulation and integration

- [FSA top](https://github.com/vca-epfl/fsa/blob/main/src/main/scala/fsa/AXI4FSA.scala): `src/main/scala/fsa/AXI4FSA.scala`
- [Verilator simulator](https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.py): `python/fsa/engine.py`
- [FPGA engine](https://github.com/vca-epfl/fsa/blob/main/python/fsa/engine.py): `python/fsa/engine.py`

### Other components

- **Caller**
- **XDMA devices**
- **Backing memory**
- **PyTorch reference**

## Connections

- Caller → Attention runner: runs
- Attention runner → Attention kernel: builds kernel
- Attention runner → Tensor model: converts tensors
- Attention runner → Execution engines: executes kernel
- Attention runner → Reference attention: compares results
- Attention runner → PyTorch reference: compares results
- Attention kernel → Execution engines: provides instructions
- Execution engines → Verilator simulator: selects simulator
- Execution engines → FPGA engine: selects FPGA
- Verilator simulator → FSA top: runs RTL
- FPGA engine → XDMA devices: transfers data
- FPGA engine → FSA top: controls device
- FSA top → Instruction decoder: dispatches instructions
- Instruction decoder → Instruction formats: decodes formats
- Instruction decoder → Matrix controller: dispatches matrix ops
- Instruction decoder → DMA controller: dispatches DMA ops
- Matrix controller → Execution plans: generates controls
- Matrix controller → Systolic array: drives compute
- Systolic array → Processing elements: composes mesh
- Systolic array → Compare units: uses compare units
- Systolic array → FP arithmetic: uses arithmetic
- Matrix controller → Accumulator: controls accumulation
- DMA controller → Load/store queues: issues requests
- Load/store queues → Banked SRAM: reads and writes
- Load/store queues → Backing memory: transfers AXI data
- FSA top → Backing memory: exposes AXI channels
- XDMA devices → Backing memory: accesses device memory