docs: document OpenWrt cfg80211 backport builds

27af5ad added the CFG80211_VERSION make variable for OpenWrt builds that use a newer mac80211 backport than the target kernel, but it is only described in a Makefile comment. Document how to pass it from an OpenWrt package Makefile, link the notes from the installation steps, and add the build script and the kernel/backports combinations verified for issue #94. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-26 17:44:16 +00:00 · 2026-09-24 14:59:53 +08:00
parent a86affa3c6
commit 332677e771
4 changed files with 156 additions and 0 deletions
@@ -0,0 +1,67 @@
+# Building with OpenWrt backports
+
+OpenWrt's target kernel and wireless stack can have different versions.
+For example, [issue #94](https://github.com/shenmintao/aic8800d80/issues/94)
+uses Linux **6.12.94** with **backports 6.18.26** on OpenWrt 25.12.5.
+The Ubuntu build host's kernel version is not used to select these APIs.
+
+## Package Makefile
+
+Pass `CFG80211_VERSION=6.18.26` to the kernel make invocation for that
+combination. Use the `PKG_VERSION` from your OpenWrt
+`package/kernel/mac80211/Makefile`, in `major.minor.patch` format. Keep the
+backports include paths and symbol versions from the same build:
+
+```make
+NOSTDINC_FLAGS := \
+	$(KERNEL_NOSTDINC_FLAGS) \
+	-I$(STAGING_DIR)/usr/include/mac80211-backport/uapi \
+	-I$(STAGING_DIR)/usr/include/mac80211-backport \
+	-I$(STAGING_DIR)/usr/include/mac80211/uapi \
+	-I$(STAGING_DIR)/usr/include/mac80211 \
+	-include backport/backport.h
+
+define Build/Compile
+	+$(KERNEL_MAKE) $(PKG_JOBS) \
+		M="$(PKG_BUILD_DIR)/drivers/aic8800" \
+		KBUILD_EXTRA_SYMBOLS="$(LINUX_DIR)/../symvers/mac80211.symvers" \
+		NOSTDINC_FLAGS="$(NOSTDINC_FLAGS)" \
+		CFG80211_VERSION=6.18.26 \
+		modules
+endef
+```
+
+The package must depend on `kmod-cfg80211` so its headers and symbol versions
+are staged before this driver is built. Keep any additional dependencies,
+firmware installation rules and module packaging rules your device needs.
+Update the package's pinned source revision to one containing this fix, or
+apply the fix as an OpenWrt package patch, then clean and rebuild the package:
+
+```sh
+make package/kernel/aic8800d80/clean
+make package/kernel/aic8800d80/compile V=sc -j1
+```
+
+Changing `CFG80211_VERSION` alone does not update the driver source or the
+wireless headers. The value must match the actual wireless stack; do not set
+it to the host kernel version or redefine `LINUX_VERSION_CODE`.
+
+## Compatibility scope
+
+The override selects the wireless API changes since Linux 6.12, including
+monitor-channel callbacks, radio/link arguments, radar notifications and
+newer cfg80211 callbacks. Timer, USB, memory-management and module namespace
+checks continue to use the target kernel version. Older target kernels with
+newer backports may need additional wireless API adaptations.
+
+Leave `CFG80211_VERSION` unset when building against the kernel's own wireless
+stack, as on a regular Ubuntu/Debian installation. The driver then uses the
+kernel version as before. Hardware revision still determines whether to use
+`main` or `legacy-mcu1`; a wireless API mismatch does not change that choice.
+
+The feeds/Kconfig duplicate definitions and recursive dependencies also
+reported in issue #94 belong to the OpenWrt build configuration and require
+separate investigation.
+
+See the [build regression recipe](tests/openwrt-backports/README.md) for
+the tested kernel/backports combinations and a script to repeat the build.
@@ -69,6 +69,10 @@ has reached `a69c:8d80` but firmware startup still fails, see

 ### Installation Steps

+For OpenWrt SDK/buildroot builds, see [OpenWrt build notes](OPENWRT.md).
+OpenWrt can use a newer cfg80211 backport than its target kernel; these builds
+must pass the wireless stack version separately.
+
 #### Method 1: [Quick Installation](INSTALL_SCRIPT.md) (Recommended)

 #### Method 2: Manual Installation
@@ -0,0 +1,44 @@
+# OpenWrt backports build regression
+
+This checks complete module compilation and MODPOST against real kernel and
+wireless-stack headers. It requires an already prepared SDK/buildroot with
+cfg80211/mac80211 headers and `mac80211.symvers` staged. It does not install
+packages or load modules.
+
+For the x86_64 SDK used in issue #94:
+
+```sh
+sdk=/path/to/openwrt-sdk
+kernel="$sdk/build_dir/target-x86_64_musl/linux-x86_64/linux-6.12.94"
+export STAGING_DIR="$sdk/staging_dir/target-x86_64_musl"
+export PATH="$sdk/staging_dir/toolchain-x86_64_gcc-14.3.0_musl/bin:$PATH"
+
+bash tests/openwrt-backports/build.sh \
+    "$kernel" "$STAGING_DIR/usr/include" \
+    "$kernel/../symvers/mac80211.symvers" 6.18.26 \
+    ARCH=x86_64 CROSS_COMPILE=x86_64-openwrt-linux-musl-
+```
+
+The script copies the current driver into a fresh temporary directory and
+checks that all three `.ko` files are produced. Additional make arguments
+can select a compiler or architecture. Use matching headers, configuration
+and symbol versions throughout; changing only the version argument is not
+a substitute for the matching wireless stack.
+
+## Verified on 2026-09-17
+
+- OpenWrt 25.12.5 x86_64 SDK: Linux 6.12.94, GCC 14.3.0, backports 6.18.26
+  with the mac80211 patches from OpenWrt revision `f5dae5ece4` applied:
+  all three modules compile and pass MODPOST with the kernel's `-Werror`.
+- Original driver revision `9594c5c`, on the same kernel/backports combination:
+  reproduces both RX argument-count errors and the four incompatible
+  `set_monitor_channel`, `set_wiphy_params`, `set_tx_power`, `get_tx_power`
+  callbacks. This comparison uses `-Wno-error=unused-label`, as the issue's
+  log does, to reach those failures. The fixed build needs no such override.
+- Native kernel headers 6.11.0-17, 6.17.0-14 and 7.2.0-070200, with
+  `CFG80211_VERSION` unset: all three modules compile and pass MODPOST.
+  The 7.2 check uses GCC 14 and reports compiler/attribute warnings because
+  those headers were built with GCC 15.
+
+These are build checks. They do not validate an installable OpenWrt package,
+firmware loading, Wi-Fi connectivity or Bluetooth operation on hardware.
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Compile a source copy against a prepared kernel and staged wireless backport.
+# Leaves the build directory for inspection; does not install or load modules.
+set -euo pipefail
+
+if [ "$#" -lt 4 ]; then
+    echo "Usage: $0 KERNEL_BUILD_DIR STAGED_INCLUDE_DIR MAC80211_SYMVERS CFG80211_VERSION [make arguments...]" >&2
+    exit 2
+fi
+
+kernel_dir=$(realpath "$1")
+include_dir=$(realpath "$2")
+symvers=$(realpath "$3")
+wireless_version=$4
+shift 4
+
+for required in "$kernel_dir/Makefile" "$kernel_dir/Module.symvers" \
+    "$include_dir/mac80211/net/cfg80211.h" \
+    "$include_dir/mac80211-backport/backport/autoconf.h" "$symvers"; do
+    if [ ! -f "$required" ]; then
+        echo "Missing build input: $required" >&2
+        exit 2
+    fi
+done
+
+repo_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+build_dir=$(mktemp -d "${TMPDIR:-/tmp}/aic8800-backports.XXXXXX")
+cp -a "$repo_dir/drivers/aic8800/." "$build_dir/"
+echo "Build directory: $build_dir"
+
+make -C "$kernel_dir" M="$build_dir" \
+    NOSTDINC_FLAGS="-I$include_dir/mac80211-backport/uapi -I$include_dir/mac80211-backport -I$include_dir/mac80211/uapi -I$include_dir/mac80211 -include backport/backport.h" \
+    KBUILD_EXTRA_SYMBOLS="$symvers" \
+    CFG80211_VERSION="$wireless_version" \
+    -j"${JOBS:-2}" "$@" modules
+
+for module in aic_load_fw/aic_load_fw.ko aic8800_fdrv/aic8800_fdrv.ko \
+    aic_zlp_quirk/aic_zlp_quirk.ko; do
+    test -s "$build_dir/$module"
+done
+echo "All three modules built successfully in $build_dir"