# 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