# aelmosalamy/trivial-vm architecture

> Architecture diagram of the GitHub repository aelmosalamy/trivial-vm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aelmosalamy/trivial-vm
- Repository: https://github.com/aelmosalamy/trivial-vm

## Overview

Based on your project’s file tree and README, this is a lightweight C implementation of a 16‐bit virtual machine designed to interpret an esoteric assembly language. The project is structured as a single-level directory containing source code files for the virtual machine logic (vm.c/vm.h) and utility/helper functions (utils.c/utils.h), as well as a Windows batch script (compile.bat) for compiling the code. The README confirms that the VM mimics a CPU with 4 main registers and 64KB of addressable memory while supporting a minimal instruction set (mov, nop, hlt).

##### Main Components
- VM Initialization & Loader:
- Execution starting point (the compiled executable “vm.exe” launched via the batch script).
- This module is responsible for initializing the VM’s state, setting up registers, and loading the program into memory.
- CPU Module:
- In the Cpu module, show subcomponents like the Register Bank and the core execution loop.
- Memory Component:
- A block representing the 64KB addressable memory where the program code and data reside.
- Instruction Decoder and Executor:
- This block is critical in mapping the opcodes to the actual operations performed on the CPU and memory.
- Utility Module:
- A component for utilities (referencing utils.c and utils.h) used throughout the codebase for tasks such as error handling or auxiliary operations.
- (Optional/Future) IO/Peripheral Interfaces:
- Although not implemented yet, you might want to reserve a space for future expansion like serial communication or peripheral handling as mentioned in the README’s future work section.

##### Architectural Patterns & Design Principles
- The design leverages modularity by separating the VM’s core components (CPU, Memory, and Instruction Handling) into distinct code units.
- Extensible design that supports variable argument lengths and the potential for additional instructions or error codes.

##### Technologies and Frameworks
- That the compile.bat file is used as the build script to produce the executable, linking the source components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Loader["VM Loader/Initializer"]:::loader
    CPU["CPU (Registers & Execution Loop)"]:::cpu
    Memory["Memory (64KB)"]:::memory
    Decoder["Instruction Decoder/Executor"]:::decoder
    Utilities["Utilities"]:::utilities
    IO["IO/Peripheral Interfaces (Future)"]:::io

    Loader -->|"loadProgram"| Memory
    Loader -->|"initCPU"| CPU
    CPU -->|"fetch"| Memory
    Memory -->|"returnData"| CPU
    CPU -->|"processOpcode"| Decoder
    CPU -->|"invokeUtility"| Utilities
    Decoder ---|"futureIntegration"| IO
    CPU ---|"futureIntegration"| IO

    click Loader "https://github.com/aelmosalamy/trivial-vm/blob/master/compile.bat"
    click Loader "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.c"
    click CPU "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.c"
    click CPU "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.h"
    click Memory "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.c"
    click Memory "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.h"
    click Decoder "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.c"
    click Decoder "https://github.com/aelmosalamy/trivial-vm/blob/master/vm.h"
    click Utilities "https://github.com/aelmosalamy/trivial-vm/blob/master/utils.c"
    click Utilities "https://github.com/aelmosalamy/trivial-vm/blob/master/utils.h"

    classDef loader fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef cpu fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef memory fill:#f94144,stroke:#000,stroke-width:2px;
    classDef decoder fill:#277da1,stroke:#000,stroke-width:2px;
    classDef utilities fill:#f3722c,stroke:#000,stroke-width:2px;
    classDef io fill:#9d4edd,stroke:#000,stroke-width:2px;
```
