# benaliossama/vm architecture

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

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

## Overview

##### Project type and purpose
- This is a Corewar game implementation in Rust, consisting of two collaborating tools:
- An **Assembler** that translates `.s` files into `.cor` binaries
- A **Virtual Machine (VM)** that loads `.cor` players into a circular memory arena and executes them cycle by cycle
- The user’s focus is on the VM; the Assembler is a separate component (see playground/asm_ref)

##### File structure
- Top-level:
- Cargo.toml / src/…: Rust project defining the VM’s code (arena.rs, vm.rs, instructions.rs, process.rs, etc.)
- Makefile & README.md: build and run instructions
- playground/: test harness containing reference assembler (playground/asm_ref), reference VM (playground/vm_ref), sample players (playground/players_src) and helper scripts
- src/ directory follows a modular layout:
- arena.rs – circular memory manager
- process.rs, player.rs – process & player state
- instructions.rs, counter.rs – decoding & parameter counting
- vm.rs, utils.rs, config.rs – overall VM orchestration, configuration, utility functions
- No external dependencies beyond Rust std; testing is via sample `.cor` files and scripts in playground/

##### README for additional insights
- Confirms core modules: memory management, processes, instruction decoding, scheduling, lifecycle checks
- Make targets: `make run` launches VM with sample players
- todo.md tracks progress on missing instructions, features

##### Final advice
- Ring buffer nature of the arena and the cyclical scheduler
- Do not overcomplicate: clarity and separation of core subsystems (Loading, Memory, Execution, Scheduling) is key

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Assembly and Execution Lanes stacked vertically for clarity
    subgraph "Assembly Lane"
        direction LR
        CLI["CLI / Entry Point<br>(main.rs)"]:::io --> Config["Config Loader<br>(config.rs)"]:::module
        Config --> Asm["Assembler (Reference)<br>(playground/asm_ref)"]:::external
        Asm --> CorBinary[".cor Binary"]:::data
    end

    subgraph "Execution Lane"
        direction LR
        CorBinary --> Loader["Binary Loader<br>(utils.rs)"]:::module
        Loader --> PlayerState["Player State<br>(player.rs)"]:::module
        PlayerState --> Process["Process Manager<br>(process.rs)"]:::module
        Process --> Counter["Counter (Param Counting)<br>(counter.rs)"]:::module
        Counter --> Decoder["Instruction Decoder & Executor<br>(instructions.rs)"]:::module
        Decoder --> Scheduler["Cycle Scheduler / Lifecycle Checker<br>(vm.rs)"]:::module
        Scheduler --> Arena["Arena (Circular Memory)<br>(arena.rs)"]:::data
        Arena --> Process
    end

    %% Test Harness feeding both lanes
    TestHarness["Test Harness<br>(playground/)"]:::external
    TestHarness --> Asm
    TestHarness --> CorBinary

    %% Click Events
    click CLI "https://github.com/benaliossama/vm/blob/main/src/main.rs"
    click Config "https://github.com/benaliossama/vm/blob/main/src/config.rs"
    click Asm "https://github.com/benaliossama/vm/tree/main/playground/asm_ref"
    click Loader "https://github.com/benaliossama/vm/blob/main/src/utils.rs"
    click PlayerState "https://github.com/benaliossama/vm/blob/main/src/player.rs"
    click Process "https://github.com/benaliossama/vm/blob/main/src/process.rs"
    click Counter "https://github.com/benaliossama/vm/blob/main/src/counter.rs"
    click Decoder "https://github.com/benaliossama/vm/blob/main/src/instructions.rs"
    click Scheduler "https://github.com/benaliossama/vm/blob/main/src/vm.rs"
    click Arena "https://github.com/benaliossama/vm/blob/main/src/arena.rs"
    click TestHarness "https://github.com/benaliossama/vm/tree/main/playground/"

    %% Styling
    classDef module fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#9f9,stroke:#333,stroke-width:1px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef io fill:#ff9,stroke:#333,stroke-width:1px
```
