From bd0f9765a51f59505a08a6119c1e5c734cccc950 Mon Sep 17 00:00:00 2001
From: Igor Velkov <325961+iav@users.noreply.github.com>
Date: Tue, 26 May 2026 05:14:38 +0300
Subject: [PATCH] docs: document PREFER_NATIVE_ARMHF and enrich
 arm64-compat-vdso entry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a Build-Switches entry for the new opt-out switch (default yes) that gates
native armhf execution on arm64 hosts with CONFIG_COMPAT, with an inline check
recipe and a link to the arm64 Kconfig.

Expand the arm64-compat-vdso entry in the Extensions reference to cover the
practical effect (native armhf userspace at full speed, ~10× faster Armbian
rootfs builds) and the Apple-M-series limitation, and cross-link the switch.

Assisted-by: Claude:claude-opus-4.7
---
 docs/Developer-Guide_Build-Switches.md  | 27 +++++++++++++++++++++++++
 docs/Developer-Guide_Extensions-List.md |  6 +++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/Developer-Guide_Build-Switches.md b/docs/Developer-Guide_Build-Switches.md
index d1bf38ef..c995ed95 100644
--- a/docs/Developer-Guide_Build-Switches.md
+++ b/docs/Developer-Guide_Build-Switches.md
@@ -325,6 +325,33 @@ Use `$DEST/ccache` as ccache home directory. Setting yes to this will enable CCA
 
 Default is to auto-detect based on build host available RAM. If not enough RAM available, use =no to accept building without BTF debug information, or use =yes to force building with BTF even if low RAM. Family code can set this to opt-out of BTF. For more information on BTF see <https://docs.kernel.org/bpf/btf.html>
 
+**PREFER_NATIVE_ARMHF** ( `string` )
+
+- `yes` (default)
+- `no`
+
+On arm64 build hosts whose kernel supports `CONFIG_COMPAT`, run armhf binaries (rootfs/chroot, package post-install) natively at full speed instead of through `qemu-user-static`. Native execution is roughly 10× faster than qemu emulation. On hosts without 32-bit ARM userspace support (notably Apple Silicon) the framework transparently falls back to qemu. Set `no` to force qemu even when native COMPAT is available.
+
+To build an arm64 Armbian kernel that exposes this capability for the host that runs it, enable the [arm64-compat-vdso extension](Developer-Guide_Extensions-List.md#arm64-compat-vdso) via `ENABLE_EXTENSIONS`. The relevant kernel options are documented in the [arm64 Kconfig](https://elixir.bootlin.com/linux/latest/source/arch/arm64/Kconfig):
+
+- `CONFIG_COMPAT=y` — required; enables 32-bit EL0 support, without which armhf binaries cannot run at all.
+- `CONFIG_COMPAT_VDSO=y` — optional but recommended; provides fast `gettimeofday`/`clock_gettime` for 32-bit processes via vDSO.
+
+To check what a given host kernel ships with:
+
+```bash
+zcat /proc/config.gz | grep -E '^CONFIG_(COMPAT|COMPAT_VDSO)='
+```
+
+A host with native armhf support will print at least `CONFIG_COMPAT=y`; for example:
+
+```bash
+CONFIG_COMPAT=y
+CONFIG_COMPAT_VDSO=y
+```
+
+If the command prints nothing, or `CONFIG_COMPAT` is unset, the host kernel cannot run armhf userspace natively and the build framework will use qemu emulation regardless of this switch.
+
 **ARTIFACT_IGNORE_CACHE** ( `string` )
 
 - `yes`
diff --git a/docs/Developer-Guide_Extensions-List.md b/docs/Developer-Guide_Extensions-List.md
index 1cfe113d..5cc4f62a 100644
--- a/docs/Developer-Guide_Extensions-List.md
+++ b/docs/Developer-Guide_Extensions-List.md
@@ -34,7 +34,11 @@ Enables Armbian Package Archive (APA) in the target image by default.
 
 ## arm64-compat-vdso
 
-Enables 32-bit compat vDSO for arm64 kernels. Requires a 32-bit ARM cross-compiler for GCC builds (`gcc-arm-linux-gnueabi` or custom `CROSS_COMPILE_COMPAT`). For clang builds uses the built-in LLVM backend.
+Builds the arm64 kernel with `CONFIG_COMPAT`, `CONFIG_COMPAT_VDSO` and `CONFIG_ARM64_32BIT_EL0`, letting a host running this kernel execute armhf (32-bit ARM) userspace natively at full speed. One concrete benefit is faster Armbian builds: on such a host, armhf rootfs / chroot / package post-install steps run native instead of through `qemu-user-static` (~10× faster). The build framework auto-detects the capability — see [PREFER_NATIVE_ARMHF](Developer-Guide_Build-Switches.md#prefer_native_armhf).
+
+Requires a 32-bit ARM cross-compiler for GCC builds (`gcc-arm-linux-gnueabi` or custom `CROSS_COMPILE_COMPAT`). For clang builds uses the built-in LLVM backend.
+
+Limitation: aarch64 silicon without 32-bit ARM userspace support at EL0 (notably Apple M-series) cannot run armhf even with this kernel option enabled.
 
 ---