From 623beb985f1bfb8b28abd1f32dafc8bb7ead46ec Mon Sep 17 00:00:00 2001
From: Tim Whisonant <tim.whisonant@canonical.com>
Date: Thu, 25 Jun 2026 12:46:24 -0700
Subject: [PATCH] doc(reference): add kernel flavours section to ubuntu-kernels

Add a 'Kernel flavours' section to the Ubuntu kernel variants and
branches reference page, migrating the design principle from the
deprecated Ubuntu wiki page at:
  https://wiki.ubuntu.com/Kernel/FAQ/KernelFlavourDifferences

The wiki established that Ubuntu kernels are all built from the same
source code and patches, with config options as the only differentiator
between flavours. That foundational principle was missing from the
existing reference page.

The new section:
- Defines what a kernel flavour is (same source, config-only differences)
- Distinguishes flavours from optimized/derivative kernels (separate
  source packages that may also carry additional patches)
- Provides a reference table of current Ubuntu flavours, their supported
  architectures, and target workloads

The historical per-release config comparison tables from the wiki
(Lucid 10.04, Natty 11.04) are not included: those releases are
end-of-life and the flavour names they document (-server, -virtual,
-generic-pae) no longer exist in current Ubuntu.

Signed-off-by: Tim Whisonant <tim.whisonant@canonical.com>
---
 docs/reference/ubuntu-kernels.md | 39 ++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/reference/ubuntu-kernels.md b/docs/reference/ubuntu-kernels.md
index c2eb0f9..c860a37 100644
--- a/docs/reference/ubuntu-kernels.md
+++ b/docs/reference/ubuntu-kernels.md
@@ -84,6 +84,45 @@ Once a `linux-unstable` kernel version includes support for all core components
   During a development cycle, it is expected to be updated to all `major.minor` upstream releases until the last version available before the Ubuntu release GA.
 * **Purpose:** The `linux` kernel is the Ubuntu generic kernel which will be available as the default choice for most installations, and will be the base for all derivatives and custom kernels based on the same upstream `major.minor` version.
 
+## Kernel flavours
+
+A **kernel flavour** is a distinct binary produced from a single kernel source package, sharing the same source code and patches as all other flavours from that package.
+The only differences between flavours are the configuration options applied at build time.
+
+For example, the Ubuntu `linux` source package produces both `linux-generic` and `linux-lowlatency` binaries from the same tree, each with a different `.config` file tailored to its target workload.
+
+```{note}
+This config-only distinction applies within a single source package.
+Kernels with separate source packages (such as `linux-aws` or `linux-raspi`) are [optimized kernels](#optimized-kernels) and may carry additional patches beyond config changes.
+```
+
+The current Ubuntu flavours and their target workloads are:
+
+```{list-table}
+:header-rows: 1
+
+* - Flavour
+  - Architectures
+  - Target workload
+* - `generic`
+  - amd64, arm64, armhf, ppc64el, riscv64, s390x
+  - Default for desktop and server systems
+* - `generic-64k`
+  - arm64
+  - Desktop and server systems requiring 64K memory pages
+* - `lowlatency`
+  - amd64, arm64
+  - Latency-sensitive workloads (audio production, real-time data)
+* - `lowlatency-64k`
+  - arm64
+  - Combines lowlatency tuning with 64K memory pages
+* - `realtime`
+  - amd64, arm64
+  - Deterministic latency via the PREEMPT_RT patchset
+```
+
+(optimized-kernels)=
+
 ## Optimized kernels
 
 In addition to the generic kernel, Canonical also provides optimized kernels which are derived from the generic kernel.