From 1876c1d558326ef09034d93cfff33233abfcdd89 Mon Sep 17 00:00:00 2001 From: Dilyn Corner Date: Fri, 17 Apr 2026 13:02:56 -0400 Subject: [PATCH 1/5] reference: development: the-kernel-snap: extend information Update to reflect the current state of the kernel snap and include information on the kernel.yaml. Signed-off-by: Dilyn Corner --- .../yaml-schemas/the-kernel-snap.md | 79 +++++++++++++++++-- 1 file changed, 71 insertions(+), 8 deletions(-) diff --git a/docs/reference/development/yaml-schemas/the-kernel-snap.md b/docs/reference/development/yaml-schemas/the-kernel-snap.md index 1b8c3c7..98ad416 100644 --- a/docs/reference/development/yaml-schemas/the-kernel-snap.md +++ b/docs/reference/development/yaml-schemas/the-kernel-snap.md @@ -1,22 +1,85 @@ (reference-development-yaml-schemas-the-kernel-snap)= # The kernel snap -As the name implies, the _kernel_ snap is responsible for defining the Linux kernel that will run in a snap-based system. The correct kernel snap for a given system is selected via the model assertion, produced and signed by the device's brand account before the image is built. Once the image is built, the kernel snap may be updated, but it cannot be replaced by a completely different kernel snap. +As the name implies, the _kernel_ snap is responsible for defining the Linux +kernel that will run in a snap-based system. The correct kernel snap for a given +system is selected via the model assertion, produced and signed by the device's +brand account before the image is built. Once the image is built, the kernel +snap may be updated, but it cannot be replaced by a completely different kernel +snap. -Canonical publishes some reference kernel snaps as well as kernel snaps for main Canonical models such as official Ubuntu Core VMs on various certified public clouds, as well as general purpose computing images for popular physical devices such as the 64-bit x86 PC and Raspberry Pi 2 and 3. +Canonical publishes some reference kernel snaps as well as kernel snaps for main +Canonical models such as official Ubuntu Core VMs on various certified public +clouds, as well as general purpose computing images for popular physical devices +such as the 64-bit x86 PC and Raspberry Pi 2 and 3. + +For details on building a kernel snap, see [Build a kernel snap](https://documentation.ubuntu.com/core/how-to-guides/image-creation/build-a-kernel-snap/) +in the Ubuntu Core documentation. ## Setup files -In addition to traditional snap metadata, the kernel snap also holds some setup files fundamental to the initialization and lifecycle of the device. +In addition to traditional snap metadata, the kernel snap also holds some setup +files fundamental to the initialization and lifecycle of the device. -The current layout for a kernel snap is straightforward: +The layout for a kernel snap has some variation, but usually follows: - `meta/snap.yaml` - Traditional snap details, with `type: kernel` explicitly defined -- `kernel.img` - The actual kernel image -- `initrd.img` - The respective initrd image +- `meta/kernel.yaml` - Optional kernel-specific metadata defining kernel-provided assets +- `snapd-info` - Information about the snapd packaged in the initrd - `modules//` - Kernel modules; version must match the one in `snap.yaml` -- `firmware/` - Optional firmware files. +- `firmware/` - Optional firmware files - `dtbs/` - Optional binary device-tree files, if gadget.yaml states `device-tree-origin: kernel` +- kernel - The actual kernel image +- initrd - The initrd image + +The kernel and initrd may be discrete objects, usually named `kernel.img` and +`initrd.img`, respectively. However, they could also be distributed as a single [Unified Kernel Image](https://uapi-group.org/specifications/specs/unified_kernel_image/) +(UKI) or as a [Flatted Image Tree](https://docs.u-boot.org/en/v2024.07/usage/fit/source_file_format.html) +(FIT) image. These are usually named `kernel.efi` or `kernel.img`, respectively. + +### kernel.yaml + +The `kernel.yaml` provides information used by snapd to determine +kernel-specific asset information. Primarily, this is about device trees and +kernel modules. The standard format is: + +```yaml +dynamic-modules: $SNAP_DATA +assets: + dtbs: + update: true + content: + - dtbs/ +``` + +* `dynamic-modules` points to a folder which contains `modules/` and `firmware/` +directories, usually created by a kernel component. + +* `assets` details a list of content the kernel snap provides, usually device +tree files, to the gadget snap. These are then referenceable in the gadget +snap's `gadget.yaml` like so: + +```yaml +volumes: + platform: + schema: gpt + bootloader: grub + structure: + - name: ubuntu-seed + role: system-seed + filesystem: vfat + type: C12A7328-F81F-11D2-BA4B-00A0C93EC93B + size: 800M + offset: 8M + content: + - source: $kernel:dtbs/dtbs/ + target: /dtbs/ +``` + +### initrd + +The initrd component of the kernel snap plays a fundamental role in the booting +of an Ubuntu Core system. -Sample configuration files may be found in the reference gadget snaps. For further details, see [Build a kernel snap](https://documentation.ubuntu.com/core/how-to-guides/image-creation/build-a-kernel-snap/) in the Ubuntu Core documentation. +The initrd is usually built using the ubuntu-core-initramfs tool. From 70fee7a357d4f630d5f8f1fd1c301204de6635b0 Mon Sep 17 00:00:00 2001 From: Dilyn Corner Date: Fri, 17 Apr 2026 13:10:45 -0400 Subject: [PATCH 2/5] reference: development: the-gadget-snap: fixup ref links Compactify things. Signed-off-by: Dilyn Corner --- .../development/yaml-schemas/the-gadget-snap.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/reference/development/yaml-schemas/the-gadget-snap.md b/docs/reference/development/yaml-schemas/the-gadget-snap.md index f597512..b7d953b 100644 --- a/docs/reference/development/yaml-schemas/the-gadget-snap.md +++ b/docs/reference/development/yaml-schemas/the-gadget-snap.md @@ -30,16 +30,7 @@ The following gadget repositories contain the gadget snap definitions for _amd64 - [Raspberry Pi "Universal" Gadget Snap](https://github.com/canonical/pi-gadget) - [i386](https://github.com/canonical/pc-i386-gadget) -In addition to the above, the IoT Devices Field team maintains a GitHub repository with source code branches that contain templates for the following device architectures: - -- [arm64-odroid-hc4](https://github.com/canonical/iot-field-gadget-snap/tree/22-arm64-odroid-hc4) -- [arm64-orange-pi-5plus](https://github.com/canonical/iot-field-gadget-snap/tree/22-arm64-orange-pi-5plus) -- [amd64-pc](https://github.com/canonical/iot-field-gadget-snap/tree/22-amd64-pc) -- [amd64-pc-classic](https://github.com/canonical/iot-field-gadget-snap/tree/22-amd64-pc-classic) -- [risc64-icicle](https://github.com/canonical/iot-field-gadget-snap/tree/22-riscv64-icicle) -- [risc64-nezha](https://github.com/canonical/iot-field-gadget-snap/tree/22-riscv64-nezha) - -In the near future, we expect to add a RISC-V reference gadget snap to this list. +In addition to the above, the IoT Devices Field team maintains a [GitHub repository](https://github.com/canonical/iot-field-gadget-snap) with source code branches that contain examples for several hardware platforms: ## The gadget.yaml file From 7978c507b690252a3fd5c56f303bd2a97ef718e9 Mon Sep 17 00:00:00 2001 From: Dilyn Corner Date: Tue, 2 Jun 2026 22:14:20 -0400 Subject: [PATCH 3/5] reference: development: the-kernel-snap: feedback Small formatting and language fixups. Signed-off-by: Dilyn Corner --- .../yaml-schemas/the-kernel-snap.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/reference/development/yaml-schemas/the-kernel-snap.md b/docs/reference/development/yaml-schemas/the-kernel-snap.md index 98ad416..2301c67 100644 --- a/docs/reference/development/yaml-schemas/the-kernel-snap.md +++ b/docs/reference/development/yaml-schemas/the-kernel-snap.md @@ -1,17 +1,14 @@ (reference-development-yaml-schemas-the-kernel-snap)= # The kernel snap -As the name implies, the _kernel_ snap is responsible for defining the Linux -kernel that will run in a snap-based system. The correct kernel snap for a given -system is selected via the model assertion, produced and signed by the device's -brand account before the image is built. Once the image is built, the kernel -snap may be updated, but it cannot be replaced by a completely different kernel -snap. +The kernel snap is responsible for providing the Linux kernel image and modules +for the system. The kernel snap to be used is defined in the device's model +assertion, which is produced and signed by the Brand authority. Canonical publishes some reference kernel snaps as well as kernel snaps for main Canonical models such as official Ubuntu Core VMs on various certified public clouds, as well as general purpose computing images for popular physical devices -such as the 64-bit x86 PC and Raspberry Pi 2 and 3. +such as the 64-bit x86 PC and Raspberry Pi. For details on building a kernel snap, see [Build a kernel snap](https://documentation.ubuntu.com/core/how-to-guides/image-creation/build-a-kernel-snap/) in the Ubuntu Core documentation. @@ -34,8 +31,8 @@ The layout for a kernel snap has some variation, but usually follows: The kernel and initrd may be discrete objects, usually named `kernel.img` and `initrd.img`, respectively. However, they could also be distributed as a single [Unified Kernel Image](https://uapi-group.org/specifications/specs/unified_kernel_image/) -(UKI) or as a [Flatted Image Tree](https://docs.u-boot.org/en/v2024.07/usage/fit/source_file_format.html) -(FIT) image. These are usually named `kernel.efi` or `kernel.img`, respectively. +(UKI) or as a [Flatted Image Tree](https://fitspec.osfw.foundation/) (FIT) image. +These are usually named `kernel.efi` or `kernel.img`, respectively. ### kernel.yaml @@ -76,10 +73,9 @@ volumes: target: /dtbs/ ``` -### initrd +## initrd The initrd component of the kernel snap plays a fundamental role in the booting of an Ubuntu Core system. The initrd is usually built using the ubuntu-core-initramfs tool. - From c12945dc031ae841eca69c2b877602fc88e7b7b6 Mon Sep 17 00:00:00 2001 From: Dilyn Corner Date: Wed, 10 Jun 2026 12:19:18 -0400 Subject: [PATCH 4/5] reference: development: the-kernel-snap: TODO on initrd section Signed-off-by: Dilyn Corner --- docs/reference/development/yaml-schemas/the-kernel-snap.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/reference/development/yaml-schemas/the-kernel-snap.md b/docs/reference/development/yaml-schemas/the-kernel-snap.md index 2301c67..8e81042 100644 --- a/docs/reference/development/yaml-schemas/the-kernel-snap.md +++ b/docs/reference/development/yaml-schemas/the-kernel-snap.md @@ -73,9 +73,12 @@ volumes: target: /dtbs/ ``` + From e8cde2247b83501676f6c7649192caa615ca562d Mon Sep 17 00:00:00 2001 From: Dilyn Corner Date: Wed, 10 Jun 2026 12:26:45 -0400 Subject: [PATCH 5/5] reference: development: the-kernel-snap: replace "referenceable" Technically "not a word". "citable" is close enough in what I mean. Signed-off-by: Dilyn Corner --- docs/reference/development/yaml-schemas/the-kernel-snap.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/development/yaml-schemas/the-kernel-snap.md b/docs/reference/development/yaml-schemas/the-kernel-snap.md index 8e81042..3902ee1 100644 --- a/docs/reference/development/yaml-schemas/the-kernel-snap.md +++ b/docs/reference/development/yaml-schemas/the-kernel-snap.md @@ -53,8 +53,8 @@ assets: directories, usually created by a kernel component. * `assets` details a list of content the kernel snap provides, usually device -tree files, to the gadget snap. These are then referenceable in the gadget -snap's `gadget.yaml` like so: +tree files, to the gadget snap. These are then citable in the gadget snap's +`gadget.yaml` like so: ```yaml volumes: