Platform System Interface Specification

Introduction

The Platform System Interface Specification, or psi-spec, is a collection of documents for hardware and software co-design from a general perspective. It describes how microprocessors can provide an environment for booting an operating system or otherwise bare-metal applications, typically starting from intermediate, rewritable code that initializes clocks, DRAM and peripherals, commonly referred to as boot firmware or platform initialization firmware.

In the following sections, psi-spec describes principles and abstractions that apply agnostic of vendors and products.

Mask ROMs and Loaders

Many SoCs have initial pieces of code baked into them to bootstrap the system. Some may call them boot ROMs, otherwise known as mask ROMs or Zero Stage Boot Loaders (ZSBL). They define a low-level access channel for development and would typically remain mostly the same over time for the same vendor, because change would mean cost. This initial code is designed to load the changeable application code from rewritable storages, such as SPI flash parts, SD cards, or eMMC, or possibly an internal reprogrammable memory part. Those stages are also referred to as platform initialization.

Mask ROM loaders may fall back to a mechanism allowing for talking to the SoC directly, e.g. via USB or UART. Because each vendor has their own implementation of such a mechanism, they also have their own software utilities that understand the respective protocol. With that software, one may read out chip information, perform MMIO access, transfer data into memory and execute it, set fuses, etc.

Generic protocols, variants and tools

• USB Device Firmware Upgrade (DFU)
  • STM32
  • usbd-dfu (written in Rust)
• fastboot
  • flashing instructions for Android development
  • U-Boot documentation on fastboot
  • fastboot host-side implementation in Rust

Vendor specific protocols and tools

• Allwinner: FEL mode, usable with
  • sunxi-fel
  • xfel
  • fel-cli
  • other tools exist
• Amlogic: (name unknown?), changed at least once over time (?)
  • pyamlboot
  • aml_boot
  • other tools exist
• Bouffalo Lab
  • bl_boot
• Canaan Kendryte
  • kendryte_boot
• Rockchip: TODO
  • rkflashtool
  • xrock
• Sophgo
  • sg_boot
• StarFive JingHong (JH)
  • jh_boot

Platform Initialization

Booting a rich, virtual memory operating system poses challenges. While modern machines may offer gigabytes or even terabytes of dynamic random access memory DRAM and extremely high speed peripheral buses in the range of gigahertz frequencies, they still start small with low amounts of static RAM and peripheral controllers in an uninitialized state.

Early platform firmware takes the responsibility to bring up DRAM and other controllers as needed to load and boot an operating system. Due to the high diversity of hardware, every SoC, SoM and mainboard comes with specific necessities.

Boot Flows

Since memory and storage parts can be complex, additional firmware and loaders are implemented in software. They would initialize the platform step by step, phase by phase, or stage by stage; projects differ in naming.

Note: oreboot and coreboot do not implement boot loaders to access external storage themselves. Instead, they provide options for payloads that could load a final OS or stand for themselves; it is up to the vendor designing a system with it. A boot block is only necessary for some specific platforms, and possibly CAR (cache-as-RAM). RISC-V does not have a term for this, since it is conceptually not necessary. Generic naming does not make much sense either, since different hardware platforms require some stages or not depending on their constraints. Nor does counting, due to different points of view: U-Boot, for example, starts counting backwards from its proper environment (the one offering a shell), to secondary and (rarely) tertiary program loader (SPL/TPL), while RISC-V starts counting forward, the mask ROM being the Zero Stage Boot Loader (ZSBL).

Note: Vendors may define artificial constraints in addition to their hardware limitiations. For example, AMD implements DRAM initialization in signed code that runs on a coprocessor before the main x86 cores come out of reset. Because the signatures of the binaries involved are verified, they cannot be customized by anyone but those who hold the signing keys, i.e., the vendor, unless ways to circumvent the verification are found. This is also true for many OEM products in general, where custom firmware is not part of the product design. I.e., it is protected against modification.

References

Arm platforms

• How Arm systems are booted
• U-Boot / Amlogic
• Arm secure boot chain on Ampere Altra
  • Armed to boot talk
  • Armed to boot blog post

RISC-V platforms

TODO

Boot Environments

A boot environment is the hosting system of a boot loader.

Boot processes may be interactive, or automatic, or static, set up in many ways.

The following table classifies various approaches with example implementations.

A boot environment may be configurable. Configuration may be changed at runtime, out of band, or at build time depending on the use case.

The following is a list of examples.

• U-Boot configuration
• UEFI NVRAM
• SeaBIOS (e.g., coreboot NVRAM)
• Boot Loader Specification
• GRUB configuration
• syslinux/extlinux configuration files
• PXE scripting/menu

Platform Security

In order to design a secure platform, each and every component in the boot process must be measured and/or verified. In addition, the platform in its entirety must be modeled so that only desired operations are permitted.

There is one essential question: Who can execute code where and when?

• when: which step/phase/stage in a boot flow chart (draw one)
• where: which component (can be hardware parts and software layers)
• who: owner, vendor, untrusted (w.r.t. owner) third party

Note: Third parties contracted by vendors are considered to be acting as controlled by the vendor here, regardless of practical issues with that.