The wiki is being retired!
Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!
This mechanism permits to test and recover from certain non-booting coreboot images.
This works by having two coreboot images in the same flash chip:
- One fallback/ image: The working image.
- One normal/ image: The image to be tested.
This feature is not widely tested on all boards. It also requires it to have a reboot_bits exported in the CMOS layout.
This also doesn't protect against human errors when using such feature, or bugs in the code responsible for switching between the two images.
- Test new images way faster: if the image doesn't boot it will fallback on the old known-working image and save a long reflashing procedure. Handy for bisecting faster.
- Test new images more safely: Despite of the recommendations of having a way to externally reflash, many new user don't. Still, this method is not totally foolproof.
- More compact testing setup: Since reflashing tools are not mandatory anymore, the tests can be done with less hardware, very useful when traveling.
How it works
Coreboot increments a reboot count at each boot but never clears it. What runs after coreboot is responsible for that.
That way, the count can be cleared by the OS once it's fully booted.
If a certain threshold is attained at boot, coreboot will boot the fallback image.
Because we uses two images, it's easy to wrongly identify which image booted:
- If the user mistakenly thinks the normal image is booting...
- But the fallback image always boots...
- And the normal image doesn't work...
- And the user flashes the normal in fallback because she thinks it boots fine...
- Then the user bricked her device and has to reflash it externally.
This scrpit takes an existing coreboot image path as argument.
The manual way
The most simple way to do it is to run the nvramtool commands below manually.
set-normal-0.sh has to be run:
- After the boot is completed and is declared a success.
- After the resuming is completed.
#!/bin/sh nvramtool -w boot_option=Fallback nvramtool -w reboot_bits=1
#!/bin/sh nvramtool -w boot_option=Normal nvramtool -w reboot_bits=0
#!/bin/sh nvramtool -a | grep -e boot_option -e last_boot -e reboot_bits
Here we use systemd to automatically reset the boot counter after each successful boot (or resume).
We are then supposed to use the normal image daily and only resort to fallback in case of issues.
First, in coreboot, install nvramtool with:
$ cd util/nvramtool $ make $ sudo make install
Then add the following systemd unit at their respective paths:
Then enable them with:
$ sudo systemctl enable email@example.com $ sudo systemctl start firstname.lastname@example.org $ sudo systemctl enable email@example.com $ sudo systemctl start firstname.lastname@example.org
- The user may wrongly identify which image booted, and because of that, end up reflashing a non-working image.
- Some issues can arrise when the nvram layout is not the same between normal/ and fallback/
- The number of failed boot is fixed at compilation time.
- In order to fully boot, some boards do reset conditionally during the boot process resulting in a non-predictable increment of the boot count.
- Example script exist only for systemd. Still, they are trivial to adapt to other init systems.
- Payloads sometime have fixed default locations when loading things from cbfs:
- When using grub as a payload, grub.cfg is at etc/grub.cfg by default, so if you want to test grub as a payload, remember to change grub.cfg's path not to interfer with the fallback's grub configuration.
- Changing the path of what SeaBIOS loads from cbfs is probably configurable with SeaBIOS cbfs symlinks but not yet tested/documented with the use of the fallback mecanism
- Tested boards need to be listed somewhere.
- Defined by CONFIG_MAX_REBOOT_CNT, typically 3