# carlosdaniel26/lizard-os architecture

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

- Interactive diagram: https://gitdiagram.com/carlosdaniel26/lizard-os
- Repository: https://github.com/carlosdaniel26/lizard-os

## Overview

##### Project Type and Purpose
- Lizard-OS is a monolithic, educational operating system kernel targeting the i686 (32-bit x86) architecture.
- It provides a learning platform for low-level systems concepts: bootloading (Multiboot2/GRUB), CPU/arch initialization, memory management (PMM/VMM), interrupt handling, basic drivers (framebuffer, keyboard, PIT, RTC, ramdisk), multitasking, a simple shell, and a tiny VFS (tar-based).

##### High-Level File‐Structure Analysis
- Top‐level artifacts:
- Makefile, scripts/install_dependencies.sh – build & bootstrap tooling
- iso/boot/grub – GRUB Multiboot2 config for ISO image
- multiboot2.h, linker/linker.ld – multiboot header & memory layout
- / & src/ split into:
- kernel/arch – GDT, IDT, stack protector
- kernel/cpu – CPUID, PIC, ISRs
- kernel/mem – kmalloc, PMM, VMM
- kernel/drivers – VGA framebuffer, keyboard, PIT, RTC, ramdisk, tar, VFS
- kernel/multitasking – task structs, context switch (ASM)
- kernel/shit-shell & terminal – simple shell & VGA TTY
- libs – basic linked list, queue, stdio, string

##### Key README Insights
- Emphasis on educational value, hands-on exploration of OS internals

##### Diagramming Strategy
1. Bootloader Layer
- BIOS/UEFI (firmware) → GRUB (multiboot2) → boot.asm
2. Kernel Entry & Initialization
- multiboot parsing, early C runtime, init.c/kernel.c
3. Architecture & CPU Subsystems
- GDT/IDT setup (arch/i686), PIC, ISR handlers, CPU feature detection
4. Memory Management
- Physical Memory Manager (PMM)
- Virtual Memory Manager (VMM) / paging
- Kernel heap allocator (kmalloc)
5. Device Drivers & I/O
- Framebuffer/VGA driver
- Keyboard driver
- PIT timer driver
- RTC driver
- Ramdisk + TAR VFS
6. Multitasking & Scheduling
- Task structs, PID management
- Context switch assembly stubs
7. User Interface Layer
- Terminal/TTY abstraction
- “shit-shell” command interpreter
8. Utility Libraries
- linked_list, queue, stdio, string (C helpers)
9. Build & Deployment
- Linker script, Makefile, scripts, ISO & GRUB config

- BIOS → GRUB → Kernel Entry
- Kernel Entry → arch init → CPU subsystems → memory manager → driver init → scheduler → shell
- Driver modules ↔ hardware I/O ports & interrupts
- Shell ↔ terminal ↔ framebuffer & keyboard driver
- VFS layer ↔ ramdisk driver
- Multitasking scheduler ↔ CPU interrupt subsystem (timer IRQ)

c. Architectural Patterns & Principles
- Monolithic, but clearly layered: hardware abstraction (drivers), core services (mem, CPU), user interface (shell)
- Modular C code with each subsystem in its own directory
- Separation between architecture-specific (i686) and generic kernel code

d. Technologies & Languages
- Assembly (boot.asm, context switch stubs)
- C (kernel & libs)
- GRUB Multiboot2 protocol
- GNU Make, sh scripts
- ISO9660 + GRUB config

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bootloader Layer
    subgraph "Bootloader Layer"
        BIOS["BIOS/UEFI"]:::boot
        GRUB["GRUB (Multiboot2)"]:::boot
        MB_H["multiboot2.h"]:::boot
        BOOT_ASM["src/boot.asm"]:::boot
        MB_C["src/kernel/multiboot2.c"]:::boot
        LINKER["src/linker/linker.ld"]:::boot
        CFG["iso/boot/grub/grub.cfg"]:::boot
    end
    click MB_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/multiboot2.h"
    click BOOT_ASM "https://github.com/carlosdaniel26/lizard-os/blob/main/src/boot.asm"
    click MB_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/multiboot2.c"
    click LINKER "https://github.com/carlosdaniel26/lizard-os/blob/main/src/linker/linker.ld"
    click CFG "https://github.com/carlosdaniel26/lizard-os/blob/main/iso/boot/grub/grub.cfg"

    %% Kernel Entry & Initialization
    subgraph "Kernel Entry & Initialization"
        INIT_C["src/kernel/init.c"]:::core
        KERNEL_C["src/kernel/kernel.c"]:::core
        INIT_H["include/kernel/init.h"]:::core
    end
    click INIT_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/init.c"
    click KERNEL_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/kernel.c"
    click INIT_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/init.h"

    %% Architecture & CPU Subsystems
    subgraph "Architecture & CPU Subsystems"
        GDT_H["gdt.h"]:::core
        GDT_C["src/kernel/arch/i686/gdt.c"]:::core
        IDT_H["idt.h"]:::core
        IDT_C["src/kernel/arch/i686/idt.c"]:::core
        STACK["stack_protactor.c"]:::core
        CPUID_H["cpuid.h"]:::core
        CPUID_C["src/kernel/cpu/cpuid.c"]:::core
        ISR_H["isr.h"]:::core
        ISR_C["src/kernel/cpu/isr.c"]:::core
        PIC_H["pic.h"]:::core
        PIC_C["src/kernel/cpu/pic.c"]:::core
        STUB["src/kernel/cpu/stub_table.asm"]:::core
    end
    click GDT_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/arch/i686/gdt.h"
    click GDT_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/arch/i686/gdt.c"
    click IDT_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/arch/i686/idt.h"
    click IDT_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/arch/i686/idt.c"
    click STACK "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/arch/i686/stack_protactor.c"
    click CPUID_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/cpu/cpuid.h"
    click CPUID_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/cpu/cpuid.c"
    click ISR_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/cpu/isr.h"
    click ISR_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/cpu/isr.c"
    click PIC_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/cpu/pic.h"
    click PIC_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/cpu/pic.c"
    click STUB "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/cpu/stub_table.asm"

    %% Memory Management
    subgraph "Memory Management"
        PMM_H["pmm.h"]:::core
        PMM_C["src/kernel/mem/pmm.c"]:::core
        VMM_H["vmm.h"]:::core
        VMM_C["src/kernel/mem/vmm.c"]:::core
        KMALLOC_H["kmalloc.h"]:::core
        KMALLOC_C["src/kernel/mem/kmalloc.c"]:::core
    end
    click PMM_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/mem/pmm.h"
    click PMM_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/mem/pmm.c"
    click VMM_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/mem/vmm.h"
    click VMM_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/mem/vmm.c"
    click KMALLOC_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/mem/kmalloc.h"
    click KMALLOC_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/mem/kmalloc.c"

    %% Device Drivers & I/O
    subgraph "Device Drivers & I/O"
        FB_H["framebuffer.h"]:::drivers
        FB_C["src/kernel/drivers/framebuffer.c"]:::drivers
        KB_H["keyboard.h"]:::drivers
        KB_C["src/kernel/drivers/keyboard.c"]:::drivers
        PIT_H["pit.h"]:::drivers
        PIT_C["src/kernel/drivers/pit.c"]:::drivers
        RTC_H["rtc.h"]:::drivers
        RTC_C["src/kernel/drivers/rtc.c"]:::drivers
        RAMDISK_H["ramdisk.h"]:::drivers
        RAMDISK_C["src/kernel/drivers/ramdisk.c"]:::drivers
        TAR_H["tar.h"]:::drivers
        VFS_H["vfs.h"]:::drivers
    end
    click FB_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/framebuffer.h"
    click FB_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/drivers/framebuffer.c"
    click KB_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/keyboard.h"
    click KB_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/drivers/keyboard.c"
    click PIT_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/pit.h"
    click PIT_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/drivers/pit.c"
    click RTC_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/rtc.h"
    click RTC_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/drivers/rtc.c"
    click RAMDISK_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/ramdisk.h"
    click RAMDISK_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/drivers/ramdisk.c"
    click TAR_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/tar.h"
    click VFS_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/drivers/vfs.h"

    %% Multitasking & Scheduling
    subgraph "Multitasking & Scheduling"
        PID_H["pid.h"]:::core
        PID_C["src/kernel/multitasking/pid.c"]:::core
        TASK_H["task.h"]:::core
        TASK_C["src/kernel/multitasking/task.c"]:::core
        SWITCH["src/kernel/multitasking/switch_task.asm"]:::core
    end
    click PID_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/multitasking/pid.h"
    click PID_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/multitasking/pid.c"
    click TASK_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/multitasking/task.h"
    click TASK_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/multitasking/task.c"
    click SWITCH "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/multitasking/switch_task.asm"

    %% User Interface Layer
    subgraph "User Interface Layer"
        TTY_H["tty.h"]:::ui
        VGA_H["vga.h"]:::ui
        TTY_C["src/kernel/terminal/tty.c"]:::ui
        SS_H["ss.h"]:::ui
        SS_C["src/kernel/shit-shell/ss.c"]:::ui
    end
    click TTY_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/terminal/tty.h"
    click VGA_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/terminal/vga.h"
    click TTY_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/terminal/tty.c"
    click SS_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/kernel/shit-shell/ss.h"
    click SS_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/kernel/shit-shell/ss.c"

    %% Utility Libraries
    subgraph "Utility Libraries"
        LL_H["linked_list.h"]:::util
        Q_H["queue.h"]:::util
        Q_C["src/libs/queue.c"]:::util
        STDIO_H["stdio.h"]:::util
        STDIO_C["src/libs/stdio.c"]:::util
        STR_H["string.h"]:::util
        STR_C["src/libs/string.c"]:::util
    end
    click LL_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/libs/linked_list.h"
    click Q_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/libs/queue.h"
    click Q_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/libs/queue.c"
    click STDIO_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/libs/stdio.h"
    click STDIO_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/libs/stdio.c"
    click STR_H "https://github.com/carlosdaniel26/lizard-os/blob/main/include/libs/string.h"
    click STR_C "https://github.com/carlosdaniel26/lizard-os/blob/main/src/libs/string.c"

    %% Build & Deployment
    subgraph "Build & Deployment"
        MAKE["Makefile"]:::build
        SCRIPT["scripts/install_dependencies.sh"]:::build
        FORMAT["format.sh"]:::build
        CLANG[".clang-format"]:::build
        ISO_DIR["iso/boot"]:::build
        LINKER_LD2["src/linker/linker.ld"]:::build
    end
    click MAKE "https://github.com/carlosdaniel26/lizard-os/tree/main/Makefile"
    click SCRIPT "https://github.com/carlosdaniel26/lizard-os/blob/main/scripts/install_dependencies.sh"
    click FORMAT "https://github.com/carlosdaniel26/lizard-os/blob/main/format.sh"
    click CLANG "https://github.com/carlosdaniel26/lizard-os/blob/main/.clang-format"
    click ISO_DIR "https://github.com/carlosdaniel26/lizard-os/tree/main/iso/boot"
    click LINKER_LD2 "https://github.com/carlosdaniel26/lizard-os/blob/main/src/linker/linker.ld"

    %% Data Flows
    BIOS --> GRUB --> BOOT_ASM --> MB_H --> MB_C --> LINKER --> INIT_C
    INIT_C --> GDT_C --> PIC_C --> PMM_C --> VMM_C --> KMALLOC_C --> FB_C --> TTY_C --> SS_C
    CPUID_C --> IDT_C
    ISR_C --> SWITCH
    PIT_C --> SWITCH
    KB_C --> TTY_C
    RAMDISK_C --> VFS_H
    VFS_H --> SS_C

    %% Styles
    classDef boot fill:#cce5ff,stroke:#0062cc,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef drivers fill:#ffe5b4,stroke:#cc8400,color:#663c00
    classDef ui fill:#fff3cd,stroke:#856404,color:#856404
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#343a40
    classDef build fill:#f0f0f0,stroke:#999999,color:#333333
```
