# freeb1e/frodo_acceleration_engine architecture

> Architecture diagram of the GitHub repository freeb1e/frodo_acceleration_engine, 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/freeb1e/frodo_acceleration_engine
- Repository: https://github.com/freeb1e/frodo_acceleration_engine

## Overview

Frodo Acceleration Engine is a Verilog/SystemVerilog accelerator simulator for FrodoKEM’s matrix and SHAKE/sampling paths, with a Python instruction-generation and reference-model layer and a C++ DPI memory bridge. The principal workflow is to generate a keygen/encapsulation/decapsulation instruction program, assemble it, run it on TEST_PLATFORM, then inspect or compare RAM results. The graph preserves the documented systolic, SHAKE/sampling, memory, and reference-analysis branches. Hardware wiring beyond the documented module roles is not established by the sampled RTL, so uncertain internal links are omitted.

Main entry points: [`vsrc/TEST_PLATFORM.sv`](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/TEST_PLATFORM.sv) (TEST_PLATFORM), [`vsrc/SYSTOLIC/systolic.sv`](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/systolic.sv) (Systolic compute), [`vsrc/SHA/sha3_ctrl.sv`](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SHA/sha3_ctrl.sv) (SHAKE controller), [`csrc/sim.cpp`](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/sim.cpp) (DPI simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Program authoring"]
  node_program["Workflow generator<br/>[program.py]"]
  node_facelib["Instruction API<br/>[face_lib.py]"]
  node_assembler["Instruction assembler<br/>[assembler.py]"]
end

subgraph group_platform["Simulation platform"]
  node_platform_top["TEST_PLATFORM<br/>[TEST_PLATFORM.sv]"]
  node_sim["DPI simulator<br/>[sim.cpp]"]
  node_init["RAM initialization<br/>[testinit.cpp]"]
  node_memory[("RAM and DPI bridge<br/>[memory.cpp]")]
  node_rambus["RAM bus<br/>[RAMBUS.sv]"]
end

subgraph group_engines["Hardware engines"]
  node_systolic["Systolic compute<br/>[systolic.sv]"]
  node_mul["Multiply datapath<br/>[mul_top.sv]"]
  node_memctrl["Array memory control<br/>[mem_ctrl_new.sv]"]
  node_transpose["Transpose path<br/>[transposition.sv]"]
  node_sha_ctrl["SHAKE controller<br/>[sha3_ctrl.sv]"]
  node_sha_core["SHA3 datapath<br/>[sha3.v]"]
  node_a_sampler["A sampler<br/>[A_sampler.sv]"]
  node_se_sampler["SE sampler<br/>[SE_sampler.sv]"]
end

subgraph group_analysis["Reference analysis"]
  node_golden["Matrix reference<br/>[goldengen.py]"]
  node_trace["SHAKE trace"]
  node_accum["Accumulation trace"]
  node_pkh["SHAKE reference<br/>[pkh.py]"]
end

node_user(("Engineer"))

node_user -->|"selects workflow"| node_program
node_program -->|"emits instructions"| node_facelib
node_facelib -->|"writes assembly"| node_assembler
node_assembler -->|"produces firmware"| node_platform_top
node_sim -->|"evaluates DUT"| node_platform_top
node_sim -->|"initializes test"| node_init
node_init -->|"loads RAM"| node_memory
node_platform_top -->|"accesses RAM"| node_rambus
node_rambus -->|"DPI memory access"| node_memory
node_platform_top -->|"dispatches compute"| node_systolic
node_systolic -->|"uses datapath"| node_mul
node_systolic -->|"controls transfers"| node_memctrl
node_systolic -->|"supports transpose"| node_transpose
node_platform_top -->|"dispatches SHAKE"| node_sha_ctrl
node_sha_ctrl -->|"runs permutation"| node_sha_core
node_sha_ctrl -->|"generates A"| node_a_sampler
node_sha_ctrl -->|"generates S/E"| node_se_sampler
node_golden -->|"provides comparison"| node_user
node_trace -->|"exports absorb trace"| node_user
node_accum -->|"reports accumulations"| node_user
node_pkh -->|"reports SHAKE state"| node_user

click node_program "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/program.py"
click node_facelib "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/face_lib.py"
click node_assembler "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/assembler.py"
click node_platform_top "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/TEST_PLATFORM.sv"
click node_sim "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/sim.cpp"
click node_init "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/testinit.cpp"
click node_memory "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/memory.cpp"
click node_rambus "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/RAMBUS.sv"
click node_systolic "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/systolic.sv"
click node_mul "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/mul_top.sv"
click node_memctrl "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/mem_ctrl_new.sv"
click node_transpose "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/transposition.sv"
click node_sha_ctrl "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SHA/sha3_ctrl.sv"
click node_sha_core "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SHA/sha3.v"
click node_a_sampler "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SAMPLER/A_sampler.sv"
click node_se_sampler "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SAMPLER/SE_sampler.sv"
click node_golden "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/goldengen.py"
click node_trace "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/trace_keccak_absorb_states.py"
click node_accum "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/bprime_s_accum_trace.py"
click node_pkh "https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/pkh.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_program,node_facelib,node_assembler toneBlue
class node_platform_top,node_sim,node_init,node_memory,node_rambus toneAmber
class node_systolic,node_mul,node_memctrl,node_transpose,node_sha_ctrl,node_sha_core,node_a_sampler,node_se_sampler toneMint
class node_golden,node_trace,node_accum,node_pkh toneRose
class node_user toneIndigo
```

## Components

### Program authoring

- [Workflow generator](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/program.py): `simdata/program.py`
- [Instruction API](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/face_lib.py): `simdata/face_lib.py`
- [Instruction assembler](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/simdata/assembler.py): `simdata/assembler.py`

### Simulation platform

- [TEST_PLATFORM](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/TEST_PLATFORM.sv): `vsrc/TEST_PLATFORM.sv`
- [DPI simulator](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/sim.cpp): `csrc/sim.cpp`
- [RAM initialization](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/testinit.cpp): `csrc/testinit.cpp`
- [RAM and DPI bridge](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/csrc/memory.cpp): `csrc/memory.cpp`
- [RAM bus](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/RAMBUS.sv): `vsrc/RAMBUS.sv`

### Hardware engines

- [Systolic compute](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/systolic.sv): `vsrc/SYSTOLIC/systolic.sv`
- [Multiply datapath](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/mul_top.sv): `vsrc/SYSTOLIC/mul_top.sv`
- [Array memory control](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/mem_ctrl_new.sv): `vsrc/SYSTOLIC/mem_ctrl_new.sv`
- [Transpose path](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SYSTOLIC/transposition.sv): `vsrc/SYSTOLIC/transposition.sv`
- [SHAKE controller](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SHA/sha3_ctrl.sv): `vsrc/SHA/sha3_ctrl.sv`
- [SHA3 datapath](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SHA/sha3.v): `vsrc/SHA/sha3.v`
- [A sampler](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SAMPLER/A_sampler.sv): `vsrc/SAMPLER/A_sampler.sv`
- [SE sampler](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/vsrc/SAMPLER/SE_sampler.sv): `vsrc/SAMPLER/SE_sampler.sv`

### Reference analysis

- [Matrix reference](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/goldengen.py): `py/goldengen.py`
- [SHAKE trace](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/trace_keccak_absorb_states.py): `py/trace_keccak_absorb_states.py`
- [Accumulation trace](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/bprime_s_accum_trace.py): `py/bprime_s_accum_trace.py`
- [SHAKE reference](https://github.com/freeb1e/frodo_acceleration_engine/blob/main/py/pkh.py): `py/pkh.py`

### Other components

- **Engineer**

## Connections

- Engineer → Workflow generator: selects workflow
- Workflow generator → Instruction API: emits instructions
- Instruction API → Instruction assembler: writes assembly
- Instruction assembler → TEST_PLATFORM: produces firmware
- DPI simulator → TEST_PLATFORM: evaluates DUT
- DPI simulator → RAM initialization: initializes test
- RAM initialization → RAM and DPI bridge: loads RAM
- TEST_PLATFORM → RAM bus: accesses RAM
- RAM bus → RAM and DPI bridge: DPI memory access
- TEST_PLATFORM → Systolic compute: dispatches compute
- Systolic compute → Multiply datapath: uses datapath
- Systolic compute → Array memory control: controls transfers
- Systolic compute → Transpose path: supports transpose
- TEST_PLATFORM → SHAKE controller: dispatches SHAKE
- SHAKE controller → SHA3 datapath: runs permutation
- SHAKE controller → A sampler: generates A
- SHAKE controller → SE sampler: generates S/E
- Matrix reference → Engineer: provides comparison
- SHAKE trace → Engineer: exports absorb trace
- Accumulation trace → Engineer: reports accumulations
- SHAKE reference → Engineer: reports SHAKE state