oreboot

oreboot README

oreboot is a downstream fork of coreboot, i.e. oreboot is coreboot without 'c'.

oreboot is mostly written in Rust, with assembly where needed.

oreboot currently only plans to support LinuxBoot payloads.

Community

If you would like to get involved, join any of the following:

• the #oreboot channel in the OSFW Slack
• our Matrix community channel

Demos

• oreboot for ARM in QEMU
• oreboot for RISC-V HiFive Unleashed in QEMU

…

Rust Style

Follow the Rust style guide.

Rust Embedded

We build on top of the abstractions from the Rust Embedded Working Group's model with its crates and traits, detailed in their book.

In a nutshell:

Vendor support

SoC vendors are expected to provide documentation to their cores, peripherals and other blocks and/or their SVD files, so that we can generate the PAC and HAL crates, or ideally, the vendor should provide and maintain those as well.

If you are a vendor, we encourage you to get in touch with us, and look at the Embedonomicon that guides you through enabling Rust support for your SoCs.

The Rust Embedded book offers design patterns and implementation guidelines as well as a glossary to gain an understanding of the structure.

Boot Flow and Setup

To get a general understanding of how oreboot and firmware in general works, have a look at the boot flow documentation. It describes how firmware is stored and boots up on a platform / SoC.

Dilemma of drivers

Note that oreboot does not aim to turn into its own operating system. Accordingly, we intend to keep the amount and functionality of drivers low. However, by design of SoCs, we do have to implement something to load code:

• SPI flash, SD cards and eMMC are rather simple to load from, but require special mechanisms and tools to write to the storage part
• USB and ethernet are more flexible for development as they allow for loading code from another machine, but are more complex to implement
• UART is simple for data transfer, but very slow for larger payloads, such as a Linux kernel

In many cases, no full driver is needed, since we only need to e.g. read from storage, and we need no rich file systems. To avoid colliding with the needs and specifics of an OS, we recommend clearly separating storage parts holding the firmware and operating system, respectively. For example, put the firmware in a SPI flash and the OS on an NVMe SSD.

Getting oreboot

Clone this repo and enter its directory, i.e.:

git clone https://github.com/oreboot/oreboot.git
cd oreboot

Prerequisites

In general, you will need the following packages installed:

• device-tree-compiler
• pkg-config
• libssl
• rustup

For Debian based systems, there is a make target to install those, which pulls rustup through curl from https://sh.rustup.rs:

make debiansysprepare

Otherwise, install the package through your system package manager.

Setting up the toolchain

Regardless of your OS, you will need to install the toolchain for oreboot. This command only needs to be done once but it is safe to do it repeatedly.

make firsttime

Keeping build tools up to date

Each time you start to work with oreboot, or even daily:

cd oreboot
make update

You should definitely do this before reporting any issues.

Developing oreboot

There are two different things in the project:

1. src/mainboard/* the actual targets; those depend on and share crates, which can be drivers, SoC init code, and similar.
2. src/* everything else; these are the aforementioned crates

Adding a new platform

Looking at how other platforms are set up in order to aim for the same architecture is a good start. Be aware that oreboot is targeting bare metal, so there is no standard library available.

1. Create a new directory structure for the vendor and platform under src/mainboard/, e.g., mkdir -p src/mainboard/acme-silicon/soc-123/.
2. Add the sub directories bt0 for DRAM init and main for the main oreboot stage. Each stage needs at least
   • Cargo.toml to define the crate as usual
   • src/main.rs as usual for the entry point
   • build.rs for the linker script
   • .cargo/config.toml to define the target

For every stage, add a Makefile with the target build to get started, until it is fully integrated with the oreboot build system.

Add a convenience platform-level Makefile, which may contain custom targets, e.g., to create diagrams, or integrate with external tools, and otherwise builds the stages and adds headers or similar if necessary.

If possible, add a run target to run the bt0 stage immediately. Many SoCs have a mask ROM that can load code via USB or serial for doing so.

Formatting

We use dprint.

The configuration is in dprint.json. Edit it to upgrade plugins. For the exec plugin, see releases on GitHub.

The dprint version itself is maintained in the Makefile.

Building oreboot

To build oreboot for a specific platform, do this:

# Go to the mainboard's directory
cd src/mainboard/sunxi/nezha
# Build the mainboard target
make mainboard
# View disassembly
make objdump
# Run from RAM without flashing
make run
# Flash to the board
make flash

The root Makefile allows you to quickly build all platforms:

# build all mainboards
make mainboards
# build everything in parallel
make -j mainboards

Mainboards

Similar to coreboot, the structure in oreboot is per vendor and mainboard. Multiple architectures and SoCs are supported respectively, and their common code is shared between the boards. Boards may have variants if minor deviations would otherwise cause too much code duplication.

See src/mainboard/ for supported platforms, including src/mainboard/emulation/ for QEMU.

Previous Implementations

For reference, earlier approaches are documented. Have a look at those for x86 and Arm platforms and mainboards.

Parked for Revival

Earlier emulation targets have been parked in src.broken/mainboard/emulation/. They are supposed to provide a general understanding of each architecture that oreboot seeks to support:

• qemu-armv7
• qemu-aarch64
• qemu-q35

Ground Rules

• All code and markup is auto-formatted with make format with no exceptions. A CI check will tell if a change does not adhere to the formatting rules.
• There will be no code written in C. We write all code in Rust.
• We will not run our own Gerrit. We are using GitHub for now, and the GitHub Pull Request review mechanism.
• We will not run our own Jenkins. We will use the most appropriate CI; for now, that is GitHub, but we will be flexible.

Copyright and License

The copyright on oreboot is owned by quite a large number of individual developers and companies. Please check the individual source files for details.

oreboot is licensed under the terms of the GNU General Public License (GPL). Some files are licensed under the "GPL (version 2, or any later version)", and some files are licensed under the "GPL, version 2". For some parts, which were derived from other projects, other (GPL-compatible) licenses may apply. Please check the individual source files for details.

This makes the resulting oreboot images licensed under the GPL, version 2.