docs: document PREFER_NATIVE_ARMHF and enrich arm64-compat-vdso entry

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`

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.
 
 ---