From 332677e771011a90ead7e1673fe1d0c477e3ba4a Mon Sep 17 00:00:00 2001 From: Shen Mintao Date: Thu, 24 Sep 2026 14:59:37 +0800 Subject: [PATCH] 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) --- OPENWRT.md | 67 +++++++++++++++++++++++++++++++ README.md | 4 ++ tests/openwrt-backports/README.md | 44 ++++++++++++++++++++ tests/openwrt-backports/build.sh | 41 +++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 OPENWRT.md create mode 100644 tests/openwrt-backports/README.md create mode 100755 tests/openwrt-backports/build.sh diff --git a/OPENWRT.md b/OPENWRT.md new file mode 100644 index 0000000..1603a4e --- /dev/null +++ b/OPENWRT.md @@ -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. diff --git a/README.md b/README.md index 62dbadd..2efccd4 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/tests/openwrt-backports/README.md b/tests/openwrt-backports/README.md new file mode 100644 index 0000000..78e5272 --- /dev/null +++ b/tests/openwrt-backports/README.md @@ -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. diff --git a/tests/openwrt-backports/build.sh b/tests/openwrt-backports/build.sh new file mode 100755 index 0000000..1bf283d --- /dev/null +++ b/tests/openwrt-backports/build.sh @@ -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"