# leonmmcoset/leonos architecture

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

- Interactive diagram: https://gitdiagram.com/leonmmcoset/leonos
- Repository: https://github.com/leonmmcoset/leonos

## Overview

##### Project type and purpose
- LeonOS is a small, educational, monolithic operating system for x86 PCs, written in Rust.
- It targets emulators such as Bochs (bochsrc.disk) and produces bootable disk images (build/*.img).
- Provides basic kernel services (memory, processes, file system, drivers) plus a user‐space shell and utilities.

##### File structure
- Top-level crates:
– mbr: first-stage bootloader (512-byte MBR in assembly/Rust)
– loader & loader2: second and third stage loaders, switch to protected mode, set up paging
– kernel: core OS (drivers, VFS, scheduler, syscalls, thread/process mgmt, shell)
– common: shared library code (data structures, paging, context, device abstractions)
– user: a template for building ring-3 user programs
– cat, echo, grep: userland utilities that link against common & user crates
– rrt: a runtime crate (maybe for testing or special utilities)
- build.rs, linker scripts (.ld, .json) orchestrate builds per crate.
- build/ folder holds generated binaries (mbr.bin, loader.bin, kernel.bin) and disk images.
- tests/ contains Rust integration/unit tests for kernel subsystems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    Hardware["Hardware (Disk, CPU, Memory, VGA, Keyboard, Interrupts)"]:::hardware

    %% BIOS
    BIOS["BIOS"]:::hardware

    %% Bootloader Stages
    MBR["MBR\n(First-stage bootloader)"]:::bootloader
    Loader["Loader\n(Second-stage bootloader)"]:::bootloader
    Loader2["Loader2\n(Third-stage loader)"]:::bootloader

    %% Kernel with subsystems
    subgraph "Kernel (Ring 0)" 
        direction TB
        CPU["CPU Abstraction\n(GDT, IDT, TSS, Context)"]:::kernel
        Memory["Memory Mgmt\n(Paging, Allocators)"]:::kernel
        Drivers["Drivers\n(ATA, PIC, PIT, VGA, Keyboard)"]:::kernel
        FS["Virtual File System\n(Superblock, Inode, File API)"]:::kernel
        Scheduler["Scheduler\n(Process/Thread)"]:::kernel
        SysCall["Syscall Interface"]:::kernel
        Shell["In-kernel Shell"]:::kernel
        CPU --> Memory
        CPU --> Drivers
        Drivers --> FS
        FS --> Scheduler
        Scheduler --> SysCall
        SysCall --> Shell
    end

    %% Common Library
    Common["Common Library\n(Shared abstractions)"]:::common

    %% User Space
    subgraph "User Space (Ring 3)"
        direction TB
        UserTemplate["user\n(Ring 3 Template)"]:::user
        Cat["cat"]:::user
        Echo["echo"]:::user
        Grep["grep"]:::user
        UserTemplate --> Cat
        UserTemplate --> Echo
        UserTemplate --> Grep
    end

    %% Runtime/Test Utilities
    RRT["rrt\n(Runtime/Test utilities)"]:::user

    %% Tests Harness
    Tests["tests\n(Integration/Unit Tests)"]:::common

    %% Build Outputs
    Build["build\n(Binary & Disk Images)"]:::common

    %% Flows
    Hardware --> interrupts --> CPU
    BIOS -->|reads MBR| MBR
    MBR -->|loads into memory| Loader
    Loader -->|enters protected mode\nloads Loader2| Loader2
    Loader2 -->|sets up paging\nloads Kernel| CPU
    CPU -->|initializes subsystems| Memory
    Shell -->|spawns user programs| UserTemplate
    UserTemplate -->|executes via sys_call| SysCall
    SysCall -->|returns results| UserTemplate
    Drivers -->|hardware interrupts| CPU
    Common -->|dependency| CPU
    Common -->|dependency| Memory
    Common -->|dependency| Drivers
    Common -->|dependency| FS
    Common -->|dependency| Scheduler
    Common -->|dependency| SysCall
    Common -->|dependency| Shell
    Common -->|dependency| UserTemplate
    Common -->|dependency| Cat
    Common -->|dependency| Echo
    Common -->|dependency| Grep
    Common -->|dependency| RRT
    Tests -->|tests| CPU
    Tests -->|tests| Memory
    Tests -->|tests| FS
    Tests -->|tests| Scheduler

    %% Click Events
    click MBR "https://github.com/leonmmcoset/leonos/tree/main/mbr/"
    click Loader "https://github.com/leonmmcoset/leonos/tree/main/loader/"
    click Loader2 "https://github.com/leonmmcoset/leonos/tree/main/loader2/"
    click CPU "https://github.com/leonmmcoset/leonos/blob/main/kernel/src/interrupt.rs"
    click Memory "https://github.com/leonmmcoset/leonos/tree/main/kernel/src/memory/"
    click Drivers "https://github.com/leonmmcoset/leonos/tree/main/kernel/src/device/"
    click FS "https://github.com/leonmmcoset/leonos/tree/main/kernel/src/filesystem/"
    click Scheduler "https://github.com/leonmmcoset/leonos/blob/main/kernel/src/scheduler.rs"
    click SysCall "https://github.com/leonmmcoset/leonos/tree/main/kernel/src/sys_call/"
    click Shell "https://github.com/leonmmcoset/leonos/tree/main/kernel/src/shell/"
    click Common "https://github.com/leonmmcoset/leonos/tree/main/common/"
    click UserTemplate "https://github.com/leonmmcoset/leonos/tree/main/user/"
    click Cat "https://github.com/leonmmcoset/leonos/tree/main/cat/"
    click Echo "https://github.com/leonmmcoset/leonos/tree/main/echo/"
    click Grep "https://github.com/leonmmcoset/leonos/tree/main/grep/"
    click RRT "https://github.com/leonmmcoset/leonos/tree/main/rrt/"
    click Build "https://github.com/leonmmcoset/leonos/tree/main/build/"
    click Tests "https://github.com/leonmmcoset/leonos/tree/main/tests/"

    %% Styles
    classDef hardware fill:#ff9966,stroke:#333,stroke-width:1px
    classDef bootloader fill:#cccccc,stroke:#333,stroke-width:1px
    classDef kernel fill:#99ccff,stroke:#333,stroke-width:1px
    classDef user fill:#99ff99,stroke:#333,stroke-width:1px
    classDef common fill:#ffff99,stroke:#333,stroke-width:1px
```
