feat(kernel): Add support for Debian suite configuration

Introduce `DEBIAN_SUITE` as a configurable argument in the Dockerfile, build
script, and CI workflow to align kernel builds with the target Raspberry Pi
OS release. Updated documentation to clarify the relationship between
suite versions and kernel compatibility.

.gitea/workflows/build-kernel.yml

@@ -27,9 +27,14 @@ jobs:
       # Don't cancel the other versions if one fails to build.
       fail-fast: false
       matrix:
-        kernel_version:
-          - "1:6.12.93-1+rpt1"
-          - "1:6.18.34-1+rpt1"
+        # Each raspberrypi archive suite only carries its own latest kernel, so
+        # the Debian base suite is paired with the kernel version it can install:
+        #   bookworm -> 6.12.x, trixie -> 6.18.x.
+        include:
+          - kernel_version: "1:6.12.93-1+rpt1"
+            suite: bookworm
+          - kernel_version: "1:6.18.34-1+rpt1"
+            suite: trixie
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -39,6 +44,7 @@ jobs:
         env:
           HEADERS_PKG: ${{ env.HEADERS_PKG }}
           KERNEL_VERSION: ${{ matrix.kernel_version }}
+          DEBIAN_SUITE: ${{ matrix.suite }}
         run: |
           set -eux
           # arm64 emulation for the builder image (no-op if already registered).
@@ -47,6 +53,7 @@ jobs:
           fi
           # Builder image: toolchain + matching raspberrypi kernel headers.
           docker build --platform linux/arm64 \
+            --build-arg DEBIAN_SUITE="$DEBIAN_SUITE" \
             --build-arg HEADERS_PKG="$HEADERS_PKG" \
             --build-arg KERNEL_VERSION="$KERNEL_VERSION" \
             -t iec-kbuild .

docs/kernel-notes.md

@@ -168,14 +168,20 @@ Configurable via env vars (kernel version is configurable as requested):
 
 | Var | Default | Purpose |
 |-----|---------|---------|
+| `SUITE` | `bookworm` | Debian/RPi OS suite; **must match the kernel** — `bookworm` ⇒ 6.12.x, `trixie` ⇒ 6.18.x |
 | `HEADERS_PKG` | `linux-headers-rpi-v8` | headers package; use `-v7`/`-v6` for 32-bit, or `raspberrypi-kernel-headers` |
 | `KERNEL_VERSION` | *(latest)* | exact version pin, e.g. `1:6.6.51-1+rpt3` |
 | `IMAGE` | `iec-kbuild` | builder image tag |
 
 ```bash
-KERNEL_VERSION=1:6.6.51-1+rpt3 ./build-in-docker.sh
+SUITE=trixie KERNEL_VERSION=1:6.18.34-1+rpt1 ./build-in-docker.sh
 ```
 
+**`SUITE` must match `KERNEL_VERSION`.** Each raspberrypi archive suite carries
+only its own latest kernel, so a trixie-era version against a `bookworm` base
+fails with `Version '…' was not found`. Find the Pi's suite with
+`. /etc/os-release; echo "$VERSION_CODENAME"` (or `lsb_release -cs`).
+
 **Find the exact values for *your* Pi** — run this on the Pi (e.g. over SSH); it
 prints the two lines ready to copy into the `build-in-docker.sh` invocation:
 
@@ -183,19 +189,21 @@ prints the two lines ready to copy into the `build-in-docker.sh` invocation:
 pkg="linux-headers-$(uname -r | sed 's/.*+rpt-//')"; echo "HEADERS_PKG=$pkg KERNEL_VERSION=$(dpkg-query -W -f='${Version}' "$pkg")"
 ```
 
-On the project's Pi Zero 2 W (`chris@10.1.0.41`, kernel `6.12.93+rpt-rpi-v8`)
-this currently prints:
+On the Pi at `chris@10.1.0.41` (a Pi 3B+, kernel `6.12.93+rpt-rpi-v8`; same
+arm64/`-v8` headers as the Zero 2 W) this currently prints:
 
 ```bash
 HEADERS_PKG=linux-headers-rpi-v8 KERNEL_VERSION=1:6.12.93-1+rpt1
 ```
 
-**vermagic caveat:** the raspberrypi apt archive normally serves only the
-*latest* kernel in its pool, so pinning `KERNEL_VERSION` to an old release may
-not be downloadable. The reliable strategy is to keep the Pi current
-(`sudo apt full-upgrade`) and build with the default (latest) — then the Pi and
-the container agree. If you must target an older/specific kernel, copy the Pi's
-`/lib/modules/$(uname -r)/build` tree into the container instead of using apt.
+**vermagic caveat:** each raspberrypi apt archive **suite** normally serves only
+the *latest* kernel in its pool (`bookworm` ⇒ 6.12.x, `trixie` ⇒ 6.18.x), so the
+container's `SUITE` must match the Pi's release, and pinning `KERNEL_VERSION` to
+an old release within a suite may not be downloadable. The reliable strategy is
+to keep the Pi current (`sudo apt full-upgrade`) and build with the matching
+`SUITE` + default (latest) version — then the Pi and the container agree. If you
+must target an older/specific kernel, copy the Pi's `/lib/modules/$(uname
+-r)/build` tree into the container instead of using apt.
 
 `uname -r` is **not** used inside the container (it reports the host kernel under
 emulation); the entrypoint derives `KDIR` from the installed headers under

kernel/Dockerfile

@@ -9,18 +9,29 @@
 #   docker run --privileged --rm tonistiigi/binfmt --install arm64
 #
 # Kernel version is configurable via build args:
+#   --build-arg DEBIAN_SUITE=trixie                # Debian/RPi OS suite (see notes)
 #   --build-arg HEADERS_PKG=linux-headers-rpi-v8   # 64-bit Pi Zero 2 W (default)
 #   --build-arg KERNEL_VERSION=1:6.6.51-1+rpt3      # optional exact pin (see notes)
 #
+# DEBIAN_SUITE must match the kernel you target: each raspberrypi archive suite
+# only carries its own latest kernel (bookworm -> 6.12.x, trixie -> 6.18.x), so
+# pinning a trixie-era KERNEL_VERSION against a bookworm base will fail with
+# "Version ... was not found". Keep this in sync with the Pi's release.
+#
 # Build context is this kernel/ directory.
-FROM --platform=linux/arm64 debian:bookworm
+ARG DEBIAN_SUITE=bookworm
+FROM --platform=linux/arm64 debian:${DEBIAN_SUITE}
+
+# Re-declare after FROM so it is in scope for the RUN below (ARGs before FROM
+# are only visible to the FROM line itself).
+ARG DEBIAN_SUITE=bookworm
 
 # The raspberrypi kernel/headers live in the raspberrypi.com archive, not Debian.
 RUN apt-get update \
  && apt-get install -y --no-install-recommends ca-certificates curl gnupg \
  && curl -fsSL https://archive.raspberrypi.com/debian/raspberrypi.gpg.key \
       | gpg --dearmor -o /usr/share/keyrings/raspberrypi-archive-keyring.gpg \
- && echo "deb [signed-by=/usr/share/keyrings/raspberrypi-archive-keyring.gpg] http://archive.raspberrypi.com/debian/ bookworm main" \
+ && echo "deb [signed-by=/usr/share/keyrings/raspberrypi-archive-keyring.gpg] http://archive.raspberrypi.com/debian/ ${DEBIAN_SUITE} main" \
       > /etc/apt/sources.list.d/raspi.list \
  && rm -rf /var/lib/apt/lists/*
 

kernel/build-in-docker.sh

@@ -9,19 +9,22 @@
 #   ./build-in-docker.sh clean          # clean build artifacts
 #
 # Configurable via environment variables:
+#   SUITE           Debian/RPi OS suite (default: bookworm; use trixie for 6.18.x)
 #   HEADERS_PKG     headers package (default: linux-headers-rpi-v8, 64-bit Zero 2 W)
 #                   e.g. linux-headers-rpi-v7 / -v6 for 32-bit, raspberrypi-kernel-headers
 #   KERNEL_VERSION  exact version to pin, e.g. 1:6.6.51-1+rpt3 (default: latest in repo)
 #   IMAGE           builder image tag (default: iec-kbuild)
 #
-# NOTE: the raspberrypi apt archive generally serves only the *latest* kernel in
-# its pool, so pinning KERNEL_VERSION to an old release may fail to download. The
+# NOTE: each raspberrypi apt archive suite serves only the *latest* kernel in its
+# pool (bookworm -> 6.12.x, trixie -> 6.18.x), so SUITE must match the kernel you
+# target and pinning KERNEL_VERSION to an old release may fail to download. The
 # reliable match strategy is to keep the Pi current (`sudo apt full-upgrade`) and
-# build with the default (latest). See docs/kernel-notes.md.
+# build with the matching SUITE + default (latest) version. See docs/kernel-notes.md.
 set -euo pipefail
 cd "$(dirname "$0")"
 
 IMAGE="${IMAGE:-iec-kbuild}"
+SUITE="${SUITE:-bookworm}"
 HEADERS_PKG="${HEADERS_PKG:-linux-headers-rpi-v8}"
 KERNEL_VERSION="${KERNEL_VERSION:-}"
 
@@ -32,8 +35,9 @@ if [ ! -e /proc/sys/fs/binfmt_misc/qemu-aarch64 ]; then
 fi
 
 # 2. Build the builder image (installs toolchain + matching kernel headers).
-echo "==> building image '$IMAGE' (HEADERS_PKG=$HEADERS_PKG KERNEL_VERSION=${KERNEL_VERSION:-latest})"
+echo "==> building image '$IMAGE' (SUITE=$SUITE HEADERS_PKG=$HEADERS_PKG KERNEL_VERSION=${KERNEL_VERSION:-latest})"
 docker build --platform linux/arm64 \
+	--build-arg DEBIAN_SUITE="$SUITE" \
 	--build-arg HEADERS_PKG="$HEADERS_PKG" \
 	--build-arg KERNEL_VERSION="$KERNEL_VERSION" \
 	-t "$IMAGE" .