How ttcdm/willowos works
Purpose and execution model
willowOS is a freestanding x86-64 kernel, booted by Limine and run primarily through the Limine template’s make run workflow. The active system is rooted in limine-c-template-x86-64/; old/ contains superseded bootloader-era experiments. Kernel code executes directly on hardware/QEMU rather than as an application process.
Key entry/build boundaries: limine-c-template-x86-64/GNUmakefile, limine-c-template-x86-64/kernel/GNUmakefile, and limine-c-template-x86-64/kernel/linker.ld.
Boot and kernel initialization
Limine supplies boot-time platform and memory information; the kernel’s C-level entry/init orchestration is in limine-c-template-x86-64/kernel/src/main.c. Loader and executable-loading responsibilities are separated into limine-c-template-x86-64/kernel/src/loader.c and limine-c-template-x86-64/kernel/src/loader.h.
The linker script fixes the kernel image’s low-level layout, while assembly files bridge CPU operations not expressed in C, including limine-c-template-x86-64/kernel/src/get_cr3.asm and descriptor-table reload helpers.
CPU foundations, interrupts, and hardware discovery
Processor setup is layered around GDT/TSS, IDT, and interrupt-controller support:
• limine-c-template-x86-64/kernel/src/gdt.c
• limine-c-template-x86-64/kernel/src/idt.c
• limine-c-template-x86-64/kernel/src/apic.c
Interrupt entry stubs are in limine-c-template-x86-64/kernel/src/idt.asm; IOAPIC routes external interrupts, including keyboard input, through limine-c-template-x86-64/kernel/src/ioapic.c and limine-c-template-x86-64/kernel/src/keyboard.c. Timing uses HPET/TSC facilities in limine-c-template-x86-64/kernel/src/hpet.c and limine-c-template-x86-64/kernel/src/tsc.c.
ACPI parsing is provided by vendored uACPI at limine-c-template-x86-64/kernel/src/uacpi/ with implementation sources under uacpi/uacpi_src/; the kernel integration boundary is limine-c-template-x86-64/kernel/src/kernel_api.c.
Memory management
Memory management divides physical-frame management, page-table mapping, and higher-level virtual/heap allocation:
• limine-c-template-x86-64/kernel/src/paging.c
• limine-c-template-x86-64/kernel/src/vmm.c
• limine-c-template-x86-64/kernel/src/mman.h
Boot memory-map information feeds physical allocation and mapping setup; these services underpin kernel heap use, user address spaces, executable loading, and thread stacks. This is a critical low-level boundary: all hardware-visible virtual-memory changes must preserve page-table and allocator invariants.
Threads, SMP, and system-call boundary
The scheduler implements preemptive thread context switching and queue/block/yield/exit operations in limine-c-template-x86-64/kernel/src/scheduler.c, with context-switch assembly in limine-c-template-x86-64/kernel/src/scheduler.asm. Synchronization primitives reside in limine-c-template-x86-64/kernel/src/mutex.c.
User programs cross into privileged services via syscall/sysret: dispatch logic is in limine-c-template-x86-64/kernel/src/syscalls.c and architectural entry/return code in limine-c-template-x86-64/kernel/src/syscalls.asm. The syscall layer is the principal ABI boundary for the in-progress mlibc port and delegates many file operations to VFS vnode operations.
Storage and program execution
The filesystem stack separates generic pathname/file-object operations from an in-memory tmpfs implementation:
• limine-c-template-x86-64/kernel/src/vfs.c
• limine-c-template-x86-64/kernel/src/tmpfs.c
• limine-c-template-x86-64/kernel/src/inode_fs.c
A bundled tmpfs archive (limine-c-template-x86-64/tmpfs.tar) and package scripts support image contents. The loader consumes executable files through this storage boundary, creates user-mode execution context, and hands runnable threads to the scheduler.
Runtime dependencies and console
External/project-vendored runtime components are Limine, uACPI, flanterm, nanoprintf, and an intended mlibc userspace port. Framebuffer terminal output flows through limine-c-template-x86-64/kernel/src/flanterm/flanterm.c and limine-c-template-x86-64/kernel/src/flanterm/backends/fb.c; lightweight formatting is supplied by limine-c-template-x86-64/kernel/src/nanoprintf-0.5.4/nanoprintf.h.
The primary infrastructure is the Limine boot image and QEMU-oriented run/debug scripts, including limine-c-template-x86-64/limine.conf and limine-c-template-x86-64/g-debug.sh.
Main entry points: main.c Kernel initialization · idt.c CPU tables & interrupts · scheduler.c Scheduler · vfs.c Virtual filesystem
Components 17
Build & Boot
- Build workflow · Builds the bootable image and drives QEMU runs.
limine-c-template-x86-64/GNUmakefile - Kernel build
limine-c-template-x86-64/kernel/GNUmakefile - Kernel layout
limine-c-template-x86-64/kernel/linker.ld - Limine boot image · Supplies boot-time platform and memory information.
limine-c-template-x86-64/limine.conf
Platform Foundations
- Kernel initialization
limine-c-template-x86-64/kernel/src/main.c - CPU tables & interrupts · Establishes descriptor tables, interrupt dispatch, and interrupt controllers.
limine-c-template-x86-64/kernel/src/idt.c - Interrupt stubs
limine-c-template-x86-64/kernel/src/idt.asm - ACPI discovery · Discovers firmware hardware topology through vendored uACPI.
limine-c-template-x86-64/kernel/src/kernel_api.c - Timers & keyboard · HPET/TSC timing and IOAPIC-routed keyboard interrupts.
limine-c-template-x86-64/kernel/src/hpet.c
Kernel Services
- Memory management · Manages frames, page tables, kernel heap, and user address spaces.
limine-c-template-x86-64/kernel/src/paging.c - Scheduler · Queues, switches, blocks, and exits kernel and user threads.
limine-c-template-x86-64/kernel/src/scheduler.c - System-call ABI · Privileged ABI boundary for the mlibc userspace port.
limine-c-template-x86-64/kernel/src/syscalls.c - Program loader · Creates user execution contexts from executable files.
limine-c-template-x86-64/kernel/src/loader.c
Runtime & Storage
- Virtual filesystem · Provides generic pathname, file-object, and vnode operations.
limine-c-template-x86-64/kernel/src/vfs.c - tmpfs archive · Populates the filesystem from the bundled archive.
limine-c-template-x86-64/kernel/src/tmpfs.c - Bundled filesystem
limine-c-template-x86-64/tmpfs.tar - Framebuffer console
limine-c-template-x86-64/kernel/src/flanterm/backends/fb.c
Connections 21
- Build workflow → Kernel build: invokes
- Build workflow → Limine boot image: packages
- Kernel build → Kernel layout: links with
- Limine boot image → Kernel initialization: boots
- Kernel initialization → CPU tables & interrupts: initializes
- Kernel initialization → ACPI discovery: discovers hardware
- Kernel initialization → Memory management: passes boot memory map
- Kernel initialization → Virtual filesystem: mounts
- Kernel initialization → Framebuffer console: initializes
- CPU tables & interrupts → Interrupt stubs: dispatches through
- ACPI discovery → CPU tables & interrupts: provides topology
- Timers & keyboard → CPU tables & interrupts: raises interrupts
- CPU tables & interrupts → Scheduler: drives preemption
- Memory management → Scheduler: backs stacks
- Memory management → Program loader: maps user spaces
- Bundled filesystem → tmpfs archive: populates
- tmpfs archive → Virtual filesystem: implements
- Virtual filesystem → Program loader: supplies executables
- Program loader → Scheduler: submits runnable threads
- System-call ABI → Virtual filesystem: delegates file operations
- Scheduler → System-call ABI: runs user threads