# galdv/cpucamp architecture

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

- Interactive diagram: https://gitdiagram.com/galdv/cpucamp
- Repository: https://github.com/galdv/cpucamp

## Overview

This repository is a Hack CPU FPGA challenge bundle: it includes a sample assembly program, assembled machine code, a converter to Intel HEX, and the documented target-system design. The user workflow is to assemble Hack code, convert it, program the FPGA, and observe execution and runtime. The tree contains no Verilog source, so hardware details below reflect README documentation, not inspected RTL; the converter is the only sampled implementation.

Main entry points: [`CPU_Garage.qar`](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar) (Hack CPU), [`python/hack_to_hex.py`](https://github.com/galdv/cpucamp/blob/main/python/hack_to_hex.py) (Hack to HEX), [`hack/rom.hack`](https://github.com/galdv/cpucamp/blob/main/hack/rom.hack) (Hack machine code), [`hex/rom.hex`](https://github.com/galdv/cpucamp/blob/main/hex/rom.hex) (Intel HEX image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_program["Program artifacts"]
  node_sample_asm["Sample assembly<br/>[rom.asm]"]
  node_machine_code["Hack machine code<br/>[rom.hack]"]
end

subgraph group_conversion["Image conversion"]
  node_converter["Hack to HEX<br/>[hack_to_hex.py]"]
  node_hex_image["Intel HEX image<br/>[rom.hex]"]
end

subgraph group_hardware["Documented FPGA system"]
  node_cpu["Hack CPU<br/>[CPU_Garage.qar]"]
  node_rom[("Instruction ROM<br/>[CPU_Garage.qar]")]
  node_ram[("Data RAM<br/>[CPU_Garage.qar]")]
  node_vga["VGA memory view<br/>[CPU_Garage.qar]"]
  node_counter["Performance counter<br/>[CPU_Garage.qar]"]
  node_seven_segment["Seven-segment display<br/>[CPU_Garage.qar]"]
end

node_assembler["Nand2Tetris assembler"]
node_programmer["FPGA programmer"]
node_screen(("Execution viewer"))

node_assembler -->|"assembles"| node_machine_code
node_converter -->|"reads"| node_machine_code
node_converter -->|"writes"| node_hex_image
node_programmer -->|"programs"| node_rom
node_rom -->|"supplies instructions"| node_cpu
node_cpu -->|"reads and writes"| node_ram
node_ram -->|"provides display data"| node_vga
node_cpu -->|"execution is timed"| node_counter
node_counter -->|"drives runtime display"| node_seven_segment
node_vga -->|"displays memory"| node_screen

click node_sample_asm "https://github.com/galdv/cpucamp/blob/main/asm/rom.asm"
click node_machine_code "https://github.com/galdv/cpucamp/blob/main/hack/rom.hack"
click node_converter "https://github.com/galdv/cpucamp/blob/main/python/hack_to_hex.py"
click node_hex_image "https://github.com/galdv/cpucamp/blob/main/hex/rom.hex"
click node_cpu "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"
click node_rom "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"
click node_ram "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"
click node_vga "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"
click node_counter "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"
click node_seven_segment "https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar"

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_sample_asm,node_machine_code,node_screen toneBlue
class node_converter,node_hex_image toneAmber
class node_cpu,node_rom,node_ram,node_vga,node_counter,node_seven_segment toneMint
class node_assembler,node_programmer toneIndigo
```

## Components

### Program artifacts

- [Sample assembly](https://github.com/galdv/cpucamp/blob/main/asm/rom.asm): `asm/rom.asm`
- [Hack machine code](https://github.com/galdv/cpucamp/blob/main/hack/rom.hack): `hack/rom.hack`

### Image conversion

- [Hack to HEX](https://github.com/galdv/cpucamp/blob/main/python/hack_to_hex.py): `python/hack_to_hex.py`
- [Intel HEX image](https://github.com/galdv/cpucamp/blob/main/hex/rom.hex): `hex/rom.hex`

### Documented FPGA system

- [Hack CPU](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`
- [Instruction ROM](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`
- [Data RAM](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`
- [VGA memory view](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`
- [Performance counter](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`
- [Seven-segment display](https://github.com/galdv/cpucamp/blob/main/CPU_Garage.qar): `CPU_Garage.qar`

### Other components

- **Nand2Tetris assembler**
- **FPGA programmer**
- **Execution viewer**

## Connections

- Nand2Tetris assembler → Hack machine code: assembles (evidence: `README.md`)
- Hack to HEX → Hack machine code: reads (evidence: `python/hack_to_hex.py`)
- Hack to HEX → Intel HEX image: writes (evidence: `python/hack_to_hex.py`)
- FPGA programmer → Instruction ROM: programs (evidence: `README.md`)
- Instruction ROM → Hack CPU: supplies instructions (evidence: `README.md`)
- Hack CPU → Data RAM: reads and writes (evidence: `README.md`)
- Data RAM → VGA memory view: provides display data (evidence: `README.md`)
- Hack CPU → Performance counter: execution is timed (evidence: `README.md`)
- Performance counter → Seven-segment display: drives runtime display (evidence: `README.md`)
- VGA memory view → Execution viewer: displays memory (evidence: `README.md`)