# vaakii/vakios64 architecture

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

- Interactive diagram: https://gitdiagram.com/vaakii/vakios64
- Repository: https://github.com/vaakii/vakios64

## Overview

##### Project type and purpose
- VaKiOS64 is a single-kernel, educational x86_64 operating system. It is not a typical client/server or full-stack web app, but rather a low-level systems project comprising a multiboot bootloader, kernel core, hardware drivers, and basic runtime services.
- The README confirms its focus on setting up the GDT, IDT, memory management (paging, heap), PIC/PIT programming, keyboard input, and VGA output.

##### File structure
- Top-level artifacts:
- Dockerfile, build.sh, qemu.sh – build and run scripts/environment.
- kernel/ – all source and headers for the kernel.
- kernel/include/ – API and hardware interface definitions (drivers, memory, sys/stdio, tty/vga).
- kernel/src/arch/ – architecture-specific implementation:
– boot (multiboot.asm)
– drivers (keyboard.c)
– linker scripts (link.ld) and make configs
– memory modules (exceptions, gdt, idt, paging, pic, pit, malloc)
– sys (stdio.c)
– vga (tty.c, vga.c)
- There’s a single Makefile under kernel for building the kernel image.
- Scripts at root orchestrate cross-compilation, ISO creation, and QEMU invocation.

##### README for additional insights
- It outlines required external tools: cross-compiler, GNU Make, QEMU.
- Build produces an ISO; run script boots it under QEMU.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Environment & Toolchain"
        BuildSh["build.sh"]:::external
        QemuSh["qemu.sh"]:::external
        Dockerfile["Dockerfile"]:::external
        Makefile["kernel/Makefile"]:::external
        MakeConfig["make.config"]:::external
    end

    subgraph "Emulation (External)"
        QEMU["QEMU Emulator"]:::external
        BIOS["BIOS"]:::external
    end

    BuildSh -->|"build ISO"| KernelImage["Kernel ISO/Image"]:::external
    QemuSh -->|"boot ISO"| QEMU
    Dockerfile -->|"provides env"| BuildSh
    QEMU --> BIOS

    BIOS --> MultibootAsm
    KernelImage --> QEMU

    subgraph "Bootloader Stage" 
        MultibootAsm["multiboot.asm"]:::bootStage
        Linker["link.ld"]:::bootStage
        MultibootAsm --> Linker
        Linker --> KernelEntry["Kernel Entry & Init"]:::core
    end

    subgraph "Kernel Core" 
        KernelEntry
        subgraph "Descriptor Tables"
            GDT_H["gdt.h"]:::core
            GDT_C["gdt.c"]:::core
            IDT_H["idt.h"]:::core
            IDT_C["idt.c"]:::core
            KernelEntry --> GDT_C
            KernelEntry --> IDT_C
            GDT_H --> GDT_C
            IDT_H --> IDT_C
        end
        subgraph "Interrupt Controllers"
            PIC_H["pic.h"]:::core
            PIC_C["pic.c"]:::core
            PIT_H["pit.h"]:::core
            PIT_C["pit.c"]:::core
            EXC["exceptions.c"]:::core
            KernelEntry --> PIC_C
            KernelEntry --> PIT_C
            KernelEntry --> EXC
            PIC_H --> PIC_C
            PIT_H --> PIT_C
        end
        subgraph "Memory Management"
            Paging_H["paging.h"]:::core
            Paging_C["paging.c"]:::core
            Mem_H["memory.h"]:::core
            Malloc_C["malloc.c"]:::core
            Mem_C["memory.c"]:::core
            KernelEntry --> Paging_C
            KernelEntry --> Malloc_C
            KernelEntry --> Mem_C
            Paging_H --> Paging_C
            Mem_H --> Malloc_C
            Mem_H --> Mem_C
        end
        subgraph "Drivers & Services"
            Keyboard_H["keyboard.h"]:::driver
            Keyboard_C["keyboard.c"]:::driver
            VGA_H["vga.h"]:::driver
            VGA_C["vga.c"]:::driver
            TTY_H["tty.h"]:::driver
            TTY_C["tty.c"]:::driver
            STDIO_H["stdio.h"]:::driver
            STDIO_C["stdio.c"]:::driver
            KernelEntry --> Keyboard_C
            KernelEntry --> VGA_C
            KernelEntry --> TTY_C
            KernelEntry --> STDIO_C
            Keyboard_H --> Keyboard_C
            VGA_H --> VGA_C
            TTY_H --> TTY_C
            STDIO_H --> STDIO_C
        end
    end

    classDef bootStage fill:#a7c7e7,stroke:#333,stroke-width:1px;
    classDef core fill:#b2f2bb,stroke:#333,stroke-width:1px;
    classDef driver fill:#ffd699,stroke:#333,stroke-width:1px;
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px;

    click BuildSh "https://github.com/vaakii/vakios64/blob/master/./build.sh"
    click QemuSh "https://github.com/vaakii/vakios64/blob/master/./qemu.sh"
    click Dockerfile "https://github.com/vaakii/vakios64/tree/master/./Dockerfile"
    click Makefile "https://github.com/vaakii/vakios64/tree/master/kernel/Makefile"
    click MakeConfig "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/make.config"
    click MultibootAsm "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/boot/multiboot.asm"
    click Linker "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/linker/link.ld"
    click KernelEntry "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/kernel.c"
    click GDT_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/gdt.h"
    click GDT_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/gdt.c"
    click IDT_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/idt.h"
    click IDT_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/idt.c"
    click PIC_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/pic.h"
    click PIC_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/pic.c"
    click PIT_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/pit.h"
    click PIT_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/pit.c"
    click EXC "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/exceptions.c"
    click Paging_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/paging.h"
    click Paging_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/paging.c"
    click Mem_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/memory/memory.h"
    click Malloc_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/malloc.c"
    click Mem_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/memory/memory.c"
    click Keyboard_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/drivers/keyboard.h"
    click Keyboard_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/drivers/keyboard.c"
    click VGA_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/tty/vga.h"
    click VGA_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/vga/vga.c"
    click TTY_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/tty/tty.h"
    click TTY_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/vga/tty.c"
    click STDIO_H "https://github.com/vaakii/vakios64/blob/master/kernel/include/sys/stdio.h"
    click STDIO_C "https://github.com/vaakii/vakios64/blob/master/kernel/src/arch/sys/stdio.c"
```
