# samiul000/vfpga-s3 architecture

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

- Interactive diagram: https://gitdiagram.com/samiul000/vfpga-s3
- Repository: https://github.com/samiul000/vfpga-s3

## Overview

VFPGA-S3 combines an ESP32-hosted software FPGA with an HDL-to-fabric workflow, an integrated RV32I soft CPU, and documented host-side simulation and educational ASIC-style physical design. The firmware entry point parses the embedded user design, builds and maps a netlist, loads the configuration into the fabric, and evaluates combinational or sequential outputs. The README documents additional host tools and Verilog emission. Some implementation paths for those capabilities were not sampled, so their nodes use exact enclosing directories and uncertain links are omitted.

Main entry points: [`src/main.cpp`](https://github.com/samiul000/vfpga-s3/blob/main/src/main.cpp) (Firmware workflow), [`tools/cli/main.cpp`](https://github.com/samiul000/vfpga-s3/blob/main/tools/cli/main.cpp) (Host CLI), [`src/vfpga/vfpga_core.cpp`](https://github.com/samiul000/vfpga-s3/blob/main/src/vfpga/vfpga_core.cpp) (Fabric core), [`src/riscv/riscv_soc_demo.cpp`](https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_soc_demo.cpp) (Virtual SoC demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hdl["HDL workflow"]
  node_firmware["Firmware workflow<br/>[main.cpp]"]
  node_embedded["Embedded HDL<br/>[user_design.h]"]
  node_lexer["HDL lexer<br/>[lexer.cpp]"]
  node_parser["HDL parser<br/>[parser.cpp]"]
  node_netlist["Netlist builder<br/>[netlist.cpp]"]
  node_mapper["LUT mapper<br/>[mapper.cpp]"]
  node_verilog["Verilog emitter<br/>[verilog_emit.cpp]"]
end

subgraph group_fabric["Virtual fabric"]
  node_core["Fabric core<br/>[vfpga_core.cpp]"]
  node_fabric_blocks["Logic and resources"]
  node_routing["Routing fabric<br/>[vfpga_pie.cpp]"]
  node_engine["Execution modes"]
  node_board["Board profile<br/>[board_profile.cpp]"]
  node_gpio["GPIO bridge<br/>[gpio_bridge.cpp]"]
end

subgraph group_soc["RISC-V SoC"]
  node_cpu["RV32I CPU<br/>[riscv_cpu.cpp]"]
  node_memory["CPU memory<br/>[riscv_memory.cpp]"]
  node_soc_demo["Virtual SoC demo<br/>[riscv_soc_demo.cpp]"]
  node_demo["Built-in demos<br/>[demo_run.cpp]"]
end

subgraph group_host["Host design tools"]
  node_cli["Host CLI<br/>[main.cpp]"]
  node_simulator["Host simulator<br/>[sim.cpp]"]
  node_testbench["Testbench execution<br/>[tb_exec.cpp]"]
  node_waveform["Waveform output<br/>[vcd.cpp]"]
  node_physical["Physical design"]
end

node_user(("Design author"))

node_user -->|"edits"| node_embedded
node_embedded -->|"loaded by"| node_firmware
node_firmware -->|"tokenizes"| node_lexer
node_firmware -->|"parses"| node_parser
node_firmware -->|"builds"| node_netlist
node_firmware -->|"maps"| node_mapper
node_firmware -->|"loads and evaluates"| node_core
node_netlist -->|"consumes AST"| node_parser
node_mapper -->|"maps netlist"| node_netlist
node_core -->|"uses routing"| node_routing
node_core -->|"evaluates fabric"| node_fabric_blocks
node_core -.->|"evaluates with"| node_engine
node_firmware -->|"detects board"| node_board
node_firmware -->|"initializes bridge"| node_gpio
node_firmware -->|"runs demos"| node_demo
node_demo -->|"runs demo"| node_soc_demo
node_soc_demo -->|"uses CPU"| node_cpu
node_soc_demo -->|"uses fabric"| node_core
node_cpu -->|"uses memory"| node_memory
node_user -->|"runs commands"| node_cli
node_cli -->|"loads HDL"| node_parser
node_cli -->|"maps design"| node_mapper
node_cli -->|"simulates design"| node_simulator
node_cli -->|"verifies design"| node_testbench
node_testbench -->|"executes on"| node_simulator
node_cli -->|"exports waveform"| node_waveform
node_cli -->|"runs physical flow"| node_physical
node_user -->|"can emit as"| node_verilog

click node_firmware "https://github.com/samiul000/vfpga-s3/blob/main/src/main.cpp"
click node_embedded "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/user_design.h"
click node_lexer "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/lexer.cpp"
click node_parser "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/parser.cpp"
click node_netlist "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/netlist.cpp"
click node_mapper "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/mapper.cpp"
click node_verilog "https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/verilog_emit.cpp"
click node_core "https://github.com/samiul000/vfpga-s3/blob/main/src/vfpga/vfpga_core.cpp"
click node_fabric_blocks "https://github.com/samiul000/vfpga-s3/tree/main/src/vfpga"
click node_routing "https://github.com/samiul000/vfpga-s3/blob/main/src/vfpga/vfpga_pie.cpp"
click node_engine "https://github.com/samiul000/vfpga-s3/blob/main/src/engine/execution_engine.cpp"
click node_board "https://github.com/samiul000/vfpga-s3/blob/main/src/io/board_profile.cpp"
click node_gpio "https://github.com/samiul000/vfpga-s3/blob/main/src/io/gpio_bridge.cpp"
click node_cpu "https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_cpu.cpp"
click node_memory "https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_memory.cpp"
click node_soc_demo "https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_soc_demo.cpp"
click node_demo "https://github.com/samiul000/vfpga-s3/blob/main/src/demo_run.cpp"
click node_cli "https://github.com/samiul000/vfpga-s3/blob/main/tools/cli/main.cpp"
click node_simulator "https://github.com/samiul000/vfpga-s3/blob/main/host_test/simulator/sim.cpp"
click node_testbench "https://github.com/samiul000/vfpga-s3/blob/main/host_test/testbench/tb_exec.cpp"
click node_waveform "https://github.com/samiul000/vfpga-s3/blob/main/host_test/waveform/vcd.cpp"
click node_physical "https://github.com/samiul000/vfpga-s3/blob/main/host_test/physical/physical_design.cpp"

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_firmware,node_embedded,node_lexer,node_parser,node_netlist,node_mapper,node_verilog toneBlue
class node_core,node_fabric_blocks,node_routing,node_engine,node_board,node_gpio toneAmber
class node_cpu,node_memory,node_soc_demo,node_demo toneMint
class node_cli,node_simulator,node_testbench,node_waveform,node_physical toneRose
class node_user toneIndigo
```

## Components

### HDL workflow

- [Firmware workflow](https://github.com/samiul000/vfpga-s3/blob/main/src/main.cpp): `src/main.cpp`
- [Embedded HDL](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/user_design.h): `src/hdl/user_design.h`
- [HDL lexer](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/lexer.cpp): `src/hdl/lexer.cpp`
- [HDL parser](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/parser.cpp): `src/hdl/parser.cpp`
- [Netlist builder](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/netlist.cpp): `src/hdl/netlist.cpp`
- [LUT mapper](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/mapper.cpp): `src/hdl/mapper.cpp`
- [Verilog emitter](https://github.com/samiul000/vfpga-s3/blob/main/src/hdl/verilog_emit.cpp): `src/hdl/verilog_emit.cpp`

### Virtual fabric

- [Fabric core](https://github.com/samiul000/vfpga-s3/blob/main/src/vfpga/vfpga_core.cpp): `src/vfpga/vfpga_core.cpp`
- [Logic and resources](https://github.com/samiul000/vfpga-s3/tree/main/src/vfpga): `src/vfpga`
- [Routing fabric](https://github.com/samiul000/vfpga-s3/blob/main/src/vfpga/vfpga_pie.cpp): `src/vfpga/vfpga_pie.cpp`
- [Execution modes](https://github.com/samiul000/vfpga-s3/blob/main/src/engine/execution_engine.cpp): `src/engine/execution_engine.cpp`
- [Board profile](https://github.com/samiul000/vfpga-s3/blob/main/src/io/board_profile.cpp): `src/io/board_profile.cpp`
- [GPIO bridge](https://github.com/samiul000/vfpga-s3/blob/main/src/io/gpio_bridge.cpp): `src/io/gpio_bridge.cpp`

### RISC-V SoC

- [RV32I CPU](https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_cpu.cpp): `src/riscv/riscv_cpu.cpp`
- [CPU memory](https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_memory.cpp): `src/riscv/riscv_memory.cpp`
- [Virtual SoC demo](https://github.com/samiul000/vfpga-s3/blob/main/src/riscv/riscv_soc_demo.cpp): `src/riscv/riscv_soc_demo.cpp`
- [Built-in demos](https://github.com/samiul000/vfpga-s3/blob/main/src/demo_run.cpp): `src/demo_run.cpp`

### Host design tools

- [Host CLI](https://github.com/samiul000/vfpga-s3/blob/main/tools/cli/main.cpp): `tools/cli/main.cpp`
- [Host simulator](https://github.com/samiul000/vfpga-s3/blob/main/host_test/simulator/sim.cpp): `host_test/simulator/sim.cpp`
- [Testbench execution](https://github.com/samiul000/vfpga-s3/blob/main/host_test/testbench/tb_exec.cpp): `host_test/testbench/tb_exec.cpp`
- [Waveform output](https://github.com/samiul000/vfpga-s3/blob/main/host_test/waveform/vcd.cpp): `host_test/waveform/vcd.cpp`
- [Physical design](https://github.com/samiul000/vfpga-s3/blob/main/host_test/physical/physical_design.cpp): `host_test/physical/physical_design.cpp`

### Other components

- **Design author**

## Connections

- Design author → Embedded HDL: edits
- Embedded HDL → Firmware workflow: loaded by (evidence: `src/main.cpp`)
- Firmware workflow → HDL lexer: tokenizes (evidence: `src/main.cpp`)
- Firmware workflow → HDL parser: parses (evidence: `src/main.cpp`)
- Firmware workflow → Netlist builder: builds (evidence: `src/main.cpp`)
- Firmware workflow → LUT mapper: maps (evidence: `src/main.cpp`)
- Firmware workflow → Fabric core: loads and evaluates (evidence: `src/main.cpp`)
- Netlist builder → HDL parser: consumes AST
- LUT mapper → Netlist builder: maps netlist
- Fabric core → Routing fabric: uses routing (evidence: `src/vfpga/vfpga_core.cpp`)
- Fabric core → Logic and resources: evaluates fabric (evidence: `src/vfpga/vfpga_core.cpp`)
- Fabric core → Execution modes: evaluates with
- Firmware workflow → Board profile: detects board (evidence: `src/main.cpp`)
- Firmware workflow → GPIO bridge: initializes bridge (evidence: `src/main.cpp`)
- Firmware workflow → Built-in demos: runs demos (evidence: `src/main.cpp`)
- Built-in demos → Virtual SoC demo: runs demo (evidence: `src/demo_run.cpp`)
- Virtual SoC demo → RV32I CPU: uses CPU (evidence: `src/riscv/riscv_soc_demo.cpp`)
- Virtual SoC demo → Fabric core: uses fabric (evidence: `src/riscv/riscv_soc_demo.cpp`)
- RV32I CPU → CPU memory: uses memory
- Design author → Host CLI: runs commands
- Host CLI → HDL parser: loads HDL
- Host CLI → LUT mapper: maps design
- Host CLI → Host simulator: simulates design
- Host CLI → Testbench execution: verifies design
- Testbench execution → Host simulator: executes on
- Host CLI → Waveform output: exports waveform
- Host CLI → Physical design: runs physical flow
- Design author → Verilog emitter: can emit as