# damiramirez/lc3-vm-rust architecture

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

- Interactive diagram: https://gitdiagram.com/damiramirez/lc3-vm-rust
- Repository: https://github.com/damiramirez/lc3-vm-rust

## Overview

##### Main Components
- Entry Point (main.rs): Acts as the startup script that initializes the Virtual Machine.
- CPU Module (cpu.rs): Simulates the central processing unit. This module is likely responsible for interpreting the opcodes, managing the execution cycle, and applying instructions.
- Memory Module (memory.rs): Represents the system’s memory where the program (object code) is loaded and manipulated.
- Flags Module (flags.rs): Manages status flags (likely conditions from executed instructions, such as negative, zero, positive) used by the CPU during instruction evaluation.
- Opcode Module (opcode.rs): Defines the supported LC3 instructions and their behavior.
- Examples: The object files (e.g., 2048.obj, hello-world.obj) that serve as input programs to run on the VM.
- Build & Run Tools: Cargo.toml and Makefile indicate how the project is built and executed.

##### Relationships and Interactions
- The entry point (main.rs) orchestrates the initialization of the VM. It loads an object file from the examples directory based on the user's input.
- Once the program is loaded, the CPU module begins its fetch-decode-execute cycle:
- The CPU fetches instructions from the memory module.
- It uses the opcode definitions (from opcode.rs) to decode each instruction.
- It applies the instruction while updating statuses in the flags module as needed.
- The memory module both provides storage for the program code/data and acts as the runtime environment for operations.
- The entire flow is demonstrated through example object files, which are run using the make commands highlighted in the README.

##### Architectural Patterns and Design Principles
- Modular Design: Each major function is split into separate files (e.g., cpu.rs, memory.rs) allowing for clearer separation of concerns and easier testing.
- Instruction Cycle Model: The overall structure resembles a classic fetch-decode-execute cycle typical in virtual machine or emulator architectures.
- Educational/Proof-of-Concept: The overall design serves to illustrate the operation of a CPU in a controlled, simplified setting.

##### Including Specific Technologies and Tools
- Rust: The language of implementation, emphasizing safety and performance.
- Cargo & Makefile: Used for dependency management and execution. The Makefile facilitates running individual examples or the main demonstration.
- Example Programs: They serve as test cases to validate the VM’s correct implementation of the LC3 instruction set.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Virtual Machine Components
    subgraph "Core VM Components"
        E["Entry Point (main.rs)"]:::core
        CPU["CPU Module (cpu.rs)"]:::core
        M["Memory Module (memory.rs)"]:::core
        O["Opcode Module (opcode.rs)"]:::core
        F["Flags Module (flags.rs)"]:::core
    end

    %% External Example Programs
    subgraph "Example Programs"
        EX1["2048.obj"]:::example
        EX2["character_counter.obj"]:::example
        EX3["hello-world.obj"]:::example
        EX4["rogue.obj"]:::example
        EX5["traps.obj"]:::example
    end

    %% Build & Run Tools
    subgraph "Build & Run Tools"
        BR1["Cargo.toml"]:::build
        BR2["Makefile"]:::build
    end

    %% Relationships and Data Flow
    E -->|"initializes"| CPU
    EX1 -->|"loaded via"| M
    EX2 -->|"loaded via"| M
    EX3 -->|"loaded via"| M
    EX4 -->|"loaded via"| M
    EX5 -->|"loaded via"| M
    CPU -->|"fetches-from"| M
    CPU -->|"decodes-using"| O
    CPU -->|"updates"| F

    %% Click Events for Core Components
    click E "https://github.com/damiramirez/lc3-vm-rust/blob/main/src/main.rs"
    click CPU "https://github.com/damiramirez/lc3-vm-rust/blob/main/src/cpu.rs"
    click M "https://github.com/damiramirez/lc3-vm-rust/blob/main/src/memory.rs"
    click O "https://github.com/damiramirez/lc3-vm-rust/blob/main/src/opcode.rs"
    click F "https://github.com/damiramirez/lc3-vm-rust/blob/main/src/flags.rs"

    %% Click Events for Example Programs
    click EX1 "https://github.com/damiramirez/lc3-vm-rust/blob/main/examples/2048.obj"
    click EX2 "https://github.com/damiramirez/lc3-vm-rust/blob/main/examples/character_counter.obj"
    click EX3 "https://github.com/damiramirez/lc3-vm-rust/blob/main/examples/hello-world.obj"
    click EX4 "https://github.com/damiramirez/lc3-vm-rust/blob/main/examples/rogue.obj"
    click EX5 "https://github.com/damiramirez/lc3-vm-rust/blob/main/examples/traps.obj"

    %% Click Events for Build & Run Tools
    click BR1 "https://github.com/damiramirez/lc3-vm-rust/blob/main/Cargo.toml"
    click BR2 "https://github.com/damiramirez/lc3-vm-rust/tree/main/Makefile"

    %% Styling Definitions
    classDef core fill:#ffefd5,stroke:#d2691e,stroke-width:2px;
    classDef example fill:#e0ffff,stroke:#4682b4,stroke-width:2px;
    classDef build fill:#f0fff0,stroke:#32cd32,stroke-width:2px;
```
