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

▶ Watch this deck — 8 scenes, ~6 min

01 No file system at boot

LITTLE KERNEL the board's disk lk (aboot)reads raw partitions; no files ubuntu-seedubuntu-bootubuntu-saveubuntu-datafiles on seed and boot do not reach lk snaprecoveryselsnapbootselthe variablessnapdwrites a structure boot_raboot_rbboot_aboot_bkernels, as Android boot imageswrites boot.img and are used once the kernel is running reference: the Dragonboard 410c gadget, which builds lk itself
Little Kernel reads raw partitions and no files. The board's disk holds snaprecoverysel and snapbootsel for the variables, boot_ra, boot_rb, boot_a and boot_b for kernels as Android boot images, and the usual ubuntu-seed, ubuntu-boot, ubuntu-save and ubuntu-data. snapd writes a structure to the select partitions and boot.img to a boot partition

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.

02 The environment is a C struct

LKENV elsewhere: lines of name=value text signatureuint32versionuint32kernel_status[256]snap_kernel[256]snap_try_kernel[256]...bootimg_matrix[2][2][256]...crc32uint32V2 run, abridged; the header is compiled into lk little-endianevery string: 256 bytescrc32 over everything before it V1 · UC16 and UC18SBse · snap_mode V2 run · UC20+SBse · kernel_statusV2 recovery · UC20+SRse · snapd_recovery_mode a key with no field is dropped, without an errorso snapd_boot_flags cannot be stored on lk
The lk environment as a C struct, abridged: signature, version, kernel_status, snap_kernel, snap_try_kernel, the boot image matrix and a final crc32. It is little-endian, every string is 256 bytes and the CRC covers everything before it. Three variants: V1 for UC16 and UC18, V2 run and V2 recovery. A key with no field is dropped without an error

The lk environment is a fixed little-endian C struct with 256-byte strings and a trailing CRC32, defined in a header shared with lk. Variants: V1 (UC16/18), V2 run and V2 recovery. Unsupported keys are silently ignored, so snapd_boot_flags cannot be stored.

Most bootloaders keep their variables as text: a name, an equals sign, a value. LK keeps them the way a C programmer would. The environment is a fixed structure, defined in a header that ships with snapd and is compiled into LK. It opens with a signature and a version, every string is two hundred and fifty-six bytes, and the last field is a checksum of everything before it. There are three variants: version one for UC16 and 18, and two version-two structures, one for run mode and one for recovery. The catch: set a variable it has no field for, and nothing happens. No error.

03 Two environments, each with a twin

SELECT PARTITIONS snaprecoveryselsnapbootsela power cut mid-write can leave a raw partition invalid snaprecoveryselbaksnapbootselbakrole: system-seed-selectrole: system-boot-select snapd savesprimarybak12primary, then backup snapd loadsprimarybakbad CRCreads the backup instead lk at bootprimarybaksame fallback, and itrestores the primary snapd_lk_boot_disk=mmcblk0UC20+: lk adds it to the kernel command line; snapd searches only that disk
snaprecoverysel and snapbootsel each have a backup partition ending in bak. snapd saves the primary then the backup, and loads the backup when the primary has a bad CRC. lk does the same at boot and restores the primary. On UC20 and later lk passes snapd_lk_boot_disk and snapd searches only that disk

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

MATRIX boot_aboot_bwhich kernel is in which? run environment · 2 rowsboot_aboot_b dragonboard-kernel_70.snap(empty)value: a kernel snap file name recovery environment · up to 10 rowsboot_ra20260301boot_rb(empty)value: a recovery system label labels: written by the gadget build from gadget.yaml, not changed afterwards lk at bootsnap_kernel -> its row -> boot_a
Two tables of partition label and value. The run environment has two rows: boot_a holds dragonboard-kernel_70.snap and boot_b is empty. The recovery environment has up to ten rows: boot_ra holds the recovery system 20260301. The labels are written by the gadget build. At boot lk looks snap_kernel up in the table and boots that partition

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

REFRESH boot_adragonboard-kernel_70.snapboot_b(free)<- snap_kernelboot_aboot_b dragonboard-kernel_71.snapsnapd copies its boot.img onto boot_bboot_b dragonboard-kernel_71.snaprecorded, environment saved snap_try_kernel=dragonboard-kernel_71.snapkernel_status=try lk: try -> trying, save both copies, boot boot_b snap_kernel=dragonboard-kernel_71.snapboot_a keeps kernel 70 until a refresh reuses it
Kernel refresh on lk: boot_a holds dragonboard-kernel_70.snap and is snap_kernel; boot_b is free. snapd copies boot.img from dragonboard-kernel_71.snap onto boot_b, records the file name in row b and saves, then sets snap_try_kernel and kernel_status=try. lk changes try to trying, saves both copies and boots boot_b; after success snap_kernel is the new kernel

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

RECOVERY create a recovery system at runtimegrub on acme-gateway: yes lk at boot, outside run modemode from the recovery environment; empty means installlabel -> recovery matrix -> partition, e.g. boot_ramode and label go on the kernel command line image build: prepare-imageboot_raboot_ra = 20260301boot.img and the .bin environments go to boot/lk/,and the image is flashed with them lk: not supportedinternal error: extracting recovery kernel assets is not supported for a runtime lk bootloader its recovery systems are the ones it left the factory with
Creating a recovery system at runtime works with grub on acme-gateway but not on lk. lk at boot maps the recovery system label through the recovery matrix to a partition and passes mode and label to the kernel. Recovery kernels are placed only by prepare-image; at runtime snapd returns an internal error

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 bootloader: android-boot gadgetandroidboot.confcopied/boot/androidboot/androidboot.env key=valuekey=valuetext · no size limit · no checksum ExtractKernelAssetsRemoveKernelAssetsboth do nothing cannot be the recovery bootloader on UC20+ ?who reads the file at boot, and how the kernel reaches the device: not determined
androidboot: gadget.yaml names android-boot; the gadget's androidboot.conf is copied to /boot/androidboot/androidboot.env, a text file of key=value lines with no size limit and no checksum. Extracting and removing kernel assets do nothing. It cannot be a UC20+ recovery bootloader. Who reads the file at boot and how the kernel reaches the device is not determined

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 Little Kernel and Android boot Bootloadersthe common interface Try, trying, donewhat the statuses mean U-Bootubootpart: env in a partition Recovery systemswhat lk cannot do Model, gadget and kernelselect and image roles Ubuntu Corethe overview
Roads from Little Kernel and Android boot: the bootloader interface, try and trying, U-Boot's ubootpart, recovery systems, the model and gadget roles, and the Ubuntu Core overview

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)

PartitionRoleContent
snaprecoverysel, snaprecoveryselbaksystem-seed-selectrecovery environment and its backup
snapbootsel, snapbootselbaksystem-boot-selectrun environment and its backup
boot_ra, boot_rbsystem-seed-imageboot images of recovery systems
boot_a, boot_bsystem-boot-imageboot 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

VariantVersionSignaturePartitionKeys snapd can get and set
V1 (UC16/18)0x00010001SBsesnapbootselsnap_mode, snap_kernel, snap_try_kernel, snap_core, snap_try_core, snap_gadget, snap_try_gadget, reboot_reason, bootimg_file_name
V2 run0x00010010SBsesnapbootselkernel_status, snap_kernel, snap_try_kernel, snap_gadget, snap_try_gadget, bootimg_file_name
V2 recovery0x00010010SRsesnaprecoveryselsnapd_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

EnvironmentRowsValue
run2kernel snap file name
recoveryup to 10recovery system label

Kernel refresh, in order

  • Find the row whose value is not the current snap_kernel.
  • Write boot.img (or the file named by bootimg_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_kernel and kernel_status=try.
  • lk changes try to trying, saves both copies and boots the row's partition; on trying it clears the status and boots the partition of snap_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>.bin and boot.img is unpacked under boot/lk/.

androidboot

ItemValue
gadget.yaml valueandroid-boot
marker in the gadgetandroidboot.conf
environment/boot/androidboot/androidboot.env: text key=value, no checksum
kernel assetsnot handled
recovery systems (UC20+)not supported
boot-side behaviournot determined

Further reading

  • Gadget snap format: the roles system-boot-image and system-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

UBUNTU CORE · bootloaders

UBUNTU CORE · install and recovery