feat(extensions): native-armhf-on-arm64 acceleration via runtime-disable of qemu-arm

Opt-in extension that disables qemu-arm in binfmt_misc for the duration
of an armhf build on an aarch64 host. The kernel's binfmt_elf path then
runs 32-bit ARM ELF binaries natively via CONFIG_COMPAT, removing the
~10× qemu-user-static overhead from mmdebstrap, chroot apt-get, dpkg
--configure, and customize_image stages.

Activate with ENABLE_EXTENSIONS=native-armhf-on-arm64.

Scope:
  - host_pre_docker_launch hook: self-gates on ARCH=armhf and aarch64
    host arch; refuses to run on hosts where qemu-arm is unregistered;
    probes arch-test armhf POST-disable with automatic rollback if the
    kernel cannot run armhf natively (no CONFIG_COMPAT);
    add_cleanup_handler on success so build exit restores qemu-arm.
  - No core changes. No global-state coordination claims.
  - Restrictions documented in the file header: NO CONCURRENT ARMBIAN
    BUILDS on the same host while the extension is active.

Why an extension (and not a core feature):
  - The acceleration only applies to armhf-on-aarch64; no benefit for
    other ARCH/host combos.
  - Concurrent-safe coordination in core would require kernel-level
    flock dance on /proc/sys/fs/binfmt_misc/qemu-arm (see PR armbian#9769),
    which is large, hard to review and to test; extension scope makes
    the operator the source of truth for host serialization and lets
    the implementation stay ~80 lines.
  - Cleanup is best-effort: a SIGKILL'd build leaves qemu-arm disabled.
    Documented in the header with manual restore instructions.

Validated:
  - aarch64 Ubuntu Noble kernel 6.8.x (Hetzner CAX), no COMPAT_VDSO
    needed in stock builds.

Assisted-by: Claude:claude-opus-4.7

Author: iav

extensions/native-armhf-on-arm64.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# SPDX-License-Identifier: GPL-2.0
+#
+# Native armhf-on-aarch64 acceleration.
+#
+# Activate with ENABLE_EXTENSIONS=native-armhf-on-arm64.
+#
+# WHAT
+#   On an aarch64 host building an armhf target, disable qemu-arm in
+#   binfmt_misc for the duration of the build. The kernel's binfmt_elf
+#   path then runs armhf ELF binaries natively via CONFIG_COMPAT — ~10×
+#   faster than qemu-user-static emulation. mmdebstrap, chroot apt-get,
+#   dpkg --configure, post-install scripts and customize_image all
+#   benefit.
+#
+# REQUIREMENTS
+#   * Host architecture aarch64.
+#   * Host kernel with CONFIG_COMPAT=y (32-bit ARM EL0 support).
+#     CONFIG_COMPAT_VDSO is not strictly required — full mmdebstrap +
+#     post-customize runs were validated on stock Ubuntu Noble (6.8.x)
+#     without COMPAT_VDSO.
+#   * Build target ARCH=armhf (a no-op for any other ARCH).
+#   * qemu-user-static (or qemu-user-binfmt) registered with qemu-arm
+#     enabled in /proc/sys/fs/binfmt_misc/qemu-arm at build start.
+#     The extension verifies this and refuses to run otherwise.
+#   * CAP_SYS_ADMIN on host (the build already runs as root).
+#
+# RESTRICTIONS
+#   * NO CONCURRENT ARMBIAN BUILDS on the same host while this extension
+#     is active. The extension globally disables qemu-arm in binfmt_misc
+#     for the build window. Any other parallel armhf-cross workload on
+#     the host (CI runners, container builds depending on qemu-arm) will
+#     have its armhf binaries routed through the kernel's binfmt_elf
+#     fallback instead of qemu — which works on this host, but may
+#     surprise code that depends on qemu being in the chain.
+#     The operator owns the host while this extension runs.
+#   * If the build is SIGKILL'd or the box crashes before the cleanup
+#     handler fires, qemu-arm stays disabled. Re-enable manually:
+#         sudo update-binfmts --enable qemu-arm
+#     or
+#         echo 1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-arm
+#
+# DESIGN
+#   No flock dance, no userspace coordination, no concurrent-safety
+#   claims. The acceleration is mechanically simple: write 0 to the
+#   binfmt_misc entry, write 1 back on cleanup. The in-core flock-based
+#   variant lives at PR #9769 if you need acceleration that coexists
+#   with concurrent armbian builds on the same host.
+
+function host_dependencies_ready__native_armhf_on_arm64() {
+	# Self-gate: target arch must be armhf. Anything else: no-op, silent.
+	# (We can't pre-compute via extension_prepare_config — that hook runs
+	# only inside the docker container, after the relaunch.)
+	[[ "${ARCH}" == "armhf" ]] || return 0
+
+	declare host_arch
+	host_arch="$(arch)"
+	if [[ "${host_arch}" != "aarch64" ]]; then
+		exit_with_error "${EXTENSION}: enabled but host arch '${host_arch}' is not aarch64; this extension only accelerates armhf on aarch64 hosts."
+	fi
+
+	if [[ ! -e /proc/sys/fs/binfmt_misc/qemu-arm ]]; then
+		exit_with_error "${EXTENSION}: qemu-arm is not registered in binfmt_misc on the host. Install qemu-user-static (or qemu-user-binfmt) and run 'update-binfmts --enable qemu-arm' before retrying."
+	fi
+
+	declare qemu_arm_state
+	qemu_arm_state="$(head -n1 /proc/sys/fs/binfmt_misc/qemu-arm 2> /dev/null || true)"
+	if [[ "${qemu_arm_state}" != "enabled" ]]; then
+		display_alert "${EXTENSION}: qemu-arm already not enabled" "state='${qemu_arm_state}' — nothing to do, leaving alone" "info"
+		return 0
+	fi
+
+	# Probe-with-rollback: disable qemu-arm, verify the kernel can still
+	# run armhf binaries natively, and re-enable + bail if it can't. This
+	# catches misconfigured hosts (kernel without CONFIG_COMPAT) BEFORE
+	# the docker container launches and starts an mmdebstrap that would
+	# silently fail in chroot.
+	display_alert "${EXTENSION}: disabling qemu-arm" "/proc/sys/fs/binfmt_misc/qemu-arm → 0" "info"
+	if ! echo 0 > /proc/sys/fs/binfmt_misc/qemu-arm 2> /dev/null; then
+		exit_with_error "${EXTENSION}: cannot write to /proc/sys/fs/binfmt_misc/qemu-arm. CAP_SYS_ADMIN missing on host?"
+	fi
+
+	if ! arch-test armhf > /dev/null 2>&1; then
+		echo 1 > /proc/sys/fs/binfmt_misc/qemu-arm 2> /dev/null || true
+		exit_with_error "${EXTENSION}: host kernel cannot run armhf natively after disabling qemu-arm (no CONFIG_COMPAT?). Restored qemu-arm and aborting; disable this extension on this host."
+	fi
+
+	declare -g _NATIVE_ARMHF_EXTENSION_DISABLED_QEMU_ARM=yes
+	add_cleanup_handler trap_handler_native_armhf_on_arm64_restore
+	display_alert "${EXTENSION}: armhf chroot execs will run natively via kernel binfmt_elf" "qemu-arm disabled for this build; will be restored on exit" "info"
+}
+
+function trap_handler_native_armhf_on_arm64_restore() {
+	[[ "${_NATIVE_ARMHF_EXTENSION_DISABLED_QEMU_ARM:-no}" == "yes" ]] || return 0
+	[[ -e /proc/sys/fs/binfmt_misc/qemu-arm ]] || return 0
+	if echo 1 > /proc/sys/fs/binfmt_misc/qemu-arm 2> /dev/null; then
+		display_alert "${EXTENSION}: qemu-arm restored" "/proc/sys/fs/binfmt_misc/qemu-arm → 1" "info"
+	else
+		display_alert "${EXTENSION}: failed to restore qemu-arm" "manual fix: echo 1 | sudo tee /proc/sys/fs/binfmt_misc/qemu-arm" "wrn"
+	fi
+	unset _NATIVE_ARMHF_EXTENSION_DISABLED_QEMU_ARM
+}