# umarnurmatov/sim-interpreter architecture

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

- Interactive diagram: https://gitdiagram.com/umarnurmatov/sim-interpreter
- Repository: https://github.com/umarnurmatov/sim-interpreter

## Overview

TOY-ISA is a Ruby assembler plus a C++ simulator for its ELF output. The user workflow is to assemble source into an ELF object, select a simulator execution mode, load the object, and run instructions until the exit syscall. The simulator has linear and cached interpreters plus a threaded dispatcher, backed by shared CPU state, memory, instruction decoding, and ISA definitions. The README documents the assembler’s Rice/ELFIO binding; source excerpts do not expose its internal calls, so that connection is shown only as documented.

Main entry points: [`src/sim/src/base_executor.cpp`](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/base_executor.cpp) (Base executor), [`src/main.cpp`](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/main.cpp) (CLI entry point), [`src/sim/src/interp_executor.cpp`](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/interp_executor.cpp) (Interpreter), [`src/sim/src/thread_executor.cpp`](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/thread_executor.cpp) (Thread dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assembly["Assembly"]
  node_assembler["Ruby assembler<br/>[as.rb]"]
end

subgraph group_runtime["Simulator runtime"]
  node_cli["CLI entry point<br/>[main.cpp]"]
  node_base_executor["Base executor<br/>[base_executor.cpp]"]
  node_interp["Interpreter"]
  node_threaded["Thread dispatcher"]
end

subgraph group_machine["Machine model"]
  node_cpu["CPU state<br/>[cpu_state.hpp]"]
  node_memory[("RAM<br/>[memory.hpp]")]
  node_instruction["Instruction model<br/>[instr.cpp]"]
  node_isa["ISA definitions<br/>[isa.hpp]"]
  node_bitops["Bit operations<br/>[bitops.cpp]"]
end

subgraph group_integration["ELF integration"]
  node_elf_binding["ELFIO Ruby binding<br/>[elfio_ext.cpp]"]
  node_loader["ELF loader<br/>[loader.cpp]"]
end

node_user(("Developer"))
node_asm_source["Assembly source"]
node_elf_object["ELF object"]

node_user -->|"writes"| node_asm_source
node_user -->|"runs"| node_assembler
node_asm_source -->|"assembles"| node_assembler
node_assembler -.->|"uses bindings"| node_elf_binding
node_assembler -->|"produces"| node_elf_object
node_user -->|"runs"| node_cli
node_elf_object -->|"loads input"| node_loader
node_cli -->|"calls"| node_loader
node_cli -->|"selects mode"| node_interp
node_cli -->|"selects mode"| node_threaded
node_loader -->|"loads bytes"| node_base_executor
node_base_executor -->|"uses state"| node_cpu
node_base_executor -->|"decodes"| node_instruction
node_instruction -->|"uses encoding"| node_isa
node_cpu -->|"owns"| node_memory
node_interp -->|"inherits"| node_base_executor
node_threaded -->|"inherits"| node_base_executor
node_interp -->|"calls"| node_bitops
node_threaded -->|"calls"| node_bitops
node_interp -.->|"executes on"| node_cpu
node_threaded -.->|"executes on"| node_cpu

click node_assembler "https://github.com/umarnurmatov/sim-interpreter/blob/master/as.rb"
click node_elf_binding "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/elfio_ext/elfio_ext.cpp"
click node_cli "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/main.cpp"
click node_loader "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/loader.cpp"
click node_base_executor "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/base_executor.cpp"
click node_interp "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/interp_executor.cpp"
click node_threaded "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/thread_executor.cpp"
click node_cpu "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/cpu_state.hpp"
click node_memory "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/memory.hpp"
click node_instruction "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/instr.cpp"
click node_isa "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/isa.hpp"
click node_bitops "https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/bitops.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_assembler toneBlue
class node_cli,node_base_executor,node_interp,node_threaded toneAmber
class node_cpu,node_memory,node_instruction,node_isa,node_bitops toneMint
class node_elf_binding,node_loader toneRose
class node_user,node_asm_source,node_elf_object toneIndigo
```

## Components

### Assembly

- [Ruby assembler](https://github.com/umarnurmatov/sim-interpreter/blob/master/as.rb): `as.rb`

### Simulator runtime

- [CLI entry point](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/main.cpp): `src/main.cpp`
- [Base executor](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/base_executor.cpp): `src/sim/src/base_executor.cpp`
- [Interpreter](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/interp_executor.cpp): `src/sim/src/interp_executor.cpp`
- [Thread dispatcher](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/thread_executor.cpp): `src/sim/src/thread_executor.cpp`

### Machine model

- [CPU state](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/cpu_state.hpp): `src/sim/include/cpu_state.hpp`
- [RAM](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/memory.hpp): `src/sim/include/memory.hpp`
- [Instruction model](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/instr.cpp): `src/sim/src/instr.cpp`
- [ISA definitions](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/include/isa.hpp): `src/sim/include/isa.hpp`
- [Bit operations](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/bitops.cpp): `src/sim/src/bitops.cpp`

### ELF integration

- [ELFIO Ruby binding](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/elfio_ext/elfio_ext.cpp): `src/elfio_ext/elfio_ext.cpp`
- [ELF loader](https://github.com/umarnurmatov/sim-interpreter/blob/master/src/sim/src/loader.cpp): `src/sim/src/loader.cpp`

### Other components

- **Developer**
- **Assembly source**
- **ELF object**

## Connections

- Developer → Assembly source: writes (evidence: `README.md`)
- Developer → Ruby assembler: runs (evidence: `README.md`)
- Assembly source → Ruby assembler: assembles (evidence: `README.md`)
- Ruby assembler → ELFIO Ruby binding: uses bindings (evidence: `README.md`)
- Ruby assembler → ELF object: produces (evidence: `README.md`)
- Developer → CLI entry point: runs (evidence: `README.md`)
- ELF object → ELF loader: loads input (evidence: `README.md`)
- CLI entry point → ELF loader: calls (evidence: `src/main.cpp`)
- CLI entry point → Interpreter: selects mode (evidence: `src/main.cpp`)
- CLI entry point → Thread dispatcher: selects mode (evidence: `src/main.cpp`)
- ELF loader → Base executor: loads bytes (evidence: `src/sim/src/loader.cpp`)
- Base executor → CPU state: uses state (evidence: `src/sim/src/base_executor.cpp`)
- Base executor → Instruction model: decodes (evidence: `src/sim/src/base_executor.cpp`)
- Instruction model → ISA definitions: uses encoding
- CPU state → RAM: owns (evidence: `src/sim/include/cpu_state.hpp`)
- Interpreter → Base executor: inherits
- Thread dispatcher → Base executor: inherits
- Interpreter → Bit operations: calls (evidence: `src/sim/src/interp_executor.cpp`)
- Thread dispatcher → Bit operations: calls (evidence: `src/sim/src/thread_executor.cpp`)
- Interpreter → CPU state: executes on
- Thread dispatcher → CPU state: executes on
