Home

K-ernel wiki

K-ernel is a 32-bit x86 (i686) operating-system kernel written from scratch, freestanding, booted through GRUB and Multiboot.

The README is the front door: what the project is, why GRUB, why the kernel sits at 1 MiB, the tree layout, the licence (GPL-2.0-only). It is bilingual (English / Italiano) and it is not repeated here.

This wiki is the part that ages: how to get a build running on your machine, what to do when it does not, where the plan is, and how to report something.

Where the kernel actually is

Phase 3 (interrupts) is in progress. What a build off main does today:

• boots from a GRUB-generated ISO through Multiboot, and checks the magic number GRUB left in eax (0x2BADB002);
• prints to the VGA text buffer at 0xB8000 (80x25, colours, scrolling) and logs to the COM1 serial port;
• has its own freestanding output layer: kprintf/ksnprintf, log levels, selectable output channels, and string/memory helpers;
• installs a GDT with kernel and user code/data segments plus a TSS;
• installs an IDT with all 256 gates: 48 of them have a stub behind them (the 32 vectors the CPU reserves for its own exceptions, plus the 16 the PIC was remapped onto), and the remaining 208 are deliberately left not present, so an unexpected vector faults instead of jumping into nothing;
• remaps the 8259A PIC pair off the exception vectors, onto vector 32 and up, and leaves every line masked until a driver claims one;
• programs the 8254 timer at 100 Hz on IRQ 0 and enables interrupts, with a 64-bit tick counter a 32-bit machine can read without ever catching it half updated. Every boot proves the tick really arrives before going on; the rate itself was measured once against a real clock, 3900 ticks in 39.000 s;
• turns an unhandled exception into something readable instead of a reset: the vector with its Intel mnemonic, a full register dump, then a halt;
• runs a self-test suite at every boot, which asks the hardware what it actually loaded (cs, tr, sgdt, sidt, a real int3) rather than re-reading what the kernel wrote to memory. Every suite prints a pass count, and the run ends with a single verdict line.

What does not exist yet, so nobody goes looking for it: no paging, no heap, no user space or ring 3, no scheduler, no filesystem, no shell, no keyboard input. The timer is the only device with a handler behind it; every other interrupt line is masked.

How this wiki is organised

• Building and running — the Docker toolchain, why the image is pinned to linux/amd64, every make target and the QEMU command it runs.
• Troubleshooting — the failures a newcomer actually hits: hidden warnings, a stale ISO, a monitor read too early, Docker not running, an editor full of imaginary errors.
• Roadmap and status — the phases, what is closed, what the phase in progress still contains, and the GitHub milestones.
• Reporting issues — what makes a report usable, and what the labels mean (including what a security label does not mean).

Links

• Repository
• Issues
• Milestones