# samsepi0x0/os-dev architecture

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

- Interactive diagram: https://gitdiagram.com/samsepi0x0/os-dev
- Repository: https://github.com/samsepi0x0/os-dev

## Overview

##### Project type and purpose
- This is an educational OS‐development repository containing boot‐sector code, 32-bit protected-mode setup, and very simple “kernel” routines in C and assembly.
- The README confirms it’s a collection of exercises from “Writing a Simple Operating System — from Scratch.”

##### File structure
- Top-level directories:
- boot-sector-programming – a series of 16-bit real-mode .asm → .bin examples (bootloader, printing, disk read)
- 32-bit-programming – setting up a GDT, switching to 32-bit protected mode, and a basic printing routine
- kernel – tiny C and assembly routines linked into .bin with accompanying .o/.dis for demonstration
- Configuration: each example has its own Bochs/QEMU config (bochsrc), and outputs .bin images.
- There is no high-level framework or external service integration; it’s pure low-level system software.

##### README for additional insights
- Build instructions: nasm for .asm → .bin, run with BOCHS/QEMU
- Progress notes: real-mode prints, disk reads, GDT definition, mode switching to protected mode

##### Essential architectural elements to capture
- The linear boot stages and hand-off points
- Mode transition: Real Mode to Protected Mode via GDT
- Invocation of printing and disk-I/O routines at each stage
- The fact that everything resides in flat `.bin` files on disk sectors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    BIOS["BIOS (Hardware/Firmware)"]:::hardware
    DiskImage["Disk Image (sectors with .bin files)"]:::hardware

    %% Stage 1: Real Mode Boot
    subgraph "Stage 1: Real-Mode Boot" 
        BootSectorLoader["Boot Sector Loader\n(16-bit assembly)"]:::real
        DiskReadRoutine["Secondary Loader / Disk Read Routine"]:::real
    end

    %% Stage 2: Protected Mode Setup
    subgraph "Stage 2: Protected-Mode Initialization"
        ProtectedModeInit["Protected-Mode Init\n(GDT & Mode Switch)"]:::prot
        PrintingRoutine["32-bit Printing Routine"]:::prot
        TestingExamples["Protected-Mode Testing Examples"]:::prot
    end

    %% Stage 3: Kernel
    subgraph "Stage 3: Kernel Routines"
        KernelRoutines["Kernel Routines\n(C & assembly)"]:::kernel
    end

    %% VM Configurations
    VMConfig1["Bochs/QEMU Configs"]:::vm

    %% Connections
    BIOS -->|"loads 0x7C00 (first 512B)"| BootSectorLoader
    DiskImage -->|“contains stage binaries”| BIOS
    BootSectorLoader -->|"reads further sectors"| DiskReadRoutine
    DiskReadRoutine -->|"loads GDT and code"| ProtectedModeInit
    ProtectedModeInit -->|"switch to 32-bit, jmp"| PrintingRoutine
    ProtectedModeInit -->|"switch to 32-bit, jmp"| TestingExamples
    ProtectedModeInit -->|"transfer control"| KernelRoutines
    KernelRoutines -->|"invoke I/O routines"| DiskReadRoutine
    KernelRoutines -->|"invoke print"| PrintingRoutine
    VMConfig1 ---|“used for each stage”| BootSectorLoader
    VMConfig1 ---|“used for each stage”| ProtectedModeInit
    VMConfig1 ---|“used for each stage”| KernelRoutines

    %% Click Events
    click BootSectorLoader "https://github.com/samsepi0x0/os-dev/tree/main/boot-sector-programming/"
    click DiskReadRoutine "https://github.com/samsepi0x0/os-dev/blob/main/boot-sector-programming/boot-disk-read.asm"
    click ProtectedModeInit "https://github.com/samsepi0x0/os-dev/tree/main/32-bit-programming/"
    click PrintingRoutine "https://github.com/samsepi0x0/os-dev/blob/main/32-bit-programming/printing-routine.asm"
    click TestingExamples "https://github.com/samsepi0x0/os-dev/blob/main/32-bit-programming/testing.asm"
    click KernelRoutines "https://github.com/samsepi0x0/os-dev/tree/main/kernel/"
    click VMConfig1 "https://github.com/samsepi0x0/os-dev/tree/main/boot-sector-programming/bochsrc"

    %% Styles
    classDef hardware fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef real fill:#90EE90,stroke:#000,stroke-width:1px
    classDef prot fill:#FFA500,stroke:#000,stroke-width:1px
    classDef kernel fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef vm fill:#F0E68C,stroke:#000,stroke-width:1px
```
