feat(extensions/netboot): clarify kernel-only deploy contract — initramfs is build-side only

Initramfs cannot be regenerated correctly outside a full image build:
its content depends on the configured rootfs (customize_image hooks,
/etc/initramfs-tools tweaks, board-specific extensions, userpatches
overlay), and that context survives only during the build itself.
After deploy the configured rootfs lives only on the NFS server, which
may be OpenWRT/embedded/etc. and cannot run chroot+update-initramfs;
regenerating from the generic post-debootstrap rootfs cache would
produce a *different* initramfs than the one the full build would have
made — fake, not just incomplete.

Therefore artifact_ready__netboot_kernel_deploy now:

  - drops any pre-existing uInitrd from TFTP after the kernel rsync,
    so U-Boot does not pair the new kernel with a stale initramfs whose
    modules have a wrong vermagic
  - replaces the previous 'run update-initramfs on the server' guidance
    (which was wrong — server-side regen is impossible on most servers
    and produces a wrong initramfs even where it is) with a clear
    contract: 'for a fresh initramfs do a full image rebuild'
  - documents the boot-time consequence in the function header: boards
    with built-in boot networking (mvneta, etc.) come up cleanly
    without initramfs; modular-NIC boards fail fast at networking and
    the operator knows to do a full rebuild

README 'Kernel-only deploy' section reframed as a narrow optimization
for built-in-NIC boards rather than a general kernel refresh path,
with explicit guidance on when to use it vs the full image rebuild.

Closes the long-standing P2 (NETBOOT_DEPLOY_REGENERATE_INITRD) by
contract clarification, not deferred TODO: standalone initramfs
regeneration is an architecturally wrong frame, removed from scope.

Assisted-by: Claude:claude-opus-4.7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>

Author: iav

extensions/netboot/README.md

@@ -179,11 +179,14 @@ is skipped — only TFTP is deployed.
 
 #### Kernel-only deploy
 
-The same extension also exposes an `artifact_ready` handler that fires
-after a stand-alone `compile.sh kernel ...` run (no image build, no
-rootfs archive). It unpacks the produced `linux-image-${BRANCH}-${LINUXFAMILY}_*.deb`
-and rsyncs vmlinuz + dtbs into `${NETBOOT_DEPLOY_TFTP_ROOT}/${NETBOOT_TFTP_PREFIX}/`
-and `/lib/modules/${kver}/` into the NFS rootfs at `${NETBOOT_NFS_PATH}/lib/modules/${kver}/`.
+A narrow optimization for **boards whose boot networking driver is built
+into the kernel** (e.g. helios64 mvneta, helios4 mvneta — anything where
+`root=/dev/nfs ip=dhcp` works without an initramfs). On such boards a
+fresh kernel can be deployed without rebuilding the rootfs or initramfs
+at all, which turns a 15-minute full image rebuild into a 10-second
+incremental refresh — useful for kernel debugging and config iteration.
+
+Triggered by `compile.sh kernel ...`:
 
 ```bash
 ./compile.sh iav kernel \
@@ -192,26 +195,46 @@ and `/lib/modules/${kver}/` into the NFS rootfs at `${NETBOOT_NFS_PATH}/lib/modu
     NETBOOT_DEPLOY_SSH=root@m1
 ```
 
+The `artifact_ready` handler unpacks the produced
+`linux-image-${BRANCH}-${LINUXFAMILY}_*.deb`, rsyncs `vmlinuz` and dtbs
+into `${NETBOOT_DEPLOY_TFTP_ROOT}/${NETBOOT_TFTP_PREFIX}/`, syncs
+`/lib/modules/${kver}/` (with `--delete`) into the NFS rootfs at
+`${NETBOOT_NFS_PATH}/lib/modules/${kver}/`, and **removes any
+pre-existing `uInitrd`** from the TFTP prefix.
+
 This closes a coherence gap that otherwise produces `BPF: Invalid
 name_offset:N` and `failed to validate module BTF: -22` spam on boot:
 split-BTF references in `.ko` modules point to the BTF inside the
 running vmlinux; if the kernel image and the modules in `/lib/modules/`
 come from different build runs, every match resolves to a wrong string
 offset. Coherent kernel + modules deployed together fix it.
 
-**Caveat — initramfs is not regenerated.** A new module ABI may need a
-fresh initrd. After the kernel deploy, run:
-
-```bash
-ssh root@m1 \
-    'chroot /srv/netboot/rootfs/shared/<board>/<branch>-<release> \
-        update-initramfs -u -k <kver>'
-```
-
-or rebuild the full image (`compile.sh build ROOTFS_TYPE=nfs-root ...`)
-when the kernel ABI moves enough to need it. Cross-architecture
-chroot needs `qemu-user-static` + `binfmt_misc` registered on the
-**server** (not the build host).
+**Initramfs is intentionally not regenerated, by design.** Initramfs
+content depends on the *configured* rootfs — `customize_image` hooks,
+`/etc/initramfs-tools/*` tweaks, board-specific extensions, userpatches
+overlay — and that context only exists during a full image build. Past
+that build, the configured rootfs lives only on the NFS server, which
+may be an OpenWRT box or anything else that cannot run
+chroot+update-initramfs. Regenerating from a generic post-debootstrap
+rootfs cache would produce a *different* initramfs than the one a full
+image build would have made — wrong, not just incomplete.
+
+So the kernel-only deploy drops the previous build's `uInitrd` and lets
+the kernel boot without an initramfs:
+
+- **Boards with built-in boot networking**: `root=/dev/nfs ip=dhcp` runs
+  directly from kernel — clean boot, every time. Modules under
+  `/lib/modules/${kver}/` get loaded later for non-boot-critical drivers
+  (WiFi, BT, etc.).
+- **Boards needing modular drivers in initramfs** (USB-eth, modular NIC,
+  modular SATA, etc.): kernel will fail fast at networking instead of
+  silently corrupting later. The fix for those boards is **not** a kernel
+  refresh — it is a full image rebuild
+  (`compile.sh build ROOTFS_TYPE=nfs-root ...`), which produces a fresh
+  initramfs alongside the kernel.
+
+Use the kernel-only path when you know your board falls in the first
+category. If unsure, the full image rebuild is always the safe choice.
 
 ## Build artifacts matrix
 

extensions/netboot/netboot-deploy.sh

@@ -447,10 +447,29 @@ function netboot_artifacts_ready__deploy_to_remote_server() (
 # Standalone-kernel deploy: fired by core's `artifact_ready` after a
 # `compile.sh kernel ...` run. No image, no rootfs archive — the canonical
 # linux-image-${BRANCH}-${LINUXFAMILY} .deb is unpacked locally; vmlinuz +
-# dtbs go to TFTP, /lib/modules/<ver>/ goes to the NFS rootfs. Closes the
-# split-BTF coherence gap: a fresh kernel was getting paired with stale
-# modules in the on-NFS rootfs, producing `BPF: Invalid name_offset` spam
-# until a full image rebuild.
+# dtbs go to TFTP, /lib/modules/<ver>/ goes to the NFS rootfs.
+#
+# Scope: kernel + modules only. Initramfs is intentionally NOT regenerated
+# here — it depends on the rootfs that was customized at full image build
+# time (customize_image hooks, /etc/initramfs-tools tweaks, board-specific
+# extensions, userpatches overlay), and that context does not survive on
+# the build host past the original image deploy. The configured rootfs now
+# lives only on the NFS server, which may be an OpenWRT box or anything
+# else that cannot run chroot+update-initramfs. Regenerating from the
+# generic post-debootstrap rootfs cache would produce a *different*
+# initramfs than the one the full image build would have made — fake.
+#
+# Therefore: any pre-existing uInitrd on TFTP is removed so U-Boot does
+# not load an initramfs whose modules have stale vermagic against the
+# new kernel. Boards with built-in boot networking (mvneta, etc.) come
+# up cleanly without initramfs via root=/dev/nfs ip=dhcp; boards that
+# need modular drivers in initramfs (USB-eth, modular NICs) will fail
+# fast at networking — the fix for those is a full image rebuild, not
+# a kernel-only refresh.
+#
+# Closes the split-BTF coherence gap: a fresh kernel was getting paired
+# with stale modules in the on-NFS rootfs, producing `BPF: Invalid
+# name_offset` spam until a full image rebuild.
 function artifact_ready__netboot_kernel_deploy() (
 	declare scratch_key=""
 	declare scratch_dir=""
@@ -571,6 +590,21 @@ function artifact_ready__netboot_kernel_deploy() (
 		"${kernel_src}" \
 		"${NETBOOT_DEPLOY_SSH}:${NETBOOT_DEPLOY_TFTP_ROOT}/${NETBOOT_TFTP_PREFIX}/${kernel_name}"
 
+	# Drop any pre-existing uInitrd from TFTP. See the function's header
+	# comment for the full rationale: kernel-only deploy intentionally does
+	# not regenerate initramfs (cannot, without the configured rootfs context),
+	# and leaving the previous full-image build's uInitrd next to a fresh
+	# kernel would have U-Boot load it and the kernel hit vermagic mismatches
+	# inside initramfs's modprobe. Removing it makes U-Boot proceed without
+	# initramfs — clean boot on built-in-NIC boards, fail-fast on modular-NIC
+	# ones (the operator then knows to do a full image rebuild).
+	declare q_uinitrd_path
+	q_uinitrd_path="'${NETBOOT_DEPLOY_TFTP_ROOT//\'/\'\\\'\'}/${NETBOOT_TFTP_PREFIX//\'/\'\\\'\'}/uInitrd'"
+	display_alert "${EXTENSION}: drop stale uInitrd from TFTP" \
+		"${NETBOOT_DEPLOY_SSH}:${NETBOOT_DEPLOY_TFTP_ROOT}/${NETBOOT_TFTP_PREFIX}/uInitrd" "info"
+	run_host_command_logged_raw ssh "${ssh_opts[@]}" "${NETBOOT_DEPLOY_SSH}" \
+		"${sudo_prefix}rm -f ${q_uinitrd_path}"
+
 	# DTBs: linux-image deb stages them under /usr/lib/linux-image-<ver>/.
 	# netboot.sh on a full image rebuild flattens them into ${NETBOOT_TFTP_PREFIX}/dtb/
 	# (e.g. dtb/rockchip/rk3399-helios64.dtb). Reproduce that layout exactly so
@@ -606,10 +640,10 @@ function artifact_ready__netboot_kernel_deploy() (
 
 	display_alert "${EXTENSION}: kernel deploy done" \
 		"${NETBOOT_DEPLOY_SSH} (kver=${kver})" "info"
-	# Initramfs is intentionally left alone: regenerating it requires a
-	# chroot into the NFS rootfs (cross-arch needs qemu-user-static binfmt
-	# on the *server*, not the build host). The operator does this manually
-	# or rebuilds the full image when the module ABI changes meaningfully.
+	# Initramfs is not produced here — see the function's header comment.
+	# The previous uInitrd was already dropped from TFTP above; this alert
+	# exists so the operator sees, in the build log, that initramfs is a
+	# concern of the full image build and not of kernel-only deploy.
 	display_alert "${EXTENSION}: skipped initramfs refresh" \
-		"run 'chroot ${NETBOOT_NFS_PATH} update-initramfs -u -k ${kver}' on the server, or rebuild the full image" "warn"
+		"kernel-only deploy cannot regenerate initramfs (depends on configured rootfs context); for a fresh initramfs do a full image rebuild" "warn"
 )