Skip to content

OpenSBI, Linux & FDT Boot Specification

1. External Artifacts

  • BIOS: Real OpenSBI executable firmware image.
  • Kernel: Real Linux kernel image matching machine ISA, device tree, and boot protocol.
  • Disk: Real ext4 rootfs containing bootable userspace and network tools.

Example relative paths: artifacts/firmware/opensbi.bin, artifacts/kernel/Image, artifacts/disk/rootfs.ext4. None of these files may be committed to Git.

2. Image Formats and Loading

  • BOOT-REQ-001: CLI must explicitly support BIOS and kernel file formats; guessing ELF or raw based solely on filenames is prohibited.
  • BOOT-REQ-002: Validate file size, target range, overlap, RAM capacity, and address overflow before loading.
  • BOOT-REQ-003: Raw images are loaded at frozen fixed addresses; if ELF is supported, ELF64, little-endian, RISC-V, program header permissions, and ranges must be verified.
  • BOOT-REQ-004: Disk is not loaded wholesale into RAM, but bound by the VirtIO-Blk backend.

BIOS, kernel, FDT, and stack/reserved regions must not overwrite each other. Specific addresses are written to a unified machine configuration source after standard baseline freezing.

3. Reset and OpenSBI Entry

  • Initial Hart ID is 0.
  • Reset enters M-mode, with PC pointing to Boot ROM trampoline or spec-defined OpenSBI entry point.
  • Set a0=hartid and a1=FDT physical address per RISC-V boot ABI.
  • Remaining registers and CSRs adopt recorded reset values.
  • If ROM trampoline is used, its machine code must be generated by controlled builds or clean encodings, rather than fake firmware printing banners.

4. FDT Contents

  • BOOT-REQ-005: Generate a legal Flattened Device Tree completely consistent with the actual machine model.
  • Root node contains compatible strings, address/size cells, and model information.
  • /cpus describes single hart, RV64 ISA string, MMU type riscv,sv39, and timebase-frequency.
  • memory node describes 0x80000000 and real RAM size.
  • chosen node configures correct stdout-path and kernel command line.
  • soc node describes CLINT, PLIC, UART, two VirtIO MMIO windows, and interrupt connections.
  • reserved-memory or memreserve protects regions required by FDT/firmware reservations.

ISA string must not declare un-implemented extensions. PLIC contexts, source IDs, and device interrupts must share configuration facts with implementation.

5. Linux Kernel Configuration Requirements

Build configuration must contain at least:

  • RV64, MMU, Sv39, SMP disabled or compatible with single hart.
  • RISC-V SBI, PLIC, CLINT/timer.
  • 8250/16550 serial and device tree console.
  • VirtIO MMIO, VirtIO Block, VirtIO Net.
  • ext4, devtmpfs, proc, sysfs, and necessary network protocols.
  • Userspace tools and DNS configuration required by DHCP client.
  • C/F/D/V extension configs must match actual implementation and toolchain.

Precise .config can be committed as reproducible text; generated kernel binaries must not be committed.

6. Kernel Command Line

Specify clearly at least: console device, root device, rootfstype, read-write policy, and early logging options. Device enumeration must be stable, and target root device should correspond to VirtIO-Blk. Debug parameters must not mask device failures or skip normal drivers.

7. rootfs Requirements

  • ext4 filesystem is intact and consistent with block device capacity.
  • Provides init, Shell, mount scripts, device node management, and network tools.
  • Contains dhclient or PRD-confirmed equivalent commands; since PRD explicitly names commands, dhclient must be provided by default.
  • Contains ping, DNS resolver configuration, and necessary dynamic libraries; if static BusyBox is used, verify command behavior satisfies acceptance.
  • Accounts and login policies suit local educational environments, containing no real keys or credentials.

8. Acceptance Criteria

  • FDT can be decompiled and verified by dtc or equivalent formal tools without address/interrupt conflicts.
  • OpenSBI detects hart, platform, clock, and next-stage entry.
  • Linux detects RAM, PLIC, UART, VirtIO-Blk, and VirtIO-Net.
  • rootfs mounts normally and enters Shell, without using initramfs to fake ext4 disk acceptance.
  • All artifact versions, configurations, sources, and SHA-256 logs are reproducible.