bare-metal-bringup

Bare-Metal Bring-Up

Overview

Bringing up code on new silicon or a new architecture is a sequence of "does the most basic thing work yet" checkpoints. Each layer has a small number of mistakes that produce total silence or a single cryptic fault, and they are almost always init ordering, trap setup, address translation, or ABI mismatches.

Core principle: Get one character out the door first, then build up one checkpoint at a time. Until you have output, you are debugging blind, so the first job is always a working console, not the feature you wanted.

When to Use

• First boot on a new arch/board, or a port to a new target
• "Boots but hangs," silent boot, or a fault before main
• Traps/interrupts not firing, or firing into garbage
• Syscalls returning wrong values or corrupting registers across the boundary
• A driver works under one emulator/accelerator but not another (TCG vs KVM)

The Checkpoint Ladder

Climb in order. Don't debug a higher rung until the one below it is solid.

1. Earliest output. Poke the UART directly (no driver, no allocator). One known byte. If you can't get a byte, nothing else is debuggable.
2. Stack and BSS. A valid, correctly-placed stack and a zeroed BSS before any C/Zig/Rust runs. On some boots the stack must live inside a specific LOAD segment or the loader drops your initrd on top of it.
3. Trap/exception vectors. Install the vector table, prove it by taking a deliberate trap and returning. Get this working before timers or interrupts.
4. Timer. Architectural timer init MUST run before any kernel timer that divides by its frequency, or you divide by zero and panic with no output.
5. Address translation. MMU/PMP/page tables. Identity-map what you need, then enable. Wrong here means a fault the instant translation turns on.
6. Interrupts. Controller (PLIC/GIC/APIC), enable bits, the right per-IRQ vs global mask model for the part.
7. Userspace / syscalls. Drop to user mode, take a syscall, return cleanly without clobbering caller-saved-by-the-ABI registers.