1.29. Reboot Mode¶
To simplify debugging, many BootROMs sample registers that survive a warm reset to customize the boot. These registers can e.g. indicate that boot should happen from a different boot medium.
Likewise, many bootloaders reuse such registers, or if unavailable, non-volatile memory to determine whether the OS requested a special reboot mode, e.g. rebooting into a USB recovery mode. This is common on Android systems.
barebox implements the upstream device tree bindings for reboot-modes to act upon reboot mode protocols specified in the device tree.
The device tree nodes list a number of reboot modes along with a magic value for each. On reboot, an OS implementing the binding would take the reboot command’s argument and match it against the modes in the device tree. If a match is found the associated magic is written to the location referenced in the device tree node.
1.29.1. User API¶
Devices registered with the reboot mode API gain two parameters:
$dev_of_reboot_mode.prev(read-only): The reboot mode that was set previously to barebox startup.
$dev_of_reboot_mode.next: The next reboot mode, for when the system is reset. Its initial value after startup is 0 which corresponds tonormalby default.
The reboot mode driver core use the alias name if available to name
the device. By convention, this should end with .reboot_mode, e.g.:
/ {
aliases {
gpr.reboot_name = &reboot_name_gpr;
};
};
Reboot mode providers have priorities. The provider with the highest
priority has its parameters aliased as $global.system.reboot_mode.prev
and $global.system.reboot_mode.next. After executing the init scripts,
barebox startup will source /env/bmode/${global.system.reboot_mode.prev}
if available. Example usage:
gpr.reboot_mode=serial reset -w
1.29.2. Reset¶
Reboot modes can be stored on a syscon wrapping general purpose registers that survive warm resets. If the system instead did reset via an external power management IC, the registers may lose their value.
If such reboot mode storage is used, users must take care to use the correct
reset provider. In barebox, multiple reset providers may co-exist. The
reset command allows listing and choosing a specific reboot mode.
For communication with the SoC’s BootROM, a warm reset can be triggered
with reset -w if a suitable reset handler has been registered.
1.29.3. Disambiguation¶
Some uses of reboot modes partially overlap with other barebox functionality. They all ultimately serve different purposes, however.
1.29.3.1. Comparison to reset reason¶
The reset reason $global.system.reset is populated by different drivers
to reflect the hardware cause of a reset, e.g. a watchdog. A reboot mode
describes the OS intention behind a reset, e.g. to fall into a recovery
mode. Reboot modes besides the default normal mode usually accompany
a reset reason of RST (because the OS intentionally triggered a reset
to activate the next reboot mode).
1.29.3.2. Comparison to bootsource¶
$bootsource reflects the current boot’s medium as indicated by the
SoC. In cases where the reboot mode is used to communicate with the BootROM,
$bootsource and $bootsource_instance may describe the same device
as the reboot mode.
For cases, where the communication instead happens between barebox and an OS,
they can be completely different, e.g. $bootsource may say barebox was
booted from spi-nor, while the reboot mode describes that barebox should
boot the Kernel off a USB flash drive.
1.29.3.3. Comparison to barebox state¶
barebox state also allows sharing information between barebox and the OS, but it does so while providing atomic updates, redundant storage and optionally wear leveling. In contrast to state, reboot mode is just that: a mode for a single reboot. barebox clears the reboot mode after reading it, so this can be reliably used across one reset only.
