# gstl-itu/ubee architecture

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

- Interactive diagram: https://gitdiagram.com/gstl-itu/ubee
- Repository: https://github.com/gstl-itu/ubee

## Overview

This repository is a teaching-oriented RV32IMC emulator, assembler, and debugger; the graph focuses on the emulator subtree present in the supplied file tree. The main workflow is to assemble source or load a program, execute it on the emulated hart, then inspect or control execution through the CLI/TUI or GUI. It also includes ISA encoding/decoding, configurable devices, and a visual pipeline. Relationships are limited to those supported by the README or SOURCE INDEX; unsampled subsystem internals are represented at their source-directory path.

Main entry points: [`Emulator/rv32_emulator-main/src/dbg/session.cpp`](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/session.cpp) (Debug session), [`Emulator/rv32_emulator-main/src/main.cpp`](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/main.cpp) (CLI dispatcher), [`Emulator/rv32_emulator-main/src/asm/assembler.cpp`](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/assembler.cpp) (Assembler), [`Emulator/rv32_emulator-main/src/gui/main_window.cpp`](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/gui/main_window.cpp) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["CLI dispatcher<br/>[main.cpp]"]
end

subgraph group_assembly["Assembly tools"]
  node_assembler["Assembler<br/>[assembler.cpp]"]
  node_parser["Source parser<br/>[parser.cpp]"]
  node_completion["Editor completion<br/>[complete.cpp]"]
  node_diagnostics["Diagnostics<br/>[diag_render.cpp]"]
end

subgraph group_isa["RISC-V ISA"]
  node_encoding["Instruction encoding<br/>[encode.cpp]"]
  node_decoding["Instruction decoding<br/>[decode.cpp]"]
  node_disassembly["Disassembler<br/>[disasm.cpp]"]
  node_isa_tables["ISA definitions<br/>[isa.hpp]"]
end

subgraph group_machine["Emulated machine"]
  node_hart["Hart execution<br/>[hart.cpp]"]
  node_memory_bus["Memory and bus<br/>[bus.cpp]"]
  node_devices["Memory-mapped devices<br/>[devices.cpp]"]
  node_device_config["Machine configuration<br/>[device_config.cpp]"]
  node_memfile["Memory images<br/>[memfile.cpp]"]
end

subgraph group_debug_ui["Debugging interfaces"]
  node_session["Debug session<br/>[session.cpp]"]
  node_history["Reverse history<br/>[history.cpp]"]
  node_breakpoints["Breakpoints<br/>[breakpoints.cpp]"]
  node_pipeline["Pipeline model<br/>[pipeline.cpp]"]
  node_repl["CLI and TUI<br/>[repl.cpp]"]
  node_gui["Desktop GUI<br/>[main_window.cpp]"]
  node_pipeline_view["Pipeline panel"]
end

node_user(("Learner"))

node_user -->|"invokes"| node_main
node_main -->|"assembles"| node_assembler
node_assembler -->|"parses source"| node_parser
node_assembler -->|"encodes instructions"| node_encoding
node_assembler -->|"renders diagnostics"| node_diagnostics
node_main -->|"configures machine"| node_device_config
node_main -->|"loads images"| node_memfile
node_main -->|"executes program"| node_hart
node_main -->|"starts debugger"| node_repl
node_main -->|"decodes output"| node_decoding
node_hart -->|"decodes instructions"| node_decoding
node_hart -->|"accesses memory"| node_memory_bus
node_memory_bus -.->|"routes device access"| node_devices
node_device_config -->|"configures hart"| node_hart
node_session -->|"loads assembled code"| node_assembler
node_session -->|"controls execution"| node_hart
node_session -->|"records steps"| node_history
node_session -->|"checks stops"| node_breakpoints
node_pipeline -->|"steps session"| node_session
node_repl -->|"controls debugger"| node_session
node_gui -->|"controls debugger"| node_session
node_gui -->|"assembles editor source"| node_assembler
node_gui -->|"sets devices"| node_device_config
node_gui -->|"loads images"| node_memfile
node_gui -->|"formats instructions"| node_disassembly
node_pipeline_view -->|"renders stages"| node_pipeline
node_pipeline_view -->|"reads debugger state"| node_session
node_completion -->|"uses ISA metadata"| node_isa_tables
node_decoding -->|"matches definitions"| node_isa_tables

click node_main "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/main.cpp"
click node_assembler "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/assembler.cpp"
click node_parser "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/parser.cpp"
click node_completion "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/complete.cpp"
click node_diagnostics "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/diag_render.cpp"
click node_encoding "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/encode.cpp"
click node_decoding "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/decode.cpp"
click node_disassembly "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/disasm.cpp"
click node_isa_tables "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/isa.hpp"
click node_hart "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/hart.cpp"
click node_memory_bus "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/bus.cpp"
click node_devices "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/devices.cpp"
click node_device_config "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/device_config.cpp"
click node_memfile "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/memfile.cpp"
click node_session "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/session.cpp"
click node_history "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/history.cpp"
click node_breakpoints "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/breakpoints.cpp"
click node_pipeline "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/pipeline.cpp"
click node_repl "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/cmd/repl.cpp"
click node_gui "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/gui/main_window.cpp"
click node_pipeline_view "https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/gui/pipeline_widget.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_main toneBlue
class node_assembler,node_parser,node_completion,node_diagnostics toneAmber
class node_encoding,node_decoding,node_disassembly,node_isa_tables toneMint
class node_hart,node_memory_bus,node_devices,node_device_config,node_memfile toneRose
class node_session,node_history,node_breakpoints,node_pipeline,node_repl,node_gui,node_pipeline_view,node_user toneIndigo
```

## Components

### Application entry

- [CLI dispatcher](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/main.cpp): `Emulator/rv32_emulator-main/src/main.cpp`

### Assembly tools

- [Assembler](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/assembler.cpp): `Emulator/rv32_emulator-main/src/asm/assembler.cpp`
- [Source parser](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/parser.cpp): `Emulator/rv32_emulator-main/src/asm/parser.cpp`
- [Editor completion](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/complete.cpp): `Emulator/rv32_emulator-main/src/asm/complete.cpp`
- [Diagnostics](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/asm/diag_render.cpp): `Emulator/rv32_emulator-main/src/asm/diag_render.cpp`

### RISC-V ISA

- [Instruction encoding](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/encode.cpp): `Emulator/rv32_emulator-main/src/isa/encode.cpp`
- [Instruction decoding](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/decode.cpp): `Emulator/rv32_emulator-main/src/isa/decode.cpp`
- [Disassembler](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/disasm.cpp): `Emulator/rv32_emulator-main/src/isa/disasm.cpp`
- [ISA definitions](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/isa/isa.hpp): `Emulator/rv32_emulator-main/src/isa/isa.hpp`

### Emulated machine

- [Hart execution](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/hart.cpp): `Emulator/rv32_emulator-main/src/core/hart.cpp`
- [Memory and bus](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/bus.cpp): `Emulator/rv32_emulator-main/src/core/bus.cpp`
- [Memory-mapped devices](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/devices.cpp): `Emulator/rv32_emulator-main/src/core/devices.cpp`
- [Machine configuration](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/device_config.cpp): `Emulator/rv32_emulator-main/src/core/device_config.cpp`
- [Memory images](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/core/memfile.cpp): `Emulator/rv32_emulator-main/src/core/memfile.cpp`

### Debugging interfaces

- [Debug session](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/session.cpp): `Emulator/rv32_emulator-main/src/dbg/session.cpp`
- [Reverse history](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/history.cpp): `Emulator/rv32_emulator-main/src/dbg/history.cpp`
- [Breakpoints](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/breakpoints.cpp): `Emulator/rv32_emulator-main/src/dbg/breakpoints.cpp`
- [Pipeline model](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/dbg/pipeline.cpp): `Emulator/rv32_emulator-main/src/dbg/pipeline.cpp`
- [CLI and TUI](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/cmd/repl.cpp): `Emulator/rv32_emulator-main/src/cmd/repl.cpp`
- [Desktop GUI](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/gui/main_window.cpp): `Emulator/rv32_emulator-main/src/gui/main_window.cpp`
- [Pipeline panel](https://github.com/gstl-itu/ubee/blob/main/Emulator/rv32_emulator-main/src/gui/pipeline_widget.cpp): `Emulator/rv32_emulator-main/src/gui/pipeline_widget.cpp`

### Other components

- **Learner**

## Connections

- Learner → CLI dispatcher: invokes (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- CLI dispatcher → Assembler: assembles (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- Assembler → Source parser: parses source (evidence: `Emulator/rv32_emulator-main/src/asm/assembler.cpp`)
- Assembler → Instruction encoding: encodes instructions (evidence: `Emulator/rv32_emulator-main/src/asm/assembler.cpp`)
- Assembler → Diagnostics: renders diagnostics (evidence: `Emulator/rv32_emulator-main/src/asm/assembler.cpp`)
- CLI dispatcher → Machine configuration: configures machine (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- CLI dispatcher → Memory images: loads images (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- CLI dispatcher → Hart execution: executes program (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- CLI dispatcher → CLI and TUI: starts debugger (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- CLI dispatcher → Instruction decoding: decodes output (evidence: `Emulator/rv32_emulator-main/src/main.cpp`)
- Hart execution → Instruction decoding: decodes instructions
- Hart execution → Memory and bus: accesses memory
- Memory and bus → Memory-mapped devices: routes device access
- Machine configuration → Hart execution: configures hart
- Debug session → Assembler: loads assembled code
- Debug session → Hart execution: controls execution
- Debug session → Reverse history: records steps
- Debug session → Breakpoints: checks stops
- Pipeline model → Debug session: steps session
- CLI and TUI → Debug session: controls debugger
- Desktop GUI → Debug session: controls debugger (evidence: `Emulator/rv32_emulator-main/src/gui/main_window.cpp`)
- Desktop GUI → Assembler: assembles editor source (evidence: `Emulator/rv32_emulator-main/src/gui/main_window.cpp`)
- Desktop GUI → Machine configuration: sets devices (evidence: `Emulator/rv32_emulator-main/src/gui/main_window.cpp`)
- Desktop GUI → Memory images: loads images (evidence: `Emulator/rv32_emulator-main/src/gui/main_window.cpp`)
- Desktop GUI → Disassembler: formats instructions (evidence: `Emulator/rv32_emulator-main/src/gui/main_window.cpp`)
- Pipeline panel → Pipeline model: renders stages
- Pipeline panel → Debug session: reads debugger state
- Editor completion → ISA definitions: uses ISA metadata (evidence: `Emulator/rv32_emulator-main/src/asm/complete.cpp`)
- Instruction decoding → ISA definitions: matches definitions (evidence: `Emulator/rv32_emulator-main/src/isa/decode.cpp`)
