Toyix is a small Linux-style teaching operating system written in C and x86 assembly. It currently boots as a Multiboot kernel through GRUB, initializes serial and VGA text consoles, installs early x86 descriptor tables, handles CPU exceptions and hardware IRQs, parses the Multiboot memory map, manages physical pages, enables an initial identity-mapped paging setup, adds a first virtual memory manager, provides an early kernel heap, and verifies boot behavior through automated QEMU smoke tests.
- Multiboot-compatible i686 kernel entry point
- Freestanding C kernel build
- Linker script placing the kernel at 1 MiB
- Serial console driver for automated test capture
- VGA text console driver for emulator output
- Flat ring-0 Global Descriptor Table setup
- Interrupt Descriptor Table entries for CPU exceptions 0-31
- Assembly ISR stubs with a shared C exception handler
- Kernel panic path for unrecoverable CPU exceptions
- Remapped 8259 PIC hardware IRQs
- PIT timer ticks with an interruptible idle loop
- Early PS/2 keyboard scancode echo driver
- Multiboot memory map parsing
- Bitmap-backed physical page allocator for 4 KiB frames
- PMM allocation/free sanity test during boot
- Identity-mapped 32-bit x86 paging for the first 16 MiB
- CR0, CR2, and CR3 helpers for paging setup and diagnostics
- Page-fault handler with CR2 fault-address reporting
- Paging sanity test during normal boot
- Virtual memory map/unmap/translate support with on-demand page table setup
- Early kernel heap with
kmalloc,kcalloc, andkfree - Heap block splitting, coalescing, statistics, and sanity checks
- QEMU test targets for boot, IRQ setup, timer ticks, PMM setup, paging setup, VMM setup, heap setup, deliberate invalid-opcode exception handling, and deliberate page-fault handling
- GitHub Actions CI for build and smoke test validation
arch/ Architecture-specific boot code
drivers/ Hardware-facing drivers
include/ Public kernel headers
kernel/ Core kernel code and small freestanding helpers
tests/ Smoke test scripts
articles/ Tutorial chapters
docs/ Project documentation and assets
The build expects an i686 ELF cross-compiler toolchain and common OS development tools:
i686-elf-gccnasmgrub-mkrescuemtoolsqemu-system-i386
The CI workflow builds the cross-compiler toolchain before running the project tests.
makemake isoThe bootable image is written to build/toyix.iso.
make runmake testRun the full local smoke suite:
tests/smoke.shRun only the deliberate CPU exception test:
make test-exceptionRun only the deliberate page-fault test:
make test-page-faultThe smoke suite builds the ISO, boots it under QEMU, captures serial output, verifies the expected early kernel, IRQ, PMM, paging, VMM, and heap messages, then rebuilds with a test-only invalid instruction path to verify CPU exception reporting and the panic halt path. The page-fault target separately rebuilds with a test-only unmapped memory access to verify page-fault reporting and the panic halt path.
Toyix is released under the MIT License. See LICENSE.