Project Goals

This page summarises the design objectives of the Neutron bootloader.

Primary Goals

Educational use. Neutron is intended as a clear, minimal example of an ARMv8 bare-metal bootloader: exception level handling, peripheral setup, SD and FAT32 access, and kernel loading. The codebase is kept small enough to read and modify for learning.

Compatibility with real hardware. The design targets the Raspberry Pi Zero 2W (and Pi 3B) and uses the same peripheral base and key addresses as BCM2837/BCM2710. QEMU is used with the raspi3b machine so that development and testing match the real hardware layout.

Structured kernel loading. Kernels are delivered as packed images (NKRN format) with a fixed header (magic, version, load/entry addresses, size, CRC32, name). The bootloader validates the image and copies the payload to a known address, then passes a boot_info_t to the kernel in x0. This gives kernel authors a stable contract.

Non-Goals

• Generic virt machine: Neutron does not target QEMU’s generic virt machine. Addresses and peripherals are specific to the Raspberry Pi / raspi3b layout.

• Full firmware replacement: Neutron assumes the GPU has already loaded kernel8.img at 0x80000. It does not replace bootcode.bin or start.elf; it is the ARM kernel image that runs after the GPU hands off.

• Rich feature set: Features such as network boot, multiple kernel selection, or a shell are out of scope for the current design. The focus is on a single kernel loaded from the first FAT32 partition.

Success Criteria

A successful Neutron setup:

• Builds a kernel8.img that runs in QEMU raspi3b and on a Raspberry Pi Zero 2W (or Pi 3B) when placed on an SD card with the standard boot files.
• Loads a packed kernel (ATOM.BIN) from the SD card, validates it, and jumps to it with x0 pointing to boot_info_t.
• Provides serial output (UART) so that boot progress and errors can be observed.

See Kernel Development Guide for how to build kernels that satisfy this contract.