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
* `initramfs` -- the initramfs
* `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`.
init 2 years ago			`# 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
src/userspace: merge back into initramfs Previously ownerboot had separate `userspace` (the initramfs contents without kernel modules) and `initramfs` (the complete initramfs) expressions. This was done in order to allow the use of CONFIG_INITRAMFS_SOURCE, which links an initramfs image into the kernel itself. I did this because I was having a hard time getting coreboot to load a separate initrd on rk3399. I have since solved that problem, and am now using coreboot to load an initramfs on all platforms. There is no longer any need for this unusual separation. 1 year ago			* `initramfs` -- the initramfs
init 2 years ago			* `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`.