# ttcdm/willowos architecture

> Architecture diagram of the GitHub repository ttcdm/willowos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ttcdm/willowos
- Repository: https://github.com/ttcdm/willowos

## Overview

#### 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: [`limine-c-template-x86-64/kernel/src/main.c`](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/main.c) (Kernel initialization), [`limine-c-template-x86-64/kernel/src/idt.c`](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/idt.c) (CPU tables & interrupts), [`limine-c-template-x86-64/kernel/src/scheduler.c`](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/scheduler.c) (Scheduler), [`limine-c-template-x86-64/kernel/src/vfs.c`](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/vfs.c) (Virtual filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build &amp; Boot"]
  node_make["Build workflow<br/>Make build"]
  node_kernel_build["Kernel build<br/>Make build"]
  node_linker["Kernel layout<br/>Linker script<br/>[linker.ld]"]
  node_limine{{"Limine boot image<br/>Bootloader<br/>[limine.conf]"}}
end

subgraph group_platform["Platform Foundations"]
  node_kernel_entry["Kernel initialization<br/>C entrypoint<br/>[main.c]"]
  node_cpu_tables["CPU tables &amp; interrupts<br/>[idt.c]"]
  node_interrupt_stubs["Interrupt stubs<br/>Assembly entry<br/>[idt.asm]"]
  node_acpi["ACPI discovery<br/>uACPI integration<br/>[kernel_api.c]"]
  node_timer_input["Timers &amp; keyboard<br/>Hardware drivers<br/>[hpet.c]"]
end

subgraph group_kernel["Kernel Services"]
  node_memory["Memory management<br/>Paging / VMM<br/>[paging.c]"]
  node_scheduler["Scheduler<br/>Preemptive threads<br/>[scheduler.c]"]
  node_syscalls["System-call ABI<br/>syscall / sysret<br/>[syscalls.c]"]
  node_loader["Program loader<br/>Executable loader<br/>[loader.c]"]
end

subgraph group_runtime["Runtime &amp; Storage"]
  node_vfs["Virtual filesystem<br/>VFS<br/>[vfs.c]"]
  node_tmpfs[("tmpfs archive<br/>In-memory filesystem<br/>[tmpfs.c]")]
  node_tmpfs_image["Bundled filesystem<br/>tmpfs archive<br/>[tmpfs.tar]"]
  node_console["Framebuffer console<br/>flanterm backend<br/>[fb.c]"]
end

node_make -->|"invokes"| node_kernel_build
node_make -->|"packages"| node_limine
node_kernel_build -->|"links with"| node_linker
node_limine -->|"boots"| node_kernel_entry
node_kernel_entry -->|"initializes"| node_cpu_tables
node_kernel_entry -->|"discovers hardware"| node_acpi
node_kernel_entry -->|"passes boot memory map"| node_memory
node_kernel_entry -->|"mounts"| node_vfs
node_kernel_entry -->|"initializes"| node_console
node_cpu_tables -->|"dispatches through"| node_interrupt_stubs
node_acpi -->|"provides topology"| node_cpu_tables
node_timer_input -->|"raises interrupts"| node_cpu_tables
node_cpu_tables -->|"drives preemption"| node_scheduler
node_memory -->|"backs stacks"| node_scheduler
node_memory -->|"maps user spaces"| node_loader
node_tmpfs_image -->|"populates"| node_tmpfs
node_tmpfs -->|"implements"| node_vfs
node_vfs -->|"supplies executables"| node_loader
node_loader -->|"submits runnable threads"| node_scheduler
node_syscalls -->|"delegates file operations"| node_vfs
node_scheduler -.->|"runs user threads"| node_syscalls

click node_make "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/GNUmakefile"
click node_kernel_build "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/GNUmakefile"
click node_linker "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/linker.ld"
click node_limine "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/limine.conf"
click node_kernel_entry "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/main.c"
click node_cpu_tables "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/idt.c"
click node_interrupt_stubs "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/idt.asm"
click node_acpi "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/kernel_api.c"
click node_timer_input "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/hpet.c"
click node_memory "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/paging.c"
click node_scheduler "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/scheduler.c"
click node_syscalls "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/syscalls.c"
click node_loader "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/loader.c"
click node_vfs "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/vfs.c"
click node_tmpfs "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/tmpfs.c"
click node_tmpfs_image "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/tmpfs.tar"
click node_console "https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/flanterm/backends/fb.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_make,node_kernel_build,node_linker,node_limine toneBlue
class node_kernel_entry,node_cpu_tables,node_interrupt_stubs,node_acpi,node_timer_input toneAmber
class node_memory,node_scheduler,node_syscalls,node_loader toneMint
class node_vfs,node_tmpfs,node_tmpfs_image,node_console toneRose
```

## Components

### Build & Boot

- [Build workflow](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/GNUmakefile): Make build · Builds the bootable image and drives QEMU runs. · `limine-c-template-x86-64/GNUmakefile`
- [Kernel build](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/GNUmakefile): Make build · `limine-c-template-x86-64/kernel/GNUmakefile`
- [Kernel layout](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/linker.ld): Linker script · `limine-c-template-x86-64/kernel/linker.ld`
- [Limine boot image](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/limine.conf): Bootloader · Supplies boot-time platform and memory information. · `limine-c-template-x86-64/limine.conf`

### Platform Foundations

- [Kernel initialization](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/main.c): C entrypoint · `limine-c-template-x86-64/kernel/src/main.c`
- [CPU tables & interrupts](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/idt.c): GDT / IDT / APIC · Establishes descriptor tables, interrupt dispatch, and interrupt controllers. · `limine-c-template-x86-64/kernel/src/idt.c`
- [Interrupt stubs](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/idt.asm): Assembly entry · `limine-c-template-x86-64/kernel/src/idt.asm`
- [ACPI discovery](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/kernel_api.c): uACPI integration · Discovers firmware hardware topology through vendored uACPI. · `limine-c-template-x86-64/kernel/src/kernel_api.c`
- [Timers & keyboard](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/hpet.c): Hardware drivers · HPET/TSC timing and IOAPIC-routed keyboard interrupts. · `limine-c-template-x86-64/kernel/src/hpet.c`

### Kernel Services

- [Memory management](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/paging.c): Paging / VMM · Manages frames, page tables, kernel heap, and user address spaces. · `limine-c-template-x86-64/kernel/src/paging.c`
- [Scheduler](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/scheduler.c): Preemptive threads · Queues, switches, blocks, and exits kernel and user threads. · `limine-c-template-x86-64/kernel/src/scheduler.c`
- [System-call ABI](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/syscalls.c): syscall / sysret · Privileged ABI boundary for the mlibc userspace port. · `limine-c-template-x86-64/kernel/src/syscalls.c`
- [Program loader](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/loader.c): Executable loader · Creates user execution contexts from executable files. · `limine-c-template-x86-64/kernel/src/loader.c`

### Runtime & Storage

- [Virtual filesystem](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/vfs.c): VFS · Provides generic pathname, file-object, and vnode operations. · `limine-c-template-x86-64/kernel/src/vfs.c`
- [tmpfs archive](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/tmpfs.c): In-memory filesystem · Populates the filesystem from the bundled archive. · `limine-c-template-x86-64/kernel/src/tmpfs.c`
- [Bundled filesystem](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/tmpfs.tar): tmpfs archive · `limine-c-template-x86-64/tmpfs.tar`
- [Framebuffer console](https://github.com/ttcdm/willowos/blob/mac/limine-c-template-x86-64/kernel/src/flanterm/backends/fb.c): flanterm backend · `limine-c-template-x86-64/kernel/src/flanterm/backends/fb.c`

## Connections

- 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
