# faresbakhit/lc3-vm architecture

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

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

## Overview

##### Component Relationships

**[Input Files] → [Image Loader] → [Memory System]**
- ↕
**[User Input] → [I/O System] ←→ [Core Execution Unit] ←→ [Register System]**
- ↕
- [Instruction Decoder]
- ↕
- [Condition Codes Handler]

##### Detailed Component Specifications

- Rounded rectangles for I/O and external interfaces
- Hexagons for processing units (Core Execution Unit)
- Diamonds for decision points (Condition Codes)

##### Implementation Details

Memory System (memory.rs):
- 65,536 memory locations (16-bit addressing)
- Memory-mapped registers
- Memory read/write operations

Instruction Processing:
- Decode unit (decode.rs)
- Opcode handling (opcode.rs)
- Condition codes (condcodes.rs)
- Trap code handling (trapcode.rs)

I/O System (io.rs):
- Terminal I/O handling
- Device interaction
- Custom termios implementation

##### Technical Details

A technical specifications section showing:
- 16-bit architecture
- Memory size
- Register set
- Supported instruction set

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        OBJ[".obj Files"]
        USR["User Input"]
    end

    subgraph Core["Core VM Components"]
        direction TB
        VM["LC-3 Virtual Machine"]:::core
        click VM "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/lc3.rs"
        
        subgraph Memory["Memory Subsystem"]
            direction TB
            MEM["Memory System<br/>(65,536 locations)"]:::memory
            click MEM "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/memory.rs"
            REG["Register System"]:::memory
            click REG "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/registers.rs"
        end

        subgraph Processing["Processing Units"]
            direction TB
            DEC["Instruction Decoder"]:::processor
            click DEC "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/decode.rs"
            OPC["Opcode Handler"]:::processor
            click OPC "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/opcode.rs"
            CC["Condition Codes"]:::processor
            click CC "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/condcodes.rs"
            TRAP["Trap Handler"]:::processor
            click TRAP "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/trapcode.rs"
        end
    end

    subgraph IO["I/O System"]
        direction TB
        IOS["I/O Handler"]:::io
        click IOS "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/io.rs"
        TERM["Terminal Interface"]:::io
        click TERM "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/termios.rs"
    end

    subgraph Programs["Program Components"]
        direction TB
        IMG["Image Loader"]:::program
        click IMG "https://github.com/faresbakhit/lc3-vm/blob/main/lc3/src/image.rs"
        OS["LC-3 OS"]:::program
        click OS "https://github.com/faresbakhit/lc3-vm/blob/main/src/lc3os.obj"
        EXAMPLES["Example Programs<br/>(2048, Rogue, etc)"]:::program
        click EXAMPLES "https://github.com/faresbakhit/lc3-vm/tree/main/examples"
    end

    %% Connections
    OBJ --> IMG
    IMG --> MEM
    USR --> IOS
    IOS <--> TERM
    IOS <--> VM
    
    VM <--> MEM
    VM <--> REG
    VM --> DEC
    DEC --> OPC
    DEC --> CC
    DEC --> TRAP
    
    TRAP --> IOS
    
    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px
    classDef memory fill:#bef,stroke:#333,stroke-width:1px
    classDef processor fill:#fbf,stroke:#333,stroke-width:1px
    classDef io fill:#bfb,stroke:#333,stroke-width:1px
    classDef program fill:#fdb,stroke:#333,stroke-width:1px

    %% Legend
    subgraph Legend
        L1["Core Component"]:::core
        L2["Memory Component"]:::memory
        L3["Processing Unit"]:::processor
        L4["I/O Component"]:::io
        L5["Program Component"]:::program
    end
```
