nebos)A from-scratch, freestanding 32-bit x86 hobby operating system written in C and x86 assembly. Single-author project (~7,000 SLOC, no external runtime, no libc). Targets i586 (first-gen Pentium); runs under QEMU or on real hardware.
Toolchain: gcc (32-bit multilib), as/ld/objcopy, mtools (mcopy/mkfs.fat), qemu.
make all # floppy.img usb.img final.bin root.img
make run # boot floppy.img + root.img in QEMU (fallback: qemu-system-x86_64)
make run-usb # boot usb.img as an IDE disk
make run-uhci # like `make run` but with a UHCI controller + USB mouse
make run-net # like `make run` + a PCI NE2000 NIC on QEMU's user network (slirp; DHCP/DNS/NAT)
make run-ahci # like `make run` + an ICH9 AHCI controller and a 512 MB SATA disk (sata0)
make test-usb # headless USB mouse/keyboard regression tests (QEMU + python3)
make clean
Makefile): -m32 -march=i586 -ffreestanding -fno-pie -nostdlib
-fno-stack-protector -mno-sse -mno-sse2 -mno-mmx -O2.root.img is a second FAT12 floppy holding user binaries (PROG.BIN, SPACE.BIN)
and test files; it requires mtools to build.make send PROGRAM=prog transfers a binary to a real machine over serial.boot.S — 512-byte boot sector (FAT16 BPB). Loads contiguous kernel sectors
to 0x7E00 (CHS for floppy, INT 13h AH=42h LBA for hard disk), jumps there.vesa_stage.S — real-mode VESA stage. Probes INT 15h E820 into 0x1000,
picks best VBE mode (≥16 bpp, LFB, fits VRAM, ≤1280px), writes mode info to
0x600, enables A20, enters protected mode, jumps to kernel_entry
(entry.S, re-points ESP to the current stack top, then kernel_main).kernel.c — kernel_main zeroes BSS then inits serial → I/O → idle → timer
(PIT 1 kHz + IDT) → mouse → processes → VGA shadow buffer → terminal.mbr.S — MBR (USB/HDD boot); loads partition boot sector at LBA 1.| Address | Purpose |
|---|---|
0x600 |
Boot framebuffer info (struct vga_boot_fb_info, see vga.h) |
0x7C00 |
Boot sector load address |
0x7E00 |
Kernel load / VESA-stage entry (kernel.ld) |
0x800 |
kexec trampoline (relocated at runtime; below the kernel) |
0x900 |
kexec flat GDT + GDTR (built at runtime; below the kernel) |
0x1000 |
E820 memory map (struct e820_map, written by vesa_stage.S, parsed by mm.c); also the kexec trampoline's private stack top (grows down, below the map) |
0x3000 |
UHCI frame list (1024 × 4 B, 4 KB-aligned; uhci.c) |
0x4000 |
ISA DMA buffer, one sector (disk.c) |
_end |
Kernel end (linker symbol; kernel.ld ASSERTs it stays below 0x7F000) |
| (in-image) | Bootstrap/protected-mode stack: 8 KB .stack NOLOAD section, __boot_stack_top/__boot_stack_bottom (travels with the kernel) |
0x7FF00 |
Program API struct (PROGRAM_API_ADDR, run_api.h) |
0x80000 |
Legacy ring-0 program load area (run.c, serial_recv.c, user.ld; max 0x6000, inside the reserved low 1 MB) |
0x100000 |
VGA shadow buffer (VGA_SHADOW_BASE, vga.h) |
Everything else is dynamic: process stacks and the kexec staging buffer come
from the frame allocator (≥ 0x900000), and the fallback stack pool is a
static BSS array. The kernel region itself only has one wall (_end
below the run area), so adding code no longer moves any address.
process.c/h, switch.S — ring-0 preemptive round-robin,
dynamically-sized process table (kmalloc'd, grows on demand), 20 ms timeslice,
ps/kill. Context switch happens in the PIT stub. Each process carries a
struct text_screen *screen output target (child processes inherit it, so
command output lands in the owning terminal). Exited processes are reaped and
their stacks freed by the scheduler.mm.c/h — INT 15h E820 detection (real-mode in vesa_stage.S,
map at 0x1000) + a bitmap page-frame allocator (4 KB pages). Reserves low
1 MB and an 8 MB VGA-shadow region. kmalloc.c/h — a power-of-two heap
allocator on top of the frame allocator (used for the process table). Process
stacks (≥ 0x900000) come from the frame allocator, with an 8-stack fallback
pool (a static BSS array; no fixed address).paging.c/h — identity-maps RAM (4 MB pages via CR4.PSE) + the
LFB (uncacheable) and enables CR0.PG/WP. A single shared page directory for
now (no per-process address spaces yet). The kexec trampoline
(kexec_tramp.S) clears CR0.PG before the copy so it can overwrite the old
kernel's page tables safely.wm.c/h — slot 0 runs wm_run(); fixed-size draggable
terminal windows (64×32) with a system bar (banner + purple "+ New" button +
clock + rainbow). Click-to-focus, drag-by-title-bar, close (×). The "+ New"
button and first boot spawn terminals; there is no term command.vga.c/h, vga_copy.S, gpu.c, ati.c, nvidia.c, nv50.c,
pci.h — VESA LFB + shadow buffer, 30 Hz dirty-row flush. ATI Mach64 CRTC
fixup; NVIDIA is VBE-only (never touch the legacy VGA CRTC). nvidia.c
identifies the card, maps BAR0/BAR1/BAR3 and reads the MCP7x stolen-VRAM
geometry; nv50.c probes the nv50-family display engine at boot (read-only,
serial/netmon). The ION/AT3IONT-I hardware cursor is deliberately not driven:
the VBIOS keeps the display engine (INTR_1 bit 8, 0x6194e8 = 0x803), EVO
DMA channels never fetch until nouveau's full takeover (which re-programs the
mode itself), the cursor staging registers are engine-only, and a channel
that has run cannot be restarted — see the header of nv50.c.fbtext.c, font_8x8.c/h, io.c/h, screen.c/h — 8×8 font,
framebuffer glyph blitting (fbtext_draw_cells) and per-terminal cell buffers
(struct text_screen).kdbg.c/h — framebuffer debug overlay (live status rows,
heartbeat, boot info rows, exception banner) for machines without serial; see
the kdbg section below.terminal.c — history, line editing (Tab completes command
names from the registry table and VFS paths via fat_list_dir), and a
table-driven command registry (cmds[]: name, usage, spawn kind/handler)
that drives dispatch, help and completion. Runs in a window
(term_run(struct term *)); reads keys from its per-terminal queue
(filled by the WM).fat.c (FAT12/16/32 read/write, device-parameterized),
vfs.c (mounts every FAT device under /), fatdetect.c/fatformat.c,
blkdev.c (floppy + IDE + SATA registry), ata.c (ATA PIO, either the
legacy ports or the PCI IDE interface's native BARs — ata_init_ports()),
disk.c (FDC + ISA DMA ch2, retries). sys_fs.c is the file service for
ring-3 commands: whole-file read/write, index-based directory listing, mount
listing, unlink/mkdir/rmdir. A FAT operation sets sys_fs_busy, which the
scheduler honours (no process switch during it): the FAT driver has static
state and the floppy still needs its IRQ. So expect a brief system stall
(not ticks — the PIT keeps running) while a command reads or writes a disk.ahci.c/h — polled AHCI driver (first controller only, PCI
class 01:06:01, no IRQs, no NCQ): port bring-up with COMRESET, IDENTIFY
(shared ata_identify_parse() with ata.c) and READ/WRITE DMA EXT through
a page-allocated bounce buffer (nothing large in BSS). Disks are registered
as sata0..sataN (named by AHCI port index) and mount like IDE disks
(sata0p1 for an MBR partition). >2 TB disks are clamped to 32-bit LBA;
a disk added after boot needs a rescan (no COMRESET hotplug).serial.c, serial_ring_buf.c/h, bin_recv.c/h, serial_recv.c,
serial_loop.c, send_serial.c — 16550 UART, IRQ-driven ring buffer, XMODEM.netdev.c/h — NIC driver registry (struct netdev, first probe
wins; drivers: r8168.c RTL8111/8168 (PCIe, polled, C+ mode) and ne2000.c
RTL8029 (QEMU/ISA)). net.c — ARP + ICMP echo, IPv4/UDP send + parse helpers,
shared ARP resolution (net_arp_resolve) and routing (net_next_hop), frame
decode, net_checksum()/net_checksum_tcp(). dhcp.c — minimal DHCP client
(DISCOVER →
OFFER → REQUEST → ACK; runs at boot when a NIC is present, 3 s budget, keeps
the static address when no server answers; dhcp re-runs it; learns the DNS
server from option 6). netcmd.c — the
netinfo/netrecv/netsend/netip/dhcp/pong/ping/netregs
commands. dns.c/h — a minimal resolver (one recursive A query over UDP,
name-compression aware; netdns shows/sets the server, host <name>
resolves). tcp.c/h — a minimal TCP client (connect/send/recv/close,
in-order receive, one segment of retransmit; the caller owns the NIC).
curl.c — the curl command: http://host[:port]/path GET with DNS, ARP,
HTTP/1.0 request and a dumped status/headers/body (no TLS, no redirects,
chunked decoded). Static IP default 192.168.178.240, mask/gateway learned
from DHCP (off-subnet traffic goes via the router).kexec.c/h, kexec_tramp.S, entry.S, bootstrap.c, and the
host-side kexec_send.c — reload the kernel over serial without rebooting
(C-light: reuses the current framebuffer, re-runs kernel_main).
The transfer entry is kernel_entry (entry.S), which re-points ESP before
any stack use: the jumping kernel's trampoline stack address comes from the
old build's memory map, so a reload between different maps (e.g. after the
kernel region grew) would otherwise land the stack inside the new image.
netkexec.c/h + host-side netkexec_send.c do the same over UDP
(make net-dev BOARD_IP=…): the WM loop auto-detects the header, the board
acks every datagram with the next expected offset, verifies the checksum and
jumps. While idle the same loop answers ARP/ICMP for our IP, so the board is
reachable (and MAC-resolvable) without running any command.mouse.c/h — cursor move/draw shared by the PS/2 path
(IntelliMouse, Cirrus/Radeon hardware cursor) and the USB backend;
usbhid.c/h — USB HID boot devices: find + configure a mouse and/or
keyboard, arm their interrupt endpoints, decode mouse reports and inject
keyboard scancodes, watch for plug/unplug.usb.c/h — controller-agnostic core: device enumeration,
descriptor parsing, hub recursion, bus scans, per-controller addresses, the
hotplug watcher and the interrupt-IN consumers (mouse + keyboard).
usb_hcd.h is the
host-controller ops vtable; uhci.c (I/O-port UHCI, frame list at
0x3000, one instance) and ohci.c (MMIO OHCI, up to 4 instances, HCCA +
ED/TD lists, polling) implement it. lsusb.c — the lsusb command (lists
every controller and its tree). The devices work on both controller types
and can be plugged in at any time (root-port connect-change watcher);
lsusb re-enumerates the bus, after which usbhid re-inits itself via a
scan generation counter.idle.c — mwait C-states, hlt fallback.run.c, run_api.h, prog.c, space.c — raw binaries at
0x80000, API function-pointer struct at 0x7FF00. prog/space are
embedded in the kernel image (prog_embed.o/space_embed.o, like
hello.elf), so make dev/make net-dev update them too and a board with
no readable filesystem can still run them: run <name> and the prog/
space commands use the embedded copy, run /<device>/<file> still loads
from FAT. Rebuilds are wired (space.c -> space.bin -> space_embed.o ->
kernel.elf). Note: full-screen programs draw over the WM, which keeps
repainting its desktop — running them windowed/cleanly is a follow-up.ucmd_*.c, ucmd_lib.h, ucmd.ld — freestanding
ELFs linked at USER_BASE (0x40000000), built by the Makefile, embedded
in the kernel image (*_embed.o) and listed as CMD_USER rows in the
terminal's command registry (cmds[] + ucmds[]). Moved so far:
cpuinfo, ls, cat, save, rm, mkdir, rmdir, meminfo,
mouseinfo, storage. They talk to the kernel through int 0x80
(syscall.h: putstr/ticks/sleep/exit, the whole-file service in
sys_fs.c and the small state snapshots in sys_info.c) and inherit the
terminal's screen, so their output lands in the owning window. New
commands: add ucmd_<name>.c, a CMD_USER row in cmds[], and a blob in
ucmds[] (the Makefile picks the file up via its ucmd_% pattern rules).
The one argument is passed as a C string on the top of the user stack
(process_create_user(..., arg)), so _start(const char *arg) needs no
crt0.cd [path], ls [path], cat <path>, save <path> <text>, rm <path>,
mkdir <path>, rmdir <path>, hello, reboot, poweroff, run <name>|<file>, space,
prog,
clock, colors, display, cpuinfo, mouseinfo, lsusb, lspci [id], peek <addr> [len], poke <addr> <val>, storage, meminfo, format <device>,
ps, kill <pid>, help, clear, serial test|recv, kexec, dbg.
Network: netinfo, netrecv, netsend, netip [a.b.c.d], dhcp (re-run the
DHCP client), pong (responds to ARP/ICMP for our IP for 30 s),
ping <host|a.b.c.d> (active ARP + ICMP echo with RTT; resolves DNS names,
goes via the gateway when the target is off-subnet), netloop (PHY loopback
TX/RX self-test), netreset
(full NIC re-init), netlog <text> (one UDP datagram to port 19290),
netconsole on|off|host <a.b.c.d> (the debug-output mirror, see below)
netregs (register dump, decoded ISR + counters), netdns [a.b.c.d] (show or
set the resolver) and host <name> (one DNS A query). curl <url> fetches
http://host[:port]/path with a minimal HTTP/1.0 GET and dumps the status
line, headers and body (no TLS, no redirects; numeric hosts skip DNS). On
boot, if a NIC is present, a DHCP client runs with a 3 s budget (requesting the
current address) and falls back to the static default when no server answers.
The board also answers ARP/ICMP for its IP while idle.
lspci lists every PCI function (one line each); with a filter (lspci 8168,
lspci 02) it also prints BAR details, type and size for matching functions.
peek <addr> [len] hex-dumps memory (identity map, so MMIO registers too).
poke <addr> <val> writes one 32-bit dword and prints the read-back (for
driving MMIO experiments from the shell).
Each terminal has a current working directory (shown in the prompt as [dir] >),
changed with cd; paths may be absolute (/floppy1/…) or relative (., ..,
nested). / is the read-only VFS root listing the mounted filesystems (the
filesystem commands operate inside a mount, e.g. cat /floppy1/HELLO.TXT).
cpuinfo, ls, cat, save, rm, mkdir, rmdir, meminfo,
mouseinfo and storage run as ring-3 processes (embedded ucmd_*.c); the
rest are kernel commands spawned as processes, or shell builtins (cd,
clear, help).
Develop without reflashing the floppy. The serial link (COM1 ↔ /dev/ttyUSB0)
runs at 115200 baud. Two paths exist:
"KXEC" magic and auto-spawns the reload, so make dev
alone boots a fresh kernel. The manual kexec command is kept as a fallback
that waits for the same image.bootstrap (one-time, zero-reflash) — a ring-0 program loaded through the
existing serial recv + run serial path that switches the UART to 115200,
receives a new kernel, and jumps into it. Used only to install the first new
kernel onto a machine still running an old (9600 baud) build; bootstrap.bin
is linked by bootstrap.ld at the old program address (0x4A000) because
that is where the old build's serial recv writes it.Wire protocol (host → target, sent immediately; no handshake):
[magic "KXEC"][entry u32 LE][size u32 LE][data][checksum u8].
Every iteration:
make dev # builds kernel.bin, computes kernel_entry via nm, sends
The reload is automatic. On boot the kernel prints Nebs OS v<version> booted
to COM1, so a serial monitor can confirm the new build headlessly:
make monitor # tail the serial line (picocom; Ctrl-A Ctrl-X to exit)
Run it in a second terminal, then make dev in the first — each reload prints
the ... booted line.
One-time install onto a 9600-baud machine (no floppy):
make bootstrap # builds bootstrap.bin
# 1) start the host sender first (it waits for 'R'):
./send_serial /dev/ttyUSB0 9600 bootstrap.bin
# 2) on the PC: `serial recv` (sends 'R'), then `run serial`
# 3) the bootstrap switches the link to 115200 and waits; send the kernel:
make dev # 115200
After the first kexec the machine is at 115200, and make dev is all you need
from then on.
Notes: the kexec path rebuilds a flat GDT at 0x900 before jumping (the old GDT
lives inside the overwritten kernel region), so it's safe to edit any file,
including vesa_stage.S/boot.S layout — but the video mode itself is only
re-applied on a full floppy/USB boot (C-light reuses the current LFB).
For boards without a serial console (the ASUS AT3IONT-I), the same reload runs over the network instead:
make net-dev # pushes kernel.bin to BOARD_IP (default 192.168.178.240)
make net-dev BOARD_IP=192.168.178.42
The board must be idle at a shell prompt: the WM loop polls the NIC, answers
ARP/ICMP for its IP, and auto-detects the "KXNU" header datagram (UDP port
19288). The host tool (netkexec_send.c) then does a stop-and-wait transfer:
the board acks every datagram with the next expected offset, verifies the
32-bit checksum and jumps. ~130 KB takes about a second on a wired LAN.
While a net command owns the receiver (netrecv/ping/netloop)
or a kexec is in progress, the auto-detect pauses.
The board's address comes from DHCP when a server is present (the DHCP client
runs at boot; netinfo shows ip/mask/gateway and the lease), so use
make net-dev BOARD_IP=<leased address> — or netip on the board to pin one.
make netmon)The serial console is mirrored to UDP port 19290, so a board without a serial
port gets the same visibility as make monitor:
serial_puts — driver bring-up trails, MTRR
dumps, kexec progress) andio_putstr — shell output, command
results, netrecv dumps)is buffered in RAM as it is produced and flushed from the WM loop as line-sized datagrams. On the host:
make netmon # builds + runs netmonitor (Ctrl-C to exit)
make netmon | tee board.log
./netmonitor 19290 # different port
The mirror is on by default and broadcasts; netconsole host <laptop-ip>
narrows it to one host (datagrams carry the broadcast MAC, so the board needs
no ARP entry for it), netconsole off/on toggles it, and netlog <text>
sends an ad-hoc line. Nothing is sent before the NIC is up, the producer
never blocks (a full buffer drops characters and reports it), and the flush
pauses while a net command owns the receiver.
usb.c is controller-agnostic; the drivers implement the usb_hcd_ops
vtable (usb_hcd.h): control transfers, root-port queries/reset, and two
interrupt-IN slots (0 = mouse, 1 = keyboard). usb_hcd_init() picks UHCI
when present, otherwise OHCI (ohci.c drives up to 4 instances — MCP79 has
four).
paging_map_mmio()), HCCA from the page allocator,
static 16-byte-aligned ED/TD sets. Control transfers run on the control
list (HcControlHeadED + CLF) and are polled via each TD's condition code
— a NAKed TD stays queued and is retried by the controller. Both HID EDs
(F = 0) are chained and referenced from all 32 HCCA interrupt-table slots,
so their TDs are serviced every frame. No IRQs and no DoneHead handling:
software just harvests retired TDs. TDs must be initialized with
CC = NotAccessed (0xF) — OHCI has no active bit, and a zero CC makes
software think a fresh TD already completed. TD data toggles are explicit:
DATA0 = 0x02000000, DATA1 = 0x03000000 (0 means "use the ED carry
bit"); a wrong value makes the first control transfer fail with a toggle
mismatch on real hardware while QEMU (which ignores toggles) is happy.
Control queues use a dummy TD as the tail anchor; the data stage is one
TD (the controller splits it into MPS-sized packets itself).0x3000, control QH + two more QHs
(one per interrupt slot) serviced every frame while the controller keeps
running. The PCI scan checks all functions (real PIIX3/PIIX4/VIA
layouts put the USB function at 0:07.2 / 0:01.2) and ignores controllers
whose BARs the firmware left unassigned. One instance only.usbhid.c): every HID (class 3) interface with an
interrupt-IN endpoint gets its own interrupt slot (USB_HCD_INT_SLOTS = 6).
Boot interfaces (subclass 1, protocol 2/1) are used as-is in boot
protocol; other class-3 interfaces are classified by reading their HID
report descriptor (a mouse/pointer collection or relative X/Y input is a
mouse, a keyboard collection is a keyboard; absolute pointers/tablets are
ignored). Composite devices (keyboard + mouse behind one receiver) and
several devices can therefore coexist; mouse reports from all slots are
merged. Mouse reports are 3 bytes (b0&7 buttons, signed dx/dy; HID's
+y is flipped to the PS/2 convention). Keyboard reports are 8 bytes
(modifier byte + 6 keycodes); they are diffed against the previous report
and decoded through a HID-usage → scancode-set-1 table (including 0xE0
extended keys), then injected with io_inject_scancode() so the
terminal/WM see exactly what a PS/2 keyboard would produce.
usbhid_poll() (from mouse_poll_update()) also runs the hotplug
watcher: root-port connect changes are enumerated (throttled to 250 ms),
CCS low or a few TD errors detach a device. A full scan (lsusb) bumps
usb_generation(), which makes usbhid detach and rescan, so lsusb
can't leave the devices dead. The BIOS PS/2 legacy emulation is
deliberately disabled (PCI config 0xC0) because the kernel now owns
these devices.ohci: / uhci: / usbhid: lines go to COM1 (and through the
netlog mirror on serial-less boards); mouseinfo shows the active mouse
backend and whether a USB keyboard is attached; usb.c's USB_DEBUG and
usbhid.c's USBHID_DEBUG (both default 0) add scan/report tracing.
Headless tests: make test-usb runs tools/qmp_cursor_test.py (injects
mouse motion with QMP input-send-event, verifies the cursor with
screendump) and tools/qmp_keyboard_test.py (types with QMP send-key,
verifies the screen output); both take mode flags (--uhci, --uhci72,
--multi, --hotplug).make net-dev still reloads the
kernel).dbg)A ring-0 debugger driven over the serial link. On the PC type dbg, then drive
commands from the host with make monitor (picocom):
r <addr> <len> read len bytes at addr -> hex dump
w <addr> <b0> [b1 ...] write bytes at addr
i <port> inb (read I/O port)
o <port> <val> outb (write I/O port)
h help
q quit
The monitor runs inline (blocks the terminal), so it owns the serial ring buffer
and doesn't conflict with the kexec auto-detect. Reading arbitrary physical
memory is safe (no paging); writing can corrupt the kernel, so the usual loop is
inspect → q → make dev a fresh build.
The terminal is framebuffer-only, so a headless QEMU gives you no easy way to
type commands or see output. The reliable workflow (used for lsusb) is to
temporarily mirror io_putchar to COM1, and to invoke the code under test
directly at boot — no keystroke injection needed:
io.c add #include "serial.h" and a
serial_putc(SERIAL_COM1, c); at the top of io_putchar. Every io_putstr/
io_putchar call (terminal prompt, echo, command output) now also lands on
COM1. serial_puthex/serial_putdec (serial.h) are available for structured
dumps inside drivers.kernel_main (e.g. usb_enumerate_and_print(); before terminal_run()), or
process_create(...) from terminal_run() to exercise the process context.
QMP send-key/input-send-event and HMP sendkey do not reliably reach
the PS/2 keyboard in headless/VNC-without-a-client mode, so don't script
keystrokes — script the call site instead.Run QEMU headless and read the log:
qemu-system-i386 -M pc \
-drive file=floppy.img,format=raw,if=floppy \
-drive file=root.img,format=raw,if=floppy \
-serial file:/tmp/opencode/serial.log \
-display none -vga std
# ...then: cat -A /tmp/opencode/serial.log
The Nebs OS v<version> booted line is already written to COM1 at boot, so
serial is live before the framebuffer is up — a crash in early init still shows.
Revert before committing — remove the io.c echo and any boot-time call;
git status should show io.c and kernel.c unchanged.
QEMU gotchas that bit once:
-M pc (QEMU ≥ 11) has no USB controller. The run-floppy
and run-usb targets therefore add -device pci-ohci -device usb-mouse
(the OHCI path, same controller type as the ASUS ION); make run-uhci runs
the same images with -device piix3-usb-uhci -device usb-mouse to exercise
the UHCI backend. To keep the controller but leave a device out (hotplug
test), drop it and use QMP device_add/device_del. A USB keyboard can be
added the same way (-device usb-kbd); QMP send-key then types on it
while the QEMU window's own keys still go to the PS/2 keyboard, so the dev
loop stays usable. Cross-check the guest's view of the tree with the
monitor info usb.pkill -f qemu-system-i386 matches your own shell command line (it contains
the string) and kills your script; use pkill qemu (process-name match) or
kill by PID.kdbg)For machines without a serial console (e.g. the ASUS AT3IONT-I), kdbg.c/h
draws a debug overlay straight into the VESA LFB, bypassing the shadow buffer
and the WM. It stays on screen even when the WM or the scheduler is wedged, so
a freeze can be diagnosed by reading/photographing the screen. This is how the
"freeze on first key press" was tracked down: the counters showed that no key
event ever reached the OS (all zeros) and the heartbeat stopped, i.e. the CPU
was wedged in firmware/SMM before IRQ1 was delivered.
Layout (bottom-left, and a heartbeat square bottom-right):
MTRRdef 00000E06 vcnt 8 <- boot info rows (yellow), up to 14
M0 b=00000000 m=FF000800 WB
...
WC=e7 b=FD000000 s=00800000
IRQ 12 SC 9C BY 12 OT 0 MK 0 <- live status row 1 (green)
WM 6 K 000A TRM 6 K 000A <- live status row 2 (blue)
Live status rows (bottom two, refreshed on key events and 1×/s):
IRQ — IRQ1 entries; SC — last scancode read from port 0x60; BY —
scancode bytes read (IRQ + polling); OT — dropped other/AUX bytes; MK —
1 if the IRQ1 storm guard tripped (IRQ1 masked; WM falls back to polling).WM n K xxxx — keys handed by the WM to the focused terminal; TRM n K xxxx
— keys consumed by term_run; K = last key value.Info rows (yellow, above the status rows) are boot-time diagnostics, e.g.
the MTRR dump from mtrr.c: MTRRdef = default-type MSR + number of variable
slots; M0..M7 = the BIOS's own MTRR entries as found at boot (- = free
slot; b/m = base/address mask; type UC/WB/WC/WT/WP); WC=eN ...
= the write-combining entry the kernel added in free slot N for the
framebuffer (or WC skipped: no free MTRR entry). An entry that already
covers the LFB base (left by a previous kexec boot -- variable MTRRs survive
a kernel reload) is reused instead of consuming another slot. Never overwrite
BIOS-populated MTRR entries — chipset/MMIO uncacheability (and the USB-legacy
SMM) breaks otherwise.
Exception banner: exc_handler() (kernel.c) calls kdbg_panic(), which
draws a red banner with vector name, EIP and CR2 at the top of the screen
(visible without serial) before the CPU halts. Faults from ring 3 do not halt:
the process is killed (with a short message in its terminal and on serial) and
the kernel keeps running.
API / wiring:
kdbg_init() — cache LFB geometry; call after vga_shadow_init().kdbg_status() — redraw the live rows; called from key paths and the PIT.kdbg_info(row, s) — set one of 14 info rows (row 0 = lowest, at
fb_h-31). Text is copied, so stack buffers are fine, and it is safe to
call before kdbg_init() (stored, drawn once the framebuffer is up).kdbg_info_alloc() — claim the next free info row (-1 when full); boot
subsystems (MTRR dump, NIC) take rows in init order without colliding.kdbg_pit_tick() — called from the PIT stub (switch.S); blinks the
heartbeat and refreshes the overlay every second.kdbg.c, bumped from io.c (kbd_irq,
io_poll_key_with_hw), wm.c (wm_handle_keyboard) and terminal.c
(term_run).Caveats:
0x7F000 boundary
(kernel.ld ASSERT).malloc, no printf. Use io_putstr /
io_putchar / io_puthex (io.h). Printing is VGA-framebuffer based.paging.c), so
physical == virtual everywhere. Still no per-process address spaces or process
isolation: everything runs ring-0 and shares the address space.vga_put_pixel_rgb etc.); a 30 Hz
flush copies dirty rows to VRAM. Full-screen programs call vga_clear_rgb..S, .c, and
linker scripts; changing one without the others breaks boot/loading.IRQ_RETURN_DS <cs_offset>
(irqret.inc), as switch.S, timer.S and syscall_stub.S do. QEMU does
not model this nulling, so a missing restore only fails on real hardware
(symptom: ring-3 #GP on its first data access, e.g. a store through a
pointer).serial_puthex (serial.c) uses "01234589ABCDEF" — digits 6 and 7 are
missing (bug).vga.c draw_flush_debug_square() — leftover debug artifact, still draws a
color-cycling 32×32 square in the corner on every flush.disk.c fdc_reset() and fdc_init_once() overlap/duplicate logic.run area (0x80000) and the program API at 0x7FF00 are the
last fixed low-memory addresses; moving prog/space to ring-3 would let
the whole block go (see the roadmap).