FPGA-Core/Tutorial/phase-19-linux-boot-contract/phase-19.md

Phase 19 - Linux Boot Contract

Context

Linux does not start from reset like bare-metal firmware. It expects a specific entry state, memory layout, device tree, and usually firmware services.

Goals

• Define the exact kernel entry ABI.
• Provide a device tree describing the SoC.
• Choose direct M-mode Linux or OpenSBI + S-mode Linux.

New Concepts

• Device tree: data structure describing hardware to the kernel.
• DTB: compiled binary form of a device tree source.
• SBI: Supervisor Binary Interface, firmware API used by S-mode kernels.
• OpenSBI: common RISC-V machine-mode firmware implementation.
• Hart: RISC-V hardware thread, roughly a CPU core/thread.

How To Think About It

This phase is about removing ambiguity before kernel bring-up. If the boot contract is wrong, Linux often just hangs early with little output.

Learning Tasks

• Read the RISC-V Linux boot protocol and list required register state.
• Draft a device tree matching your memory map and interrupt topology.
• Use the modern CPU ISA properties: riscv,isa-base = "rv32i" and riscv,isa-extensions = "i", "m", "a", "zicsr", "zifencei". Keep the legacy riscv,isa = "rv32ima_zicsr_zifencei" string only as a compatibility fallback.
• Decide whether the first Linux attempt uses direct M-mode or OpenSBI.

Pitfalls

• Passing the wrong DTB address in a1.
• Loading the kernel at the wrong alignment.
• Claiming device-tree compatibility with hardware you did not implement.

Tooling And Testing

• Validate DTS with dtc.
• Keep early console strategy simple and documented.
• Build small firmware checks that print boot parameters before jumping to Linux.

References

• RISC-V Linux boot protocol: https://docs.kernel.org/arch/riscv/boot.html
• RISC-V device-tree CPU bindings: https://www.kernel.org/doc/Documentation/devicetree/bindings/riscv/cpus.yaml
• OpenSBI: https://github.com/riscv-software-src/opensbi