How shadokos/kfs works
Project type and purpose
• This is a monolithic, UNIX-like kernel for i386, written entirely in Zig.
• It provides core OS services (memory management, task scheduling, device drivers, syscall interface) plus a kernel-mode shell and basic CI/test harnesses.
• Key use cases: boot under GRUB or Limine, run on real or emulated hardware (QEMU), exercise memory and multitasking features, and support a minimal userspace POC.
File structure
• Top-level:
• CI/ : custom CI scripts, Dockerfile, ISO boot configs
• build.zig & build/ : Zig and Makefile wrappers for building the kernel, bootloader integration, ISO creation, QEMU launch
• iso/ : generated ISO boot images (GRUB and Limine folders)
• src/ : all kernel source code (boot, drivers, memory, task scheduler, shell, syscalls, etc.)
• src/ subdivided by subsystem:
• drivers/ : ACPI, PIC, PIT, PS2, serial port, VGA
• memory/ : allocators (buddy, slab, multipool, page-grained), paging, mapping, virtual space
• task/ : scheduler, ready queue, user-space trampoline, semaphores, signals
• tty/ : buffer writer, keyboard, themes, vt100 emulation
• syscall/ : individual syscall implementations
• shell/ : built-in commands for CI and default shell
• misc/ : logging, ASCII art, random, basic data structures
• Build and CI:
• .github/, CI/, Makefile, build.zig, build/Makefiles/ orchestrate compilation, testing, linting, ISO creation, and QEMU runs
README for additional insights
• Features list confirms core subsystems (Terminal, Memory, Multitasking) and pending parts (filesystem, signals, ELF exec).
• Testing section highlights serial port and CI integration.
Main components & interactions
a. Main components:
1. Hardware Layer (i386 CPU, physical RAM, I/O buses)
2. Bootloader Layer (GRUB / Limine)
3. Kernel Initialization
4. Memory Management Subsystem
• Page frame allocator (buddy)
• Virtual space allocator (AVL trees)
• Object allocators (slab, multipool, page-grained)
5. Device Drivers
• PS/2, VGA, Serial, PIC, PIT, ACPI
6. Task Scheduler & Multitasking
• Ready queue, context switching, semaphores, signals
7. System Call Interface
8. Kernel-mode Shell (terminal + built-ins)
9. Userspace POC (ELF loader pending)
10. CI / Build System
• Zig build scripts, Makefiles, Docker, QEMU emulator
b. Relationships & interactions:
• Bootloader → Loads Kernel (entry point, passes multiboot2 or limine info)
• Kernel Initialization → Sets up GDT, IDT, paging (HIGHER HALF mapping)
• Drivers ↔ Hardware: controllers and devices accessed via I/O ports and memory-mapped I/O
• Memory Subsystem ↔ Kernel & Tasks: allocates pages, objects, handles page faults
• Scheduler ↔ Memory ↔ Tasks: context switch uses page tables, allocates stacks
• Syscall Interface: user tasks invoke kernel services
• Shell ↔ Syscall Interface: runs built-in commands in kernel mode
• CI / Build System ↔ Source: triggers compile, link, ISO image, QEMU test harness
c. Architectural patterns & principles:
• Monolithic kernel: all core services linked in one binary
• Layered initialization: hardware abstraction then subsystems
• Modular code organization by subsystem under src/
• Build-time dependency graph via Zig and Makefiles
• Emulation & testing integrated in CI pipelines
d. Technologies, frameworks, libraries:
• Zig language for kernel and build scripts
• GNU Make + custom Makefiles (CI.mk, Docker.mk, Limine.mk, Zig.mk)
• GRUB and Limine bootloaders
• QEMU for emulation
• Docker for isolated CI runs
Detailed breakdown to capture essential elements
• Initialization flow: startup.asm (trampoline) → boot.zig → init subsystems.
• CI pipeline step (lint → build → test on QEMU → ISO generation).
• Don’t overload with every .zig file—group by subsystem folders.
• How the kernel boots and initializes
• The core OS subsystems and their interactions
• The build/test pipeline that produces and validates the kernel
• The boundary between hardware, kernel, and (future) userspace components