linuxboot/book

LinuxBoot book which contains the documentation in markdown format

linuxboot

The LinuxBoot project allows you to replace your server's firmware with Linux.

Supported server mainboards

• qemu emulated Q35 systems
• Intel S2600WF
• Dell R630
• Winterfell Open Compute node (works well)
• Leopard Open Compute node (works well)
• Tioga Pass Open Compute node (works well)
• Monolake Open Compute node (not tested)

Build instructions

Make sure you have installed the dependencies uuid-dev, nasm, and acpica-tools (or equivalent for your distribution).

You need to provide:

• The vendor UEFI firmware for the mainboard
• A Linux kernel built with the CONFIG_EFI_BDS option enabled
• An initrd.cpio file with enough tools to kexec the rest of the system.

For the initrd, the Heads firmware or u-root systems work well. Both will build minimal runtimes that can fit into the few megabytes of space available.

For everything except qemu, you'll need to copy the vendor ROM dump to boards/$(BOARD)/$(BOARD).rom. Due to copyright restrictions, we can't bundle the ROM images in this tree and you must supply your own ROM from your own machine. qemu can built its own ROM from the edk2 tree, so this is not necessary.

Configure the build system:

cp path/to/s2600wf.rom boards/s2600wf/
make \
	BOARD=s2600wf \
	KERNEL=../path/to/bzImage \
	INITRD=../path/to/initrd.cpio.xz \
	config
make

This will write the values into the .config file so that you don't need to specify them each time. If all goes well you will end up with a file in build/$(BOARD)/linuxboot.rom that can be flashed to your machine. It will take a while since it also clones the LinuxBoot patched version of tianocore/edk2 UDK2018 branch and build it.

Emulating with qemu

If you want to experiment with LinuxBoot you can run it under qemu. No ROM file is necessary, although you still need a Heads or NERF runtime kernel/initrd pair. You can launch the emulator by running:

make run

This will use your current terminal as the serial console, which will likely mess with the settings. After killing qemu by closing the window you will need to run stty sane to restore the terminal settings (echo is likely turned off, so you'll have to type this in the blind).

Adding a new mainboard

Copy Makefile.board from one of the other mainboards and edit it to match your new board's ROM layout. The qemu one is not the best example since it has to match the complex layout of OVMF; most real mainboards are not this messy.

You'll need to figure out which FVs have to be preserved, how much space can be recovered from the ME region, etc. The per-board makefile needs to set the following variables:

• FVS: an ordered list of IFD, firmware volumes and padding
• linuxboot-size: the final size of the ROM image in bytes (we should verify this against the real ROM instead)

More info

• https://www.linuxboot.org/
• https://trmm.net/LinuxBoot_34c3

book's Issues

refresh references

Over time, people have presented on LinuxBoot, e.g.:

• https://sysadmin.miniconf.org/2021/lca2021-Naohiro_Tamra-LinuxBoot_AArch64.pdf

elaborate intro to utilities

With #71, we created the base README on utilities.
We have a lot to cover here, and reference utk, dut, etc, plus third party tools such as me_analyzer et al that all contribute to LinuxBoot based projects.

Likely errant backtick in implementation/README.md

I believe the following line should be removed:

book/implementation/README.md

Line 53 in 5d95247

`

add notes on architectures

We need to add a statement on architecture support.

Just a little "works on all architectures supported by Linux with kexec" will do, with a list of exampleds, "such as RISC-V, Arm, Arm64, and x86".

It might be better to have a "known good" specific list, and add "may work on other architectures supported by Linux".

Notes on cmdline

The cmdline determines a good bunch of things, such as finding the initrd and where console output goes.

Those are crucial to understand to avoid blank screens and frustration.
Try asking a search engine or forum "why is my screen blank" - it is hard to figure out.

console=ttyS0 is common, though some platforms, e.g. som Arm based ones, may require a driver specific tty, such as ttyAMA0.

Create getting started chapter

Here are some thoughts:

• A version of the getting started guide using qemu.
• A version of the getting started guide using hardware. Exactly which piece of hardware this would be is undecided, but the requirements are:
  • cheap
  • easy to buy and ship online
  • has a reasonably sized flash chip
  • has a programming header and is easy to reflash
• An accompanying presentation which follows the same format for use in workshops and on-boarding.

Fix netlify

Netlify has been broken on all the pull requests

Treat documentation as code

https://lwn.net/Articles/963037/

QEMU localboot cannot see block devices

Hi team,
I got the complete build instructions working and able to run in qemu. I get as far as the "Systemboot" text art and then a boot loop starts. First fbnetboot is tried ( I don't have network configured ) and then sit0 and then localboot, which I am trying to get to work, by attaching an .iso as a cdrom device to the qemu command line.

madhan@madhan-HP-Notebook:~/coreboot$ sudo qemu-system-x86_64 -M q35 -enable-kvm -bios build/coreboot.rom -m 1024 -object rng-random,filename=/dev/urandom,id=rng0 -vga cirrus --serial /dev/tty -cdrom ./ubuntu-18.04.3-live-server-amd64.iso

However it seems like no block devices are seen. I tried attaching a scsi device, a block device and an usb device (all qcow2 image files that I could get to work in "HEADS" earlier) but same result. Also the uroot shell does not have lspci, lsmod, insmod etc. and so I am not able to look at the devices enumerated. But firstly, how do I know the tinylinux payload that we built got control or not? Should we dig into this on the uroot side or the tinylinux side? Any pointers please?

2019/12/02 16:02:19 Running boot command: [localboot -grub -d]
2019/12/02 16:02:19 Getting list of supported filesystems
2019/12/02 16:02:19 Supported file systems: [ext3 ext2 ext4 iso9660 udf]
2019/12/02 16:02:19 trying to mount all the available block devices with all the supported file system types
2019/12/02 16:02:19 mounted: []
2019/12/02 16:02:19 No boot configuration found
2019/12/02 16:02:19 Error executing &{/bbin/localboot [localboot -grub -d] []  <nil> 0xc00000e020 0xc00000e028 [] <nil> 0xc0000db2f0 exit status 1 <nil> <nil> true [0xc00000e148 0xc00000e020 0xc00000e028] [0xc00000e148] [] [] 0xc0000708a0 <nil>}: exit status 1

Thanks,
Madhan

Build error. Says "not enough arguments"

Hi Team,
I just started on u-root with a focus on Linuxboot. I am not familiar with Go language. I am also new to Linux. At this point everything is pretty much "learn as you go" for me :-) I am following instructions from https://github.com/linuxboot/book/blob/master/coreboot.u-root.systemboot/README.md

When I reach the command "u-root -build=bb core github.com/systemboot/systemboot/{uinit,localboot,netboot}" it fails with an error "not enough arguments". See below the full terminal output. Any pointers please?

madhan@madhan-HP-Notebook:~/work$ u-root -build=bb core github.com/systemboot/systemboot/{uinit,localboot,netboot}
2019/11/19 17:08:52 Disabling CGO for u-root...
2019/11/19 17:08:52 Build environment: GOARCH=amd64 GOOS=linux GOROOT=/usr/local/go GOPATH=/home/madhan/work CGO_ENABLED=0
2019/11/19 17:08:54 Filename is /tmp/initramfs.linux_amd64.cpio
2019/11/19 17:09:53 error building: error building go package in "/home/madhan/work/src/github.com/u-root/u-root/bb": # github.com/systemboot/systemboot/pkg/bootconfig
../../../systemboot/systemboot/pkg/bootconfig/bootconfig.go:93:27: not enough arguments in call to multiboot.Load
have (bool, string, string, []string)
want (bool, string, string, []string, *ibft.IBFT)
, exit status 2

Thanks in advance,
Madhan

rework setup for book deployment

We are currently using plain GitHub pages, which is rather simple, but missing essential features such as navigation from chapters.

There are modern tools that integrate with GitHub.
For the LinuxBoot website, we are currently using Hugo.

For the book, this looks like a promising option, being used for multiple books in the Rust ecosystem already: https://github.com/rust-lang/mdBook

intro to LinuxBoot implementation

the current chapter is an example of reworking a given hardware+firmware design by replacing DXEs

move that to its own file, and write an introductory chapter

• elaborate on how LinuxBoot is a concept and many implementations are possible to cover different use cases
• discuss hooking into an existing platform vs design from scratch
• reference the implementation examples

How to export the book as pdf format？

ATT

concept for graphical environments

Current Linux desktop distros mostly expect a UEFI environment.

Generally, u-root can execute a PE32, all the code is there:
https://github.com/u-root/u-root/blob/main/pkg/boot/bzimage/header.go#L279

Problems arise when some service or an EFI framebuffer etc is expected.
Let's say we do our LinuxBoot with native Linux DRM for graphics. Then we execute a distro kernel with its initrd, and that tries to draw on the EFI framebuffer, which does not exist. So the screen goes blank.

One approach is adding edk2 as an intermediate payload again, creating a bunch of ping pong.

Some minimal tables for a basic UEFI would work.
Should we meet on that medium ground, similar to Arm style Base Boot Requirements?
We could add this to u-root or as a standalone tool.
It wouldn't be hard to write those few structs somewhere in memory, at least.

list petitboot as an implementation example

https://github.com/open-power/petitboot

prominently uses kexec :)

uefi shell---->bzimage fail

When I replaced the UEFI shell with the linux-4.19.6 compiled bzimage according to the example, I entered the server and then entered the uefi shell and displayed a black screen，why？

Update u-root URL

URL for u-root in the README points to https://u-root.tk/. Should point to https://github.com/u-root/u-root.

I can submit a PR if that's easier.

Decided on the chapters and organization/flow of the book

tioga.rom

Is there any way to obtain 'tioga.rom' these days? It seems like Wiwynn no longer sells Tioga Pass servers mentioned in the case study.

Oreboot Chapter

Link the book from linuxboot.org

This should wait until we have some more substantial introductory material and a getting started guide.

Cleanup u-root chapter

This was an import of Ron's u-root paper from some time ago. The writing is already great, but a few things have to change:

• Fix the formatting (it got converted from tex to markdown and a few things are still off)
• Update to the present since the paper was a few years old
• Sort out the references section

Nicely format the main README.md

Don't repeat yourself

Hi,

this book contains lot of redundant information. I feel like I've read the sentence "packages are built and installed, typically in a fraction of a second." a gazillion times, even in consecutive paragraphs.

I wished it was more concise. Please excuse the harsh words, but this documentation is wasting precious developer time.

UTK Chapter

Cleanup the table of contents

What is the currently the "table of contents" should also serve as a landing page for the book as a whole. It should also include an introduction (a couple short paragraphs) and acknowledgements.