# remenod/bare-metal-snake architecture

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

- Interactive diagram: https://gitdiagram.com/remenod/bare-metal-snake
- Repository: https://github.com/remenod/bare-metal-snake

## Overview

##### Project Type and Purpose
- This is a bare-metal, ring-0-only, monolithic OS for x86, booting via BIOS/MBR into 32-bit protected mode.
- It includes a custom bootloader (in Assembly), a kernel (C + Assembly), hardware drivers, a minimal C runtime (“lib”), and several demo applications (Snake, Text Sandbox, etc.).

##### File Structure
- Top-level directories:
- boot/ – MBR bootloader (boot.asm)
- / – Public headers (arch, drivers, kernel, lib)
- src/ – Implementation code
– arch/x86/interrupts, ports, timer (architecture-specific CPU/interrupt code)
– kernel/ (core kernel services + drivers)
– lib/ (freestanding C library)
– apps/ (demo applications)
- Key build artifacts: linker scripts (linker.ld), Makefile, build output image.

##### Extract Architecture Insights from README
- Single-stage BIOS → MBR → protected-mode transition.
- Kernel subsystems: exception handling, PIC/PIT, keyboard, VGA text/graphics, stack guard, RSoD panic.
- “Apps” live on top of the kernel and invoke driver APIs directly.

1. BIOS (real-mode firmware)
2. MBR Bootloader (boot/boot.asm)
3. Protected-Mode Kernel
- Core Subsystem (kernel/core)
- Arch Layer (src/arch/x86)
– Interrupt Descriptor Table (IDT), exception & ISR handlers
– Programmable Interrupt Controller (PIC) & PIT timer
– Port I/O abstraction
- Drivers (kernel/drivers + include/drivers)
– PS/2 Keyboard
– QEMU Serial
– VGA Text Mode & Mode-13 Graphics + Palette + Font loader
- Stack Guard Module
- RSoD Panic Handler
4. Freestanding C Library (src/lib + include/lib)
5. Applications (src/apps/*)
– App Selector, Snake, Text Sandbox, RSoD Roulette, Segment Test
6. Hardware Peripherals
– x86 CPU, Memory Bus, VGA Framebuffer, PS/2 Controller, PIT, PIC

- BIOS → loads → MBR Bootloader → switches to protected mode → loads → Kernel
- Kernel Core ← uses → Arch Layer (IDT/PIC/PIT/ports)
- Core & Apps ← call → Drivers ← interact → Hardware (Keyboard, VGA, PIT)
- Apps ← link against → Freestanding C Library

c. Architectural Patterns & Principles:
- Monolithic kernel in ring 0 only
- Layered design: Bootloader → Kernel Core → Hardware Abstraction (Arch & Drivers) → Applications
- Freestanding C runtime (no libc)
- Event-driven via hardware interrupts

d. Key Technologies & Frameworks:
- Assembly: NASM for MBR, ISRs, protected-mode entry
- C: i386-elf-gcc for kernel, drivers, apps
- Linker script (linker.ld)
- QEMU for emulation/testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Boot Sequence
    BIOS["BIOS (Real Mode Firmware)"]:::boot
    MBR["MBR Bootloader"]:::boot
    BIOS -->|"loads"| MBR
    click MBR "https://github.com/remenod/bare-metal-snake/blob/master/boot/boot.asm"

    %% Kernel Load
    MBR -->|"switches to Protected Mode & loads"| Kernel

    %% Kernel Subsystems
    subgraph "Protected-Mode Kernel"
        direction TB
        subgraph "Core Subsystem"
            direction TB
            KernelCore["Kernel Core"]:::kernel
            MemorySub["Memory Subsystem"]:::kernel
        end

        subgraph "Architecture Layer"
            direction TB
            IDTISR["IDT & ISR Handlers"]:::arch
            PICPIT["PIC & PIT Timer"]:::arch
            PortIO["Port I/O Abstraction"]:::arch
            StackGuard["Stack Guard Module"]:::arch
            RSOD["RSoD Panic Handler"]:::arch
        end

        subgraph "Drivers"
            direction TB
            Keyboard["PS/2 Keyboard Driver"]:::driver
            Serial["QEMU Serial Driver"]:::driver
            VGA["VGA Text & Graphics Driver"]:::driver
        end

        Lib["Freestanding C Library"]:::lib

        subgraph "Applications"
            direction TB
            AppSel["App Selector"]:::app
            SnakeApp["Snake"]:::app
            TextSB["Text Sandbox"]:::app
            RSODApp["RSoD Roulette"]:::app
            SegTest["Segment Test"]:::app
        end
    end

    %% Hardware
    subgraph "Hardware Peripherals"
        direction TB
        CPU["x86 CPU"]:::hw
        MemBus["Memory Bus"]:::hw
        VGAFB["VGA Framebuffer"]:::hw
        PS2["PS/2 Controller"]:::hw
        PITDev["PIT Timer"]:::hw
        PICDev["PIC"]:::hw
    end

    %% Interconnections
    Kernel -->|uses| IDTISR
    Kernel -->|uses| PICPIT
    Kernel -->|uses| PortIO
    Kernel -->|uses| StackGuard
    Kernel -->|uses| RSOD

    KernelCore <-->|calls| Keyboard
    KernelCore <-->|calls| Serial
    KernelCore <-->|calls| VGA

    Keyboard -->|interacts| PS2
    Serial -->|interacts| CPU
    VGA -->|interacts| VGAFB

    PICPIT -->|interrupts| Kernel
    IDTISR -->|handles exceptions| Kernel

    AppSel -->|link against| Lib
    SnakeApp -->|link against| Lib
    TextSB -->|link against| Lib
    RSODApp -->|link against| Lib
    SegTest -->|link against| Lib

    AppSel -->|calls| Keyboard
    SnakeApp -->|calls| VGA
    TextSB -->|calls| VGA
    RSODApp -->|calls| RSOD
    SegTest -->|calls| StackGuard

    PICDev -->|generates| PICPIT
    PITDev -->|generates| PICPIT

    %% Click Events - Kernel Entry & Linker
    click KernelCore "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/core/kernel.c"
    click MemorySub "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/core/memory.c"
    click MemorySub "https://github.com/remenod/bare-metal-snake/blob/master/include/kernel/memory.h"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/idt.c"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/isr.c"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/cpu_exceptions_isrs.c"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/cpu_interrupts.asm"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/lidt.asm"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/idt.h"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/isr.h"
    click IDTISR "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/cpu_exceptions.h"
    click PICPIT "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/pic.c"
    click PICPIT "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/pic_interrupts.asm"
    click PICPIT "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/timer/pit.c"
    click PICPIT "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/pic.h"
    click PICPIT "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/timer/pit.h"
    click PortIO "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/ports.c"
    click PortIO "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/ports.h"
    click StackGuard "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/stack_guard/stack_guard.c"
    click StackGuard "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/stack_guard/stack_guard_extern.asm"
    click StackGuard "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/stack_guard/stack_guard.h"
    click RSOD "https://github.com/remenod/bare-metal-snake/blob/master/src/arch/x86/interrupts/rsod_routine.c"
    click RSOD "https://github.com/remenod/bare-metal-snake/blob/master/include/arch/x86/interrupts/rsod_routine.h"
    click Keyboard "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/drivers/keyboard.c"
    click Keyboard "https://github.com/remenod/bare-metal-snake/blob/master/include/drivers/keyboard.h"
    click Serial "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/drivers/qemu_serial.c"
    click Serial "https://github.com/remenod/bare-metal-snake/blob/master/include/drivers/qemu_serial.h"
    click VGA "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/drivers/vga.c"
    click VGA "https://github.com/remenod/bare-metal-snake/blob/master/src/kernel/drivers/screen.c"
    click VGA "https://github.com/remenod/bare-metal-snake/blob/master/include/drivers/vga.h"
    click VGA "https://github.com/remenod/bare-metal-snake/blob/master/include/drivers/screen.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/src/lib/arrlib.c"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/src/lib/math.c"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/src/lib/mem.c"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/src/lib/random.c"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/src/lib/string.c"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/arrlib.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/math.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/mem.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/random.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/string.h"
    click Lib "https://github.com/remenod/bare-metal-snake/blob/master/include/lib/types.h"
    click AppSel "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/app_selector/app_selector.c"
    click SnakeApp "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/snake/snake.c"
    click TextSB "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/text_sandbox/text_sandbox.c"
    click RSODApp "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/rsod_roulette/rsod_roulette.c"
    click SegTest "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/segment_test/segment_test.c"
    click SegTest "https://github.com/remenod/bare-metal-snake/blob/master/src/apps/segment_test/segment_test_extern.asm"

    %% Styles
    classDef boot fill:#ADD8E6,stroke:#000;
    classDef kernel fill:#90EE90,stroke:#000;
    classDef driver fill:#FFA500,stroke:#000;
    classDef app fill:#FFFF00,stroke:#000;
    classDef hw fill:#D3D3D3,stroke:#000;
    classDef arch fill:#98FB98,stroke:#000;
    classDef lib fill:#E0FFFF,stroke:#000;
```
