include: one folder per subsystem, and includes that name it

Sixty-five headers sat side by side in include/, so `#include "irq.h"`
said nothing about where irq.h was or what it belonged to, and errno.h,
stat.h and fcntl.h at the top shadowed the system's for any host tool
built with -I./include. They are in folders now -- arch/ core/ fs/
dev/ gfx/ net/ uapi/ (and ldls/ for the Linux driver layer) -- and
every include names the folder, as Linux's do: "core/proc.h".

Done mechanically and checked the hard way: the kernel built from this
tree disassembles identically to the one built from the tree before
it. The full image boots, and userland is the same set of programs.
Paths in docs and comments follow; docs/guides/layout.md has a table
of what is where, and tools/fix-includes.py rewrites old-style
includes from the folders in the tree, for code written before this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S1giNvrHTrPMPw7V6x1kQ4

kernel/core/console.c

@@ -1,25 +1,25 @@
 #include <stdarg.h>
-#include "types.h"
-#include "defs.h"
-#include "klog.h"
-#include "dbg.h"
-#include "vt.h"
-#include "kbd.h"   /* KBD_VT_SWITCH -- the terminal-switch chords */
-#include "gfx.h"
-#include "theme.h"
-#include "irq.h"
-#include "param.h"
-#include "traps.h"
-#include "errno.h"
-#include "spinlock.h"
-#include "sleeplock.h"
-#include "fs.h"
-#include "file.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "proc.h"
-#include "posix.h"
-#include "x86.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/klog.h"
+#include "core/dbg.h"
+#include "dev/vt.h"
+#include "dev/kbd.h"   /* KBD_VT_SWITCH -- the terminal-switch chords */
+#include "gfx/gfx.h"
+#include "gfx/theme.h"
+#include "core/irq.h"
+#include "core/param.h"
+#include "arch/traps.h"
+#include "uapi/errno.h"
+#include "core/spinlock.h"
+#include "core/sleeplock.h"
+#include "fs/fs.h"
+#include "fs/file.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/proc.h"
+#include "uapi/posix.h"
+#include "arch/x86.h"
 
 void consputc(int);
 // Set by panic() once the crash screen has been painted: after that, consputc
@@ -268,7 +268,7 @@ consputc(int c)
 
   // Every kernel message passes through here, which is what makes this the
   // one hook the log needs: cprintf, panic's report, a driver's complaint at
-  // three in the morning. See include/klog.h.
+  // three in the morning. See include/core/klog.h.
   klog_putc(c);
 
   // Held back from the screen and the wire, kept in the log. See kinfo().
@@ -584,7 +584,7 @@ consoleintr(int (*getc)(void))
     // three-byte character, so a reader decoding UTF-8 swallowed the next two
     // keys waiting for continuations that never came -- every arrow key
     // corrupted the two keystrokes after it. The keycodes now sit above
-    // U+10FFFF where nothing can collide with them; see include/kbd.h.
+    // U+10FFFF where nothing can collide with them; see include/dev/kbd.h.
     //
     // What a terminal sends is `ESC [ A`, and what makes zsh's line editor
     // work is receiving that. The sequences below are the DEC/xterm ones that

kernel/core/dma.c

@@ -1,14 +1,14 @@
-// Physically contiguous memory for devices. See include/dma.h.
+// Physically contiguous memory for devices. See include/core/dma.h.
 
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "spinlock.h"
-#include "dma.h"
-#include "sbuf.h"
-#include "dbg.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/spinlock.h"
+#include "core/dma.h"
+#include "core/sbuf.h"
+#include "core/dbg.h"
 
 #define DMA_GRAIN  64          // one cache line; also xHCI's ring alignment
 #define NEXTENT    64          // free extents we can track

kernel/core/kalloc.c

@@ -2,14 +2,14 @@
 // memory for user processes, kernel stacks, page table pages,
 // and pipe buffers. Allocates 4096-byte pages.
 
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "spinlock.h"
-#include "sbuf.h"
-#include "dbg.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/spinlock.h"
+#include "core/sbuf.h"
+#include "core/dbg.h"
 
 void freerange(void *vstart, void *vend);
 extern char end[]; // first address after kernel loaded from ELF file

kernel/core/klog.c

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 //
-// The kernel log that outlives the kernel. See include/klog.h.
+// The kernel log that outlives the kernel. See include/core/klog.h.
 //
 // Two properties are worth reading the code for, because both are easy to
 // write and easy to get subtly wrong:
@@ -20,12 +20,12 @@
 // early output goes into a small static array and is flushed into the ring the
 // moment there is one.
 
-#include "types.h"
-#include "defs.h"
-#include "memlayout.h"
-#include "klog.h"
-#include "sbuf.h"
-#include "dbg.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "arch/memlayout.h"
+#include "core/klog.h"
+#include "core/sbuf.h"
+#include "core/dbg.h"
 
 // consputc()'s cursor-movement escape, from kernel/core/console.c.
 #define BACKSPACE 0x100

kernel/core/kmem.c

@@ -1,4 +1,4 @@
-// Small-object allocation. See include/kmem.h for what this is for.
+// Small-object allocation. See include/core/kmem.h for what this is for.
 //
 // A slab is one page from kalloc(), with a header at the front and objects
 // packed after it. Free objects hold the free list in their own first eight
@@ -35,15 +35,15 @@ static void acquire(struct spinlock *l) { (void)l; }
 static void release(struct spinlock *l) { (void)l; }
 #define PGROUNDDOWN(a) (((uint64)(a)) & ~((uint64)PGSIZE - 1))
 #else
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "mmu.h"
-#include "spinlock.h"
-#include "sbuf.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/mmu.h"
+#include "core/spinlock.h"
+#include "core/sbuf.h"
 #endif
 
-#include "kmem.h"
+#include "core/kmem.h"
 
 // Objects are 16-byte aligned. Eight would be enough for the free list, but
 // sixteen is what the ABI wants for anything that might hold a long double or

kernel/core/ksym.c

@@ -14,8 +14,8 @@
 // checks that rather than trusting it, by listing the text symbols of both
 // passes and refusing to build if they differ.
 
-#include "types.h"
-#include "defs.h"
+#include "core/types.h"
+#include "core/defs.h"
 
 // Weak, and the reason is worth stating: the first link pass has no table --
 // it is the input to the program that writes one. An undefined weak symbol

kernel/core/main.c

@@ -1,19 +1,19 @@
-#include "types.h"
-#include "defs.h"
-#include "vt.h"
-#include "gfx.h"
-#include "param.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "proc.h"
-#include "x86.h"
-#include "irq.h"
-#include "dma.h"
-#include "klog.h"
-#include "usb.h"
-#include "acpi.h"
-#include "vmap.h"
-#include "hwinfo.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "dev/vt.h"
+#include "gfx/gfx.h"
+#include "core/param.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/proc.h"
+#include "arch/x86.h"
+#include "core/irq.h"
+#include "core/dma.h"
+#include "core/klog.h"
+#include "dev/usb.h"
+#include "dev/acpi.h"
+#include "arch/vmap.h"
+#include "core/hwinfo.h"
 
 static void *klog_base;   // the persistent log, just above the kernel image
 
@@ -37,7 +37,7 @@ int boot_debug;
 // Must match SCHBOOT_VERBOSE_FLAG in boot/bios/stage2main.c exactly: just past
 // the VBE info block, not 0x7000 (startothers() below uses that address for
 // the AP boot trampoline).
-#include "schboot.h"
+#include "arch/schboot.h"
 
 // Bootstrap processor starts running C code here.
 // Allocate a real stack and switch to it, first
@@ -174,7 +174,7 @@ kmain(uint32 fb_addr)
   // kalloc's free list makes no such promise -- two pages from it are adjacent
   // only by chance. Taking it first is the only way to be sure the region
   // exists; asking for it later would mean asking kalloc for something it
-  // fundamentally cannot provide. See include/dma.h.
+  // fundamentally cannot provide. See include/core/dma.h.
   // Before anything touches PHYSTOP, which is now a variable read from the
   // firmware's memory map rather than a constant asserting 224 MB exists.
   e820_init();
@@ -295,7 +295,7 @@ kmain(uint32 fb_addr)
   //
   // main() names no display driver. Whichever one owns the boot framebuffer
   // publishes it there as this kernel's scanout, and the console and crash
-  // screen draw on that; see include/gfx.h.
+  // screen draw on that; see include/gfx/gfx.h.
   //
   // No splash drawing here on purpose. The loader owns the splash, logo and
   // all, and bringing the framebuffer up deliberately does not clear it -- so
@@ -357,7 +357,7 @@ kmain(uint32 fb_addr)
   //    every entry from user mode, so both CPUs shared one per-CPU block.
   // 4. `cpu` and `proc` were __thread. That means per *thread*, so the compiler
   //    cached the thread pointer across calls -- but %fs here is per *CPU*, and
-  //    a kernel thread changes CPU at every sched(). See include/proc.h.
+  //    a kernel thread changes CPU at every sched(). See include/core/proc.h.
   // 5. The new per-CPU slots collided with syscall_entry's scratch word at
   //    %fs:(8), which is the same memory as %gs:8.
   //

kernel/core/panic.c

@@ -26,25 +26,25 @@
 // what tools/bootcheck.ps1 reads, and it is what you get when the crash happens
 // before there is a framebuffer at all.
 
-#include "types.h"
-#include "kbd.h"
-#include "x86.h"
-#include "defs.h"
-#include "gfx.h"
-#include "param.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "x86.h"
-#include "proc.h"
-#include "spinlock.h"
+#include "core/types.h"
+#include "dev/kbd.h"
+#include "arch/x86.h"
+#include "core/defs.h"
+#include "gfx/gfx.h"
+#include "core/param.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "arch/x86.h"
+#include "core/proc.h"
+#include "core/spinlock.h"
 // Purple, because the name says so, and white on it because nothing else is
 // legible at every brightness a monitor might be set to. The palette lives in
 // theme.h with everything else; this file used to keep its own copy under the
 // same names but with different values, which meant theme.h described a crash
 // screen nobody had ever seen.
-#include "theme.h"
-#include "logo.h"   /* LOGO_H -- the mark's height, for the layout below */
-#include "qr.h"
+#include "gfx/theme.h"
+#include "gfx/logo.h"   /* LOGO_H -- the mark's height, for the layout below */
+#include "gfx/qr.h"
 
 extern uint ticks;
 extern int  panicked;
@@ -431,7 +431,7 @@ paint(char *reason, addr_t *pcs, int npcs)
   if (y + LOGO_H + ch * 2 + body > foot)
     logo = 0;
 
-  // Shift, the system's own mark, from the same include/logo.h the loader
+  // Shift, the system's own mark, from the same include/gfx/logo.h the loader
   // splash and the boot console draw. It replaces Guru, a chamfered face that
   // lived only here and was drawn from primitives a few lines up this file.
   //
@@ -494,7 +494,7 @@ paint(char *reason, addr_t *pcs, int npcs)
   //
   // What replaces it is the thing nobody would guess: **this screen is no
   // longer the only copy.** The log survives into the next boot (see
-  // include/klog.h), so the right instruction on a crash screen is now
+  // include/core/klog.h), so the right instruction on a crash screen is now
   // "restart and read it" rather than "photograph this".
   //
   // Kept under about 45 characters each: the QR card is on the right, and the

kernel/core/qr.c

@@ -1,4 +1,4 @@
-// QR encoder. See include/qr.h for why it exists and why it is this small.
+// QR encoder. See include/gfx/qr.h for why it exists and why it is this small.
 //
 // Freestanding on purpose: no allocation, no floating point, no libc beyond
 // memset/memmove. It has to run in panic context, where the heap may be exactly
@@ -21,11 +21,11 @@
 #ifdef QR_HOST
 #include <string.h>
 #else
-#include "types.h"
-#include "defs.h"
+#include "core/types.h"
+#include "core/defs.h"
 #endif
 
-#include "qr.h"
+#include "gfx/qr.h"
 
 // ---------------------------------------------------------------------------
 // Version table

kernel/core/sbuf.c

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 //
-// The bounded string builder. See include/sbuf.h for what it is and why it
+// The bounded string builder. See include/core/sbuf.h for what it is and why it
 // moved out of kernel/dev/procfs.c.
 
-#include "types.h"
-#include "sbuf.h"
+#include "core/types.h"
+#include "core/sbuf.h"
 
 void
 sb_putc(struct sbuf *sb, char c)

kernel/core/sleeplock.c

@@ -1,14 +1,14 @@
 // Sleeping locks
 
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "x86.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "proc.h"
-#include "spinlock.h"
-#include "sleeplock.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/x86.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/proc.h"
+#include "core/spinlock.h"
+#include "core/sleeplock.h"
 
 void
 initsleeplock(struct sleeplock *lk, char *name)

kernel/core/spinlock.c

@@ -1,11 +1,11 @@
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "x86.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "proc.h"
-#include "spinlock.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/x86.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/proc.h"
+#include "core/spinlock.h"
 
 void
 initlock(struct spinlock *lk, char *name)

kernel/core/string.c

@@ -1,5 +1,5 @@
-#include "types.h"
-#include "x86.h"
+#include "core/types.h"
+#include "arch/x86.h"
 
 void*
 memset(void *dst, int c, uint64 n)

kernel/core/time.c

@@ -17,12 +17,12 @@
 // mid-update) so reading it on every gettimeofday would be absurd; and `ticks`
 // is a perfectly good interval clock once it has something to count from.
 
-#include "types.h"
-#include "defs.h"
-#include "x86.h"
-#include "date.h"
-#include "param.h"
-#include "spinlock.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "arch/x86.h"
+#include "core/date.h"
+#include "core/param.h"
+#include "core/spinlock.h"
 
 extern uint ticks;
 

kernel/core/uaccess.c

@@ -1,4 +1,4 @@
-// User-memory access helpers — see include/uaccess.h for the rules.
+// User-memory access helpers — see include/core/uaccess.h for the rules.
 //
 // Everything here validates against the *current* process's page table
 // (myproc()->pgdir), which is also the live CR3 while a syscall runs, so a
@@ -6,14 +6,14 @@
 // code for the remainder of the syscall (single-threaded processes can't
 // unmap it out from under us mid-call).
 
-#include "types.h"
-#include "defs.h"
-#include "param.h"
-#include "memlayout.h"
-#include "mmu.h"
-#include "proc.h"
-#include "errno.h"
-#include "uaccess.h"
+#include "core/types.h"
+#include "core/defs.h"
+#include "core/param.h"
+#include "arch/memlayout.h"
+#include "arch/mmu.h"
+#include "core/proc.h"
+#include "uapi/errno.h"
+#include "core/uaccess.h"
 
 int
 access_ok(addr_t uaddr, uint64 size)