Little Kernel and Android boot
one bootloader for Ubuntu Core developers
Little Kernel boots Android boot images from raw partitions and has no file system at boot. snapd shares a C structure with it in the snapbootsel and snaprecoverysel partitions and writes each kernel's boot.img into a free boot partition. Recovery systems cannot be created at runtime.
On the map: ubuntu core bootloaders
01 No file system at boot
lk boots Android boot images from raw partitions. Boot variables are a binary structure in the snaprecoverysel and snapbootsel partitions, and each kernel's boot.img is written to a boot partition.
This board grew up in the phone world. Its bootloader, Little Kernel, or LK, doesn't open files at boot: it only knows partitions. It loads an Android boot image, kernel and initrd in one blob, straight from a raw partition. So nothing snapd leaves in a file on seed or boot can reach it. Instead, the boot variables live in two small partitions of their own, as a binary structure, and each kernel is written into a boot partition. The usual four Ubuntu Core partitions are still there, for everything after the kernel starts. Our example is the Dragonboard 410c, whose gadget builds LK with snap boot support compiled in.
03 Two environments, each with a twin
snaprecoverysel and snapbootsel each have a backup partition with the suffix bak. snapd writes primary then backup and loads the backup when the primary is invalid. On UC20+ the partitions are searched only on the disk named by snapd_lk_boot_disk; without it lk is not detected.
A raw partition has no file system to keep it consistent. If the power fails halfway through a write, what's left? That's what the twin is for. The gadget declares snaprecoverysel and snapbootsel, each with a twin whose name ends in bak. When snapd saves, it writes the primary, then the backup. When it loads and the primary's checksum is bad, it reads the backup instead. LK does the same at boot, and also repairs the primary from the backup. And on UC20 and later, LK names its boot disk on the kernel command line. snapd looks for these partitions only on that disk.
04 The boot image matrix
Each environment holds a matrix of partition label and value. Run: two rows, the value is a kernel snap file name. Recovery: up to ten rows, the value is a recovery system label. The labels are set by the gadget build.
If kernels are just blobs in partitions called boot A and boot B, how does anyone know which kernel is in which? There's a little table for that. Each environment holds pairs: a partition label and a value. The run environment has two rows, and the value is a kernel snap's file name. The recovery environment has up to ten rows, and the value is a recovery system label. The labels are filled in when the gadget is built, from gadget.yaml, and after that nobody changes them. At boot, LK takes the kernel name from the variables, finds its row and boots that partition.
05 A kernel refresh: fill the free slot
snapd writes the new kernel's boot.img to the boot partition not used by snap_kernel, records the snap file name in the matrix, then sets snap_try_kernel and kernel_status=try. lk flips the status and boots the matching partition. Removing a kernel only clears its row.
Two boot partitions, one kernel in use. Guess where the new one goes. snapd asks the environment for the row whose value isn't the current kernel: boot B. It unpacks boot.img from the new kernel snap, copies it onto that partition, writes the new file name into the row and saves. Then it sets the try kernel, and the kernel_status to try. At boot, LK flips try to trying, saves both copies and boots boot B. Finding trying already set would mean the last attempt failed, so it would boot the old kernel. Once the new one is good, it becomes the current kernel.
06 Recovery systems are fixed when the image is built
lk maps snapd_recovery_system through the recovery matrix to a boot partition. Recovery kernels are written only when the image is prepared: creating a recovery system at runtime is not supported on lk.
On acme-gateway, the grub device from the other decks, you can create a new recovery system while it runs. Try that on this board and you hit a wall. Outside run mode, LK reads the mode and the system label from the recovery environment; an empty mode means install. It looks the label up in the recovery matrix, boots that partition and passes both values to the kernel. But recovery kernels only get into those partitions while the image is prepared. At runtime, snapd's code for it returns an internal error. So the recovery systems on this board are the ones it left the factory with.
07 androidboot: the smallest implementation
androidboot keeps variables in the text file /boot/androidboot/androidboot.env and does not handle kernel assets. It cannot be a UC20+ recovery bootloader. Its boot-side behaviour was not determined.
One more name sits next to LK in gadget.yaml: android boot. It's a shorter story, and partly an unfinished one. The gadget ships androidboot.conf, and snapd copies it to an environment file under boot. The format is plain text, key=value, with no size limit and no checksum. Extracting and removing kernel assets do nothing at all. It supports neither kind of recovery system, so it can't be the recovery bootloader on UC20 and later. And there's no test, no reference gadget and no boot code to read, so who reads that file at boot, and how a kernel gets there, is still open.
08 Where to go from here
Roads: the bootloader interface, try and rollback, U-Boot, recovery systems, the gadget and the overview.
That's the bootloader with the least in common with the others. To see what it shares with them after all, start with the bootloaders deck: the interface every implementation fills in. Try, trying and done have a deck of their own. U-Boot's ubootpart is the other bootloader that keeps its environment in a raw partition. Recovery systems shows what creating one needs, the step LK can't do. The model deck has the gadget roles for select and image partitions. And the lighthouse takes you back to the Ubuntu Core overview.
Read more
Partitions and gadget roles (reference gadget)
| Partition | Role | Content |
|---|---|---|
snaprecoverysel, snaprecoveryselbak | system-seed-select | recovery environment and its backup |
snapbootsel, snapbootselbak | system-boot-select | run environment and its backup |
boot_ra, boot_rb | system-seed-image | boot images of recovery systems |
boot_a, boot_b | system-boot-image | boot images of run kernels |
The gadget marker lk.conf is a link to the recovery environment image the gadget builds. The gadget.yaml bootloader value is lk.
Environment variants
| Variant | Version | Signature | Partition | Keys snapd can get and set |
|---|---|---|---|---|
| V1 (UC16/18) | 0x00010001 | SBse | snapbootsel | snap_mode, snap_kernel, snap_try_kernel, snap_core, snap_try_core, snap_gadget, snap_try_gadget, reboot_reason, bootimg_file_name |
| V2 run | 0x00010010 | SBse | snapbootsel | kernel_status, snap_kernel, snap_try_kernel, snap_gadget, snap_try_gadget, bootimg_file_name |
| V2 recovery | 0x00010010 | SRse | snaprecoverysel | snapd_recovery_mode, snapd_recovery_system, bootimg_file_name, try_recovery_system, recovery_system_status |
The structures are defined in include/lk/snappy_boot_v1.h and snappy_boot_v2.h in the snapd tree and mirrored in bootloader/lkenv/. Every string field is 256 bytes. The last field is a CRC32 over everything before it. Any other key is ignored without an error, so snapd_boot_flags and the command-line variables cannot be stored.
Boot image matrix
| Environment | Rows | Value |
|---|---|---|
| run | 2 | kernel snap file name |
| recovery | up to 10 | recovery system label |
Kernel refresh, in order
- Find the row whose value is not the current
snap_kernel. - Write
boot.img(or the file named bybootimg_file_name) from the kernel snap to that partition. - Record the kernel's file name in the row and save the environment.
- Set
snap_try_kernelandkernel_status=try. - lk changes
trytotrying, saves both copies and boots the row's partition; ontryingit clears the status and boots the partition ofsnap_kernel. - Removing a kernel clears the row; the partition's content stays.
Finding the partitions
- UC20+: only on the disk named by the kernel argument
snapd_lk_boot_disk, which lk appends. Without that argument the lk bootloader is not considered present. - UC16/18:
/dev/disk/by-partlabel/. - At image build time the environments are files named
<label>.binandboot.imgis unpacked underboot/lk/.
androidboot
| Item | Value |
|---|---|
| gadget.yaml value | android-boot |
| marker in the gadget | androidboot.conf |
| environment | /boot/androidboot/androidboot.env: text key=value, no checksum |
| kernel assets | not handled |
| recovery systems (UC20+) | not supported |
| boot-side behaviour | not determined |
Further reading
- Gadget snap format: the roles
system-boot-imageandsystem-boot-select, the only published mention of Little Kernel.
The published documentation has no other page on Little Kernel or Android boot.
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 the comparison with other bootloaders
- U-Boot — ubootpart which also keeps its environment in a raw partition
UBUNTU CORE · install and recovery
- Recovery systems — what creating a recovery system needs
- Model, gadget and kernel — the gadget roles for select and image partitions