# pynqpanthers/fractal-accelerator-rtl architecture

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

- Interactive diagram: https://gitdiagram.com/pynqpanthers/fractal-accelerator-rtl
- Repository: https://github.com/pynqpanthers/fractal-accelerator-rtl

## Overview

PYNQZOOM is an RTL fractal-rendering accelerator: the processing system configures a render and starts it, then programmable logic schedules work, computes pixels, tests uniform regions, stores the frame, and writes completed sixteenths to DDR. The graph reflects the README’s documented architecture and workflow; the RTL modules themselves were not sampled, so relationships are cited to that documentation rather than inferred from unseen calls. It shows the two design variants and their distinct precision/core-count tradeoff.

Main entry points: [`hdl/dual_core/scheduler/scheduler.sv`](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/scheduler.sv) (Mariani-Silver scheduler), [`hdl/dual_core/top/per_sixteenth_engine.sv`](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/per_sixteenth_engine.sv) (Sixteenth engine), [`hdl/dual_core/control_unit/control_unit.sv`](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/control_unit/control_unit.sv) (Job control unit), [`hdl/dual_core/top/top_level.sv`](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/top_level.sv) (Top-level control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Render orchestration"]
  node_top["Top-level control<br/>[top_level.sv]"]
  node_sixteenth_controller["Sixteenth controller"]
  node_per_sixteenth_engine["Sixteenth engine"]
  node_control_unit["Job control unit<br/>[control_unit.sv]"]
  node_job_queue["Job queue<br/>[job_queue.sv]"]
  node_complete_queue["Completion queue<br/>[complete_queue.sv]"]
end

subgraph group_scheduling["Work scheduling"]
  node_scheduler["Mariani-Silver scheduler<br/>[scheduler.sv]"]
  node_border_generator["Border pixel generator"]
  node_scheduler_stack["Scheduler stack<br/>[scheduler_stack.sv]"]
  node_comparator["Border comparator<br/>[comparator.sv]"]
end

subgraph group_compute["Pixel computation"]
  node_cluster["Core cluster<br/>[cluster.sv]"]
  node_worker_core["Iterator core<br/>[core_top.sv]"]
end

subgraph group_frame_storage["Frame storage and output"]
  node_colour_bram[("Colour frame buffer<br/>[colour_bram.sv]")]
  node_state_bram[("Scheduler state memory<br/>[state_bram.sv]")]
  node_tile_table[("Tile metadata<br/>[tile_table.sv]")]
  node_dram_writeback["DDR writeback<br/>[bram_to_dram.sv]"]
  node_axi_hp["AXI-HP master"]
end

subgraph group_design_variants["Design variants"]
  node_dual_core_variant["Dual-core variant<br/>[top_level.sv]"]
  node_write_arbiter["AXI write arbiter<br/>[axi_wr_arbiter.sv]"]
  node_dual_precision_variant["Dual-precision variant<br/>[top_level.sv]"]
  node_wide_multiplier["Wide multiply manager"]
end

node_ps(("Processing system"))
node_ddr[("DDR memory")]

node_ps -->|"configures and starts"| node_top
node_top -->|"sequences frames"| node_sixteenth_controller
node_sixteenth_controller -->|"runs sixteenths"| node_per_sixteenth_engine
node_per_sixteenth_engine -->|"schedules pixels"| node_scheduler
node_scheduler -->|"requests border pixels"| node_border_generator
node_scheduler -->|"manages quad-tree"| node_scheduler_stack
node_scheduler -->|"dispatches jobs"| node_control_unit
node_control_unit -->|"queues jobs"| node_job_queue
node_control_unit -->|"arbitrates work"| node_cluster
node_cluster -->|"assigns pixels"| node_worker_core
node_worker_core -->|"returns results"| node_complete_queue
node_complete_queue -->|"feeds border results"| node_comparator
node_comparator -->|"reports uniformity"| node_scheduler
node_per_sixteenth_engine -->|"stores frame pixels"| node_colour_bram
node_scheduler -->|"uses scheduler state"| node_state_bram
node_scheduler -->|"uses tile metadata"| node_tile_table
node_per_sixteenth_engine -->|"streams completed frame"| node_dram_writeback
node_dram_writeback -->|"writes over AXI-HP"| node_axi_hp
node_axi_hp -->|"writes frame data"| node_ddr
node_dual_core_variant -->|"merges engine writes"| node_write_arbiter
node_dual_precision_variant -->|"supports wide mode"| node_wide_multiplier

click node_top "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/top_level.sv"
click node_sixteenth_controller "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/sixteenth_controller.sv"
click node_per_sixteenth_engine "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/per_sixteenth_engine.sv"
click node_scheduler "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/scheduler.sv"
click node_border_generator "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/border_pixel_generator.sv"
click node_scheduler_stack "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/scheduler_stack.sv"
click node_control_unit "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/control_unit/control_unit.sv"
click node_job_queue "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/queues/job_queue.sv"
click node_cluster "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/control_unit/cluster/cluster.sv"
click node_worker_core "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/worker_core/core_top.sv"
click node_comparator "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/comparator/comparator.sv"
click node_complete_queue "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/queues/complete_queue.sv"
click node_colour_bram "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/colour_bram.sv"
click node_state_bram "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/state_bram.sv"
click node_tile_table "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/tile_table.sv"
click node_dram_writeback "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/bram_to_dram.sv"
click node_axi_hp "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/axi/axi_hp_master_wrap.sv"
click node_dual_core_variant "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/top_level.sv"
click node_write_arbiter "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/axi/axi_wr_arbiter.sv"
click node_dual_precision_variant "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_precision/top/top_level.sv"
click node_wide_multiplier "https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_precision/worker_core/multiply_manager.sv"

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_top,node_sixteenth_controller,node_per_sixteenth_engine,node_control_unit,node_job_queue,node_complete_queue toneBlue
class node_scheduler,node_border_generator,node_scheduler_stack,node_comparator,node_ddr toneAmber
class node_cluster,node_worker_core toneMint
class node_colour_bram,node_state_bram,node_tile_table,node_dram_writeback,node_axi_hp toneRose
class node_dual_core_variant,node_write_arbiter,node_dual_precision_variant,node_wide_multiplier,node_ps toneIndigo
```

## Components

### Render orchestration

- [Top-level control](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/top_level.sv): `hdl/dual_core/top/top_level.sv`
- [Sixteenth controller](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/sixteenth_controller.sv): `hdl/dual_core/top/sixteenth_controller.sv`
- [Sixteenth engine](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/per_sixteenth_engine.sv): `hdl/dual_core/top/per_sixteenth_engine.sv`
- [Job control unit](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/control_unit/control_unit.sv): `hdl/dual_core/control_unit/control_unit.sv`
- [Job queue](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/queues/job_queue.sv): `hdl/dual_core/queues/job_queue.sv`
- [Completion queue](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/queues/complete_queue.sv): `hdl/dual_core/queues/complete_queue.sv`

### Work scheduling

- [Mariani-Silver scheduler](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/scheduler.sv): `hdl/dual_core/scheduler/scheduler.sv`
- [Border pixel generator](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/border_pixel_generator.sv): `hdl/dual_core/scheduler/border_pixel_generator.sv`
- [Scheduler stack](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/scheduler/scheduler_stack.sv): `hdl/dual_core/scheduler/scheduler_stack.sv`
- [Border comparator](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/comparator/comparator.sv): `hdl/dual_core/comparator/comparator.sv`

### Pixel computation

- [Core cluster](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/control_unit/cluster/cluster.sv): `hdl/dual_core/control_unit/cluster/cluster.sv`
- [Iterator core](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/worker_core/core_top.sv): `hdl/dual_core/worker_core/core_top.sv`

### Frame storage and output

- [Colour frame buffer](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/colour_bram.sv): `hdl/dual_core/memory/colour_bram.sv`
- [Scheduler state memory](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/state_bram.sv): `hdl/dual_core/memory/state_bram.sv`
- [Tile metadata](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/tile_table.sv): `hdl/dual_core/memory/tile_table.sv`
- [DDR writeback](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/memory/bram_to_dram.sv): `hdl/dual_core/memory/bram_to_dram.sv`
- [AXI-HP master](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/axi/axi_hp_master_wrap.sv): `hdl/dual_core/axi/axi_hp_master_wrap.sv`

### Design variants

- [Dual-core variant](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/top/top_level.sv): `hdl/dual_core/top/top_level.sv`
- [AXI write arbiter](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_core/axi/axi_wr_arbiter.sv): `hdl/dual_core/axi/axi_wr_arbiter.sv`
- [Dual-precision variant](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_precision/top/top_level.sv): `hdl/dual_precision/top/top_level.sv`
- [Wide multiply manager](https://github.com/pynqpanthers/fractal-accelerator-rtl/blob/main/hdl/dual_precision/worker_core/multiply_manager.sv): `hdl/dual_precision/worker_core/multiply_manager.sv`

### Other components

- **Processing system**
- **DDR memory**

## Connections

- Processing system → Top-level control: configures and starts (evidence: `README.md`)
- Top-level control → Sixteenth controller: sequences frames (evidence: `README.md`)
- Sixteenth controller → Sixteenth engine: runs sixteenths (evidence: `README.md`)
- Sixteenth engine → Mariani-Silver scheduler: schedules pixels (evidence: `README.md`)
- Mariani-Silver scheduler → Border pixel generator: requests border pixels (evidence: `README.md`)
- Mariani-Silver scheduler → Scheduler stack: manages quad-tree (evidence: `README.md`)
- Mariani-Silver scheduler → Job control unit: dispatches jobs (evidence: `README.md`)
- Job control unit → Job queue: queues jobs (evidence: `README.md`)
- Job control unit → Core cluster: arbitrates work (evidence: `README.md`)
- Core cluster → Iterator core: assigns pixels (evidence: `README.md`)
- Iterator core → Completion queue: returns results (evidence: `README.md`)
- Completion queue → Border comparator: feeds border results (evidence: `README.md`)
- Border comparator → Mariani-Silver scheduler: reports uniformity (evidence: `README.md`)
- Sixteenth engine → Colour frame buffer: stores frame pixels (evidence: `README.md`)
- Mariani-Silver scheduler → Scheduler state memory: uses scheduler state (evidence: `README.md`)
- Mariani-Silver scheduler → Tile metadata: uses tile metadata (evidence: `README.md`)
- Sixteenth engine → DDR writeback: streams completed frame (evidence: `README.md`)
- DDR writeback → AXI-HP master: writes over AXI-HP (evidence: `README.md`)
- AXI-HP master → DDR memory: writes frame data (evidence: `README.md`)
- Dual-core variant → AXI write arbiter: merges engine writes (evidence: `README.md`)
- Dual-precision variant → Wide multiply manager: supports wide mode (evidence: `README.md`)