U-Boot
one bootloader for Ubuntu Core developers
On U-Boot boards snapd only edits an environment and unpacks kernels. The boot logic is a script in the gadget. Since UC20 the environment is a small boot.sel file on each of ubuntu-seed and ubuntu-boot or with ubootpart a raw partition holding two copies.
On the map: ubuntu core bootloaders
01 snapd edits variables, the gadget's script decides
With U-Boot, snapd writes boot variables and unpacks kernel files; the gadget's boot script does the rest. UC16/18 use uboot.env, UC20+ use two boot.sel files and boot.scr, and ubootpart uses a raw partition.
On your Arm board the bootloader is U-Boot, and U-Boot will happily run whatever script it's given. So snapd takes a step back and lets the gadget do the talking. snapd sets variables in an environment and unpacks kernel files into a folder. The gadget's boot script reads the one and loads from the other. You'll meet three arrangements. Ubuntu Core 16 and 18 keep one environment file, with the boot logic stored inside it as a variable. Ubuntu Core 20 and later use two small boot.sel files and a separate script. And the newer ubootpart keeps the environment in a raw partition.
02 The environment: a checksum and a list of strings
A U-Boot environment is a CRC32, an optional flag byte, NUL-terminated key=value strings, a double NUL and 0xff fill. snapd overwrites it in place and accepts either header size when reading.
Before the script, the notebook it reads. U-Boot's environment is a block of a few kilobytes with a very simple shape. It starts with a checksum. Then there may be one flag byte. Then come key=value strings, each ending in a zero byte. Two zeros end the list, and 0xff fills the rest. snapd saves it by overwriting the file in place, with no rename, to keep writes on a FAT partition to a minimum. Whether the flag byte is there depends on how your board's U-Boot was built, so snapd reads with one layout and, if the checksum doesn't match, tries the other.
03 UC20: two boot.sel files and a script
UC20+ gadgets carry an empty uboot.conf marker and a boot.scr. snapd creates uboot/ubuntu/boot.sel on ubuntu-seed at image time; the one on ubuntu-boot is shipped by the gadget.
Mount your board's two unencrypted partitions and look for a folder called uboot/ubuntu. There's one on each, holding a file called boot.sel. The gadget's uboot.conf used to be the whole environment. Now it's an empty marker: this gadget boots through a script, boot.scr. When the image is built, snapd creates a four kilobyte boot.sel on the seed, for the mode and the recovery system. The gadget ships the one beside the kernels, because snapd installs run bootloader configuration only for GRUB. At run time it appears under /boot/uboot. This layout comes from the Raspberry Pi gadget's UC20 branch.
04 What the boot script does
The reference boot.scr reads the mode from ubuntu-seed's boot.sel (default install); in run mode it reads the next partition's boot.sel, flips try to trying, saves it, and loads kernel.img and initrd.img from the chosen kernel's folder.
Now the script. It's short, and if you've seen the GRUB deck you'll recognise most of it. It loads boot.sel from the seed and imports the mode and the recovery system. No mode means install. Both go onto the kernel command line. In run mode it loads the other boot.sel from the next partition, by number, not by label. Try becomes trying and the try kernel is picked. Trying means the last attempt failed, so the status is cleared and the old kernel is picked. It saves the file. Other modes use the recovery system's kernel. Last, it loads the kernel and initrd, and boots.
05 A kernel refresh: a folder and one write
snapd unpacks kernel.img, initrd.img and dtbs/* into uboot/ubuntu/<snap-file>/, then sets snap_try_kernel and kernel_status=try in one write; success is one more write.
Time to refresh the kernel on your board. Compared with GRUB's careful sequence of symlinks, this one is almost boring. snapd unpacks the kernel image, the initrd and the device trees from the new snap into a folder named after the snap file. Then one write sets the try kernel and the status, try. During the reboot the script flips it to trying. After a good boot, one more write makes the new kernel current and clears the other two. Each change is a single write, so there's no symlink order to get wrong. Recovery systems get the same files under systems/<label>/kernel/, even on a running device.
06 ubootpart: the environment without a file system
ubootpart stores two 8192-byte environment copies in a raw partition labelled ubuntu-boot-state (role system-boot-state). The copy with a valid CRC and the newer flag is active; a save writes the other one.
A file on a FAT partition is a fragile place to keep what a board needs to boot. ubootpart skips the file system. The gadget declares a raw partition with the role system-boot-state: fixed offset, no file system, at least one mebibyte. Inside are two copies of the environment, eight kilobytes each. The active one has a valid checksum and the newer flag. A save writes only the other copy, flag one higher, so one intact copy always remains. snapd finds the partition by the disk the firmware booted from, then a kernel argument, then the label. No published gadget or boot script for it was found.
07 Where to go from here
Roads: the bootloader interface, try and rollback, piboot, Little Kernel, the gadget and the overview.
On a U-Boot board most of the boot story is written in the gadget. Here's where the rest of it is. The bootloaders deck shows the interface snapd's two U-Boot implementations share, and how it tells them apart. Try, trying, done explains what those statuses mean for the whole device. The Raspberry Pi has moved from U-Boot to piboot, and that deck shows how. Little Kernel boards keep their environment in raw partitions too. The model deck covers the gadget that carries boot.scr and declares the boot state partition. And the overview takes you back to Ubuntu Core as a whole.
Read more
Three arrangements
| Arrangement | Environment | Boot logic | Kernels |
|---|---|---|---|
UC16/18 (uboot, sole role) | /boot/uboot/uboot.env, a copy of the gadget's uboot.conf | the variable snappy_boot inside the environment, using snap_mode | /boot/uboot/<snap-file>/ |
UC20+ (uboot) | uboot/ubuntu/boot.sel on ubuntu-seed and on ubuntu-boot | the gadget's boot.scr | uboot/ubuntu/<snap-file>/ on ubuntu-boot; systems/<label>/kernel/ on ubuntu-seed |
ubootpart | raw partition ubuntu-boot-state, two copies | a gadget boot script (no reference found) | uboot/ubuntu/<snap-file>/; systems/<label>/kernel/ |
The gadget.yaml value is u-boot; snapd's names are uboot and ubootpart; the marker file is uboot.conf. On UC20 and later a non-empty uboot.conf is refused with "non-empty uboot.env not supported on UC20+ yet".
Environment format
| Part | Size | Notes |
|---|---|---|
| CRC32 | 4 bytes | little-endian |
| flag | 1 byte | optional in a single-copy environment; always present in a redundant one |
| data | rest | key=value strings ending in NUL; a double NUL ends the list; 0xff fill |
When snapd creates boot.sel it takes only the header layout, flag byte or not, from a sample boot.sel in the gadget if there is one; the content is not copied. Without a sample it writes the flag byte.
| File or device | Size |
|---|---|
boot.sel created by snapd | 4096 bytes |
UC16/18 uboot.env in the Pi gadget | 131072 bytes |
each copy on ubuntu-boot-state | 8192 bytes |
ubuntu-boot-state.img written at image build time | 16384 bytes |
Variables
| File | Variables |
|---|---|
ubuntu-seed boot.sel | snapd_recovery_mode, snapd_recovery_system, snapd_recovery_kernel |
ubuntu-boot boot.sel | kernel_status, snap_kernel, snap_try_kernel |
UC16/18 uboot.env | snap_mode, snap_core, snap_try_core, snap_kernel, snap_try_kernel |
snapd does not write the kernel command line variables for U-Boot; the boot script owns the command line.
The reference boot script, step by step
The script read is flash-kernel's bootscr.rpi, which the Raspberry Pi gadget's 20-arm64 branch wraps into boot.scr.
1. Load /uboot/ubuntu/boot.sel from the partition U-Boot booted from (ubuntu-seed); import the three recovery variables. The default mode is install. 2. Append snapd_recovery_mode=... snapd_recovery_system=... panic=-1 to the kernel arguments. 3. In run mode: load boot.sel from the next partition (partition number plus one), import the three kernel variables, flip try to trying or clear trying, save the file, and set the prefix to uboot/ubuntu/<kernel>/. 4. Otherwise: set the prefix to systems/<snapd_recovery_system>/kernel/. 5. Load kernel.img (decompressing it if needed) and initrd.img, then boot.
ubootpart in gadget.yaml
A structure with role: system-boot-state must have an explicit offset, no min-size, a size of at least 1 MiB, no file system, and the type 3DE21764-95BD-54BD-A5C3-4ABE786F38A8. The volume says bootloader: u-boot. A gadget reference file ubootpart.sel, if present, must be 8192 bytes.
Partition lookup order: the disk of the partition the firmware reports as the loader's; the disk named by the kernel argument snapd_system_disk; /dev/disk/by-partlabel/ubuntu-boot-state.
Further reading
- Gadget snap format:
uboot.confas marker file, thesystem-boot-staterole andboot.selin the Pi example. - Build a gadget snap:
boot.scr.inin the gadget tree and theboot.scrcontent entries. - Board enablement: a complete U-Boot gadget for a UC16 board.
- Install on MediaTek Genio: a real U-Boot board with its boot firmware archive.
Roads from here
UBUNTU CORE · boot
- Try, trying, done — what try and trying mean
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · bootloaders
- Bootloaders: one interface, six implementations — the interface and how uboot and ubootpart are told apart
- Raspberry Pi: piboot and tryboot — what replaced U-Boot on the Raspberry Pi
- Little Kernel and Android boot — another bootloader that keeps its environment in raw partitions
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the gadget that carries boot.scr and the system-boot-state role