Aster Kernel

Aster is a small, clean-room x86-64 educational kernel written in freestanding C11 and assembly. It boots with GRUB/Multiboot2, enters long mode, exposes an interactive ring-0 monitor, drives an emulated RTL8139 NIC, and contains a bounded polling stack for Ethernet, ARP, IPv4, UDP, DNS A records, and ICMP echo.

It is not Linux-compatible and is not a production operating system. The scope is intentionally narrow enough that the boot path, driver, packet formats, and failure handling can be reviewed end to end.

Implemented and source-verified

Area	Implementation
Boot	Multiboot2 header; 32-bit protected-mode entry; CPUID/long-mode checks; 64-bit transition
Paging	PML4 -> PDPT -> page directory; first 1 GiB identity mapped with 2 MiB pages
CPU state	x87 initialization; CR0/CR4 SSE enablement; default MXCSR loaded before C
Exceptions	64-bit IDT; vectors 0-31; normalized error frames; ABI-aligned C dispatch
Diagnostics	VGA text output, hardware cursor, scrolling, COM1 output/input
Input	Polled PS/2 set-1 keyboard plus serial input; bounded 128-byte command line
Boot metadata	Bounded Multiboot2 tag and memory-map traversal
PCI/NIC	Legacy PCI enumeration; RTL8139 port I/O; bus-master DMA RX ring and four TX buffers
Networking	Ethernet II, ARP cache/resolution, IPv4, UDP DNS queries, DNS A-record parsing, ICMP echo
Timing	Serialized TSC reads; PIT channel-2 calibration attempt with a fallback frequency

The supplied QEMU profile uses a fixed RTL8139 MAC and the standard user-network addresses 10.0.2.15/24, gateway 10.0.2.2, and DNS proxy 10.0.2.3.

See docs/ARCHITECTURE.md for the control and packet flows, invariants, and limitations.

Build requirements

Arch Linux / CachyOS:

sudo pacman -S --needed \
  base-devel clang lld qemu-system-x86 qemu-ui-gtk \
  grub xorriso mtools

qemu-ui-sdl can replace qemu-ui-gtk. A graphical UI module is not required for headless operation.

Ubuntu/Debian CI-equivalent packages:

sudo apt-get install \
  binutils clang grub-common grub-pc-bin lld make mtools \
  python3 qemu-system-x86 xorriso

Build and deterministic verification

git clone https://github.com/magetsu002/aster-kernel.git
cd aster-kernel
make clean check

make check is local and network-independent. It performs:

• a warning-free freestanding build with warnings treated as errors
• host-side malformed IPv4, DNS, ICMP, and address-parser tests
• ELF64 architecture, entry-point, segment, section, and symbol validation
• Multiboot2 placement, alignment, length, tag, and checksum validation
• rejection of dynamic/interpreter segments and undefined symbols
• load-range checks for the 1 GiB identity map and 32-bit DMA assumption
• repository artifact, ignore-rule, and README/Make-target consistency checks

Boot through GRUB and run the internal heartbeat in QEMU:

make smoke

make smoke waits for the serial monitor, sends ping aster, and requires four responses. It proves the boot path, console input, command dispatch, and network-independent timing workload; it is not an external ICMP test.

Interactive use

Graphical QEMU with automatic GTK/SDL/Cocoa detection:

make run

Terminal-only session:

make run-headless

Useful monitor commands:

help
sysinfo
mem
cpu
net
ping aster
ping 1.1.1.1
ping google.com

ping 1.1.1.1 and ping google.com exercise Aster's RTL8139, ARP, IPv4, ICMP, and, for hostnames, UDP/DNS code. Their success depends on QEMU user networking, host policy, and the remote endpoint, so external connectivity is not asserted by offline checks or CI.

Validation and CI boundary

GitHub Actions runs make clean check and make smoke. This verifies a clean build and an actual QEMU boot with the internal heartbeat. Public DNS and ICMP are manual integration checks and are reported only when observed in a specific environment.

Exception-6 case study

A startup failure reported x86 exception 6 (#UD) at an address in optimized C reached during network initialization. Compiler optimization can introduce XMM instructions for ordinary copy/clear loops even when the source contains no SSE intrinsics. The bootstrap had entered long mode but had not established the x87/SSE state expected by that generated code.

arch/x86_64/boot.S now clears CR0.EM/TS, sets CR0.MP, enables CR4.OSFXSR/OSXMMEXCPT, executes fninit, and loads MXCSR 0x1F80 before calling any C function. The debugging workflow and exact address-inspection commands are documented in docs/DEBUGGING.md.

Current limitations

• all commands and drivers execute in ring 0
• no allocator, userspace, scheduler, syscalls, VFS, or persistent storage
• static QEMU-specific IPv4 configuration; no DHCP
• no TCP, sockets, IPv6, or IP fragment reassembly
• polling keyboard and NIC paths; no NIC interrupts
• no SMP or hardware target beyond the current GRUB/QEMU x86-64 profile
• incoming nonzero UDP checksums are not yet verified
• failures can halt or crash the whole kernel because there is no isolation

These constraints are deliberate and documented rather than hidden.

Repository map

arch/x86_64/       boot, long-mode transition, IDT, exception stubs
kernel/            console, input, monitor, timing, PCI, RTL8139, protocols
include/aster/     kernel interfaces and hardware/protocol types
scripts/           ELF/repository checks, QEMU launcher, boot smoke test
tests/             host-side packet-parser boundary tests
docs/              architecture, debugging workflow, roadmap
grub/               Multiboot2 boot menu
linker.ld           linked image layout

License

MIT. See LICENSE.