ownerboot/doc/architecture.md

Ownerboot Architecture

Nixpkgs

Nixpkgs is organized as a mutually-recursive package collection; the machinery for this involves lib.makeScope and callPackage.

Ownerboot

Ownerboot creates a second mutually-recursive package set containing all of the build products which go into the final flash image; this package set is what you see in src/default.nix:

• coreboot -- a Nix package for coreboot, since it is not in nixpkgs
• kernel -- the Linux kernel, using a custom (non-nixpkgs) expression
• userspace -- the userspace for the linux initramfs
• initramfs -- merges userspace with the boot-critical modules from kernel and wraps it in a properly-formatted cpio archive
• arm-trusted-firmware -- the ARM EL3 privileged routines
• fit -- generates a FIT payload
• iasl -- the Intel ACPI compiler

Many of these packages are simply customizations of the corresponding packages in nixpkgs. In spite of this, the ownerboot package set is not a scope-extension of any nixpkgs package set, in order to avoid future package name collisions as nixpkgs adds more packages (and present name collisions due to mistakes!).

Cross Compilation

Ownerboot is designed for cross-compilation as a first-class citizen. My arm64 laptop is fanless and lightweight but slow; I don't want to use it to build its own bootloader.

Terminology

Recall the GCC cross-compilation terminology:

• build: the platfrom doing the compiling
• host: the platform which runs the result of the compilation
• target: if running the result of the compilation emits code, the platform on which that code runs

Package Sets

When cross-compiling nixpkgs there will be (at least) two of these mutually-recursive package sets. Ownerboot instantiates them as:

• nixpkgsOnBuildForBuild: a copy of nixpkgs which executes on the build machine and emits code for the build machine
• nixpkgsOnBuildForHost: a copy of nixpkgs which executes on the build machine and emits code for the host machine

The ownerboot package set is host-independent; it contains only the code which is common across all hosts. Several essential inputs (for example, choice of coreboot version) are host-specific. The host-independent package set has throw "you must provide..." placeholders for these. If you attempt to build the host-independent package set, you will encounter these thrown exceptions.

Each host platform supported by ownerboot applies an overlay (i.e. overrideScope') to the host-independent package set. These overlays must replace all of the throw placeholders in order to produce a useful build artifact. There is one entry for each supported host platform near the bottom of src/default.nix.