facebookarchive / osf-builder

osf-builder contains tools to build OSF (Open System Firmware) firmware images, and to keep track of their versioning information.

OSF Builder

This osf-builder repo is an open source repo to faciliate the development community to collaborate on Open System Firmware (OSF).

Build pre-requisites

• GNU make
• Go 1.x

Build process

OSF boot starts with coreboot first, then Linux kernel which then executes init, which in this case is provided by u-root.

OSF build also consists of these three stages, executed in the reverse order.

Entire build requires PLATFORM to be defined, this specifies the platform for which build is being run.

• getdeps is a tool used to fetch dependencies. It can clone Git repos, fetch files, etc.
  • It is configured by a JSON file that must be specified in CONFIG.
  • CONFIG consists of three top-level sections: initramfs, kernel and coreboot that specify what to fetch for each of the stages.
• Initramfs image is built first, by building u-root with certain set of commands.
  • initramfs section of the CONFIG is executed by getdeps to fetch the u-root sources and the Go toolchain.
  • PATCHES_DIR/initramfs-PLATFORM-* patches are applied.
  • Default set of commands can be found in Makefile.inc UROOT_BASE_CMDS, it can be augmented with UROOT_ADDITIONAL_CMDS or replaced entirely.
  • Additional commands can come from u-root itself or from external packages, in which case UROOT_ADDITIONAL_GOPATH may be required.
  • Initramfs can embed binary utilities, files can be added through UROOT_ADDITIONAL_FILES as local_path:initramfs_path pairs.
• Kernel is built next
  • kernel section of the CONFIG is executed by getdeps to fetch the kernel source.
  • PATCHES_DIR/kernel-PLATFORM-* patches are applied.
  • KERNEL_CONFIG is used as .config.
• Coreboot is built last
  • coreboot section of the CONFIG is executed by getdeps to fetch the source and toolchain dependencies.
  • PATCHES_DIR/coreboot-PLATFORM-* patches are applied.
  • COREBOOT_CONFIG is used as .config.
  • Resulting flahs image is written to osf-PLATFORM.rom in the current directory.

How to build the sample project

• Clone the repo.
• cd examples/qemu
• Run make
• Once the build is completed, run make run, it will start a VM with the OSF BIOS image.

Development tricks

• To speed up builds, when not actively working on initramfs or the kernel, pass ALWAYS_BUILD_INITRAMFS=0 and ALWAYS_BUILD_KERNEL=0 respectively.
  • make ALWAYS_BUILD_INITRAMFS=0 ALWAYS_BUILD_KERNEL=0 - for hacking on coreboot only.
• make clean will clean all the components without wiping the work done by getdeps.
  • make clean-coreboot and make clean-kernel will clean just the coreboot and kernel components.
• make wipe will wipe everything, including downloaded deps.
  • make wipe-coreboot and make wipe-kernel will clean just the coreboot and kernel components.
  • Note that toolchain cache survives wipe and will be used in the next build.

License

OSF Builder is MIT licensed, as found in the LICENSE file.

osf-builder's Issues

Add local file and git repo support for getdeps

For osf-builder developers at home, it would be nice to be able to cache dependencies on a local filesystem and use those to override URLs. That will save time downloading large files and codebases (e.g. kernel tarball, coreboot git repo) and will put less stress on third party servers.

Build coreboot in the background with everything else

Building coreboot's toolchain is the longest part of the build process, and much of it involves running serialized steps (e.g. decompressing archives, running configure, etc). We should be able to kick this off while u-root and Linux are being built.

In case coreboot somehow gets built first, we can avoid the race condition by building coreboot with a stub as the LinuxBoot payload and then insert the final Linux+u-root binary using cbfstool in a separate step at the very end.

Add support to let PLATFORM add/customize it's own VPD variables

It would be nice if we can let each PLATFORM customize their own VPD variables. Right now Makefile.inc adds internal_versions and firmware_version to VPD variables, for each platform it may want to add more such as fsp_log_enable, coreboot_log_level .,etc.
$(VPD_TOOL) -f "$<" -O -i RO_VPD -s internal_versions="cat $(FINAL_CONFIG_OUT)"
[ -z "$(VERSION)" ] || $(VPD_TOOL) -f "$<" -i RO_VPD -s firmware_version=$(VERSION)

Maybe running a script provided by the PLATFORM for this VPD customization or by other approaches.