[bong-water-water-bong]

Adds docs/kernel.md, the runbook the Gantt row "Kernel 7.4 readiness" is about: every source is pinned, so a release is a bump, not a scramble. Also records the 2026-10-23 rehearsal of that runbook against the newest tags that exist today.

What the page covers

build -> sign -> install -> grub entry -> reboot (owner) -> mokutil -> hw-gate -> weekly package + 1bit OS image, with the facts that go stale marked as facts and the commands that do not:

• what runs today (v7.3-rc4 + the two IOMMU PerfOpt backports, why: prefill +21–25 %, decode unchanged, greedy output byte-identical), and the out-of-tree modules that must follow every kernel (amdxdna, the fan EC);
• the two MOKs and which one signs what, the postinst.d hook, and the traps: a module-signing-only MOK is rejected for kernel images, an unsigned vmlinuz-*.unsigned in /boot becomes a boot entry, a firmware reset drops the MOKs;
• GRUB_DEFAULT is left alone — the previous kernel stays the fallback and the owner chooses when the box moves;
• the verify sequence after boot, then the hardware gate as the thing that makes a boot more than "it booted";
• the weekly release preflight (VMLINUZ=) and os/mini/mkimage.sh (MOK_KEY/MOK_CERT, the signed UKI), which is where a new kernel lands in the packages.

The rehearsal (2026-10-23)

No v7.4* tag exists (v7.3 final, 2026-10-18; no v7.3.y; the 7.4 merge window is open — torvalds master is Merge tag 'net-next-7.4'). So it ran twice, on a separate 16-core machine, with the config of record (/boot/config-7.3.0-rc4-1bit-perfopt), LLVM=1 clang 21.1.8, nice -n 19 make -j12 bindeb-pkg:

tree	PerfOpt	olddefconfig delta	bindeb-pkg	release
v7.3	backports re-applied (343 insertions, 8 files, no rebase needed)	28 lines (clang + debug info only)	pass, ~15 min	7.3.0-1bit-perfopt+
next-20261022 (7.4 merge-window content)	already native, backports dropped	110 lines (new clang-21/7.4 symbols; drops ANDROID_BINDER*, ARCH_HAS_DEBUG_WX, …)	pass, ~15 min	7.3.0-next-20261022-1bit-perfopt

The out-of-tree amdxdna builds against both trees (MAKE_RC=0, amdxdna.ko), so the most likely 7.4 break is not there yet — worth re-running the moment v7.4-rc1 is tagged, since next is a moving target.

Traps found and written down: libdw-dev is the packaging dependency that stops bindeb-pkg in dpkg-checkbuilddeps; LLVM=1 must be exported or the packaging stage re-enters make with the wrong compiler; the driver's own Makefile exports an empty ARCH, which makes scripts/Makefile.clang abort with add '--target=' option (pass ARCH=x86_64); a tree with commits past its tag gets + in the release string and in module vermagic.

Verification

• python3 tools/copyright.py --check → rc 0 (the new page carries the Apache notice).
• docs/kernel.md is linked from README.md and from the release run section of docs/releases.md.
• Every number in the rehearsal section comes from the two builds above; the box was only read (kernel, config, MOKs, GRUB_DEFAULT, module signers), never installed on or rebooted.

Not done here (deliberately): install, sign, boot and gate on the box — that is the owner's reboot and step 2 to 8 of the runbook; the fan-EC module (its source lives only on the box); throughput re-measurement on the new kernel.

🤖 Generated with Claude Code

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Missing Hardware Context Details The document describes the kernel readiness process but lacks specific details about NPU hardware-context and runlist lifetimes, which are critical for ensuring correctness when moving to a new kernel. These aspects are essential for the 1bit engine's operation on AMD Strix Halo's XDNA 2 NPU. The Strix Halo box runs a kernel we build, not the distribution's: everything the engine and the NPU need is pinned by hand, so the next kernel is a step list, not an investigation. This page is that list, with the facts that go stale marked as facts and the commands that do not. Incomplete MOK Handling While the document mentions two MOKs and their respective purposes, it does not fully address potential issues with MOK enrollment or how to handle cases where MOKs may become invalid or need re-enrollment, especially after firmware resets or Secure Boot changes. | key | path | signs | |---|---|---| | `strixhalo Secure Boot Kernel` (EKU codeSigning) | `/var/lib/shim-signed/mok/MOK-Kernel.{priv,pem,der}` | the kernel image | | `strixhalo Secure Boot MOK` (module-signing OID) | `/var/lib/shim-signed/mok/MOK.{priv,pem,der}` | every `.ko` we build | ```sh # kernel: automatic on install (this is what the hook does), or by hand sudo sbsign --key /var/lib/shim-signed/mok/MOK-Kernel.priv \ --cert /var/lib/shim-signed/mok/MOK-Kernel.pem \ --output /boot/vmlinuz-<version> /boot/vmlinuz-<version> # modules we built ourselves (in-tree modules carry the build-time key already) sudo kmodsign sha512 /var/lib/shim-signed/mok/MOK.priv \ /var/lib/shim-signed/mok/MOK.der updates/amdxdna.ko /etc/kernel/postinst.d/z0-mok-sign signs any kernel image the installer did not sign, and does nothing when sbverify --list already shows a signature. Trap: a MOK whose EKU is module-signing only (Ubuntu's default style) is rejected by shim for kernel images. That is why there are two keys; signing a vmlinuz with MOK.priv produces a kernel that will not boot under Secure Boot. Trap: an unsigned copy left in /boot as vmlinuz-*.unsigned becomes a GRUB menu entry. Keep originals outside /boot (/var/backups/kernels/). A BIOS/firmware reset can drop the enrolled MOKs. The fix needs the owner at the console (MokManager), and can be primed over ssh beforehand: mokutil --import /var/lib/shim-signed/mok/MOK-Kernel.der, then the same for MOK.der, then the owner confirms both in MokManager on the next boot. </details> <details><summary><a href='https://github.com/1bit-MONSTER/engine/pull/525/files#diff-494189164462e19f5ede07003ce7b6850d55d7b4020fd4072f1fd9391c5ca989R112-R114'><strong>Unclear Module Signing Process</strong></a> The document describes module signing but does not specify how to verify that the signing process was successful for all required modules, particularly the out-of-tree modules like `amdxdna` and `ec_su_axb35`, which must be rebuilt and signed against the new kernel. </summary> ```markdown sudo kmodsign sha512 /var/lib/shim-signed/mok/MOK.priv \ /var/lib/shim-signed/mok/MOK.der updates/amdxdna.ko </details> </td></tr> </table>