test: unify legacy Wi-Fi Bluetooth and ZLP support

# Conflicts: # .gitattributes # README.md
2026-09-26 17:44:16 +00:00 · 2026-07-25 15:54:23 +08:00
parent 1f0c3e28ac 800a7b93ba
commit 51b7b6e729
17 changed files with 1135 additions and 35 deletions
@@ -0,0 +1,12 @@
+KVER ?= $(shell uname -r)
+KDIR ?= /lib/modules/$(KVER)/build
+
+obj-m += aic_zlp_quirk.o
+
+.PHONY: all clean
+
+all:
+	$(MAKE) -C $(KDIR) M=$(CURDIR) modules
+
+clean:
+	$(MAKE) -C $(KDIR) M=$(CURDIR) clean
@@ -0,0 +1,109 @@
+# Issue #63: standard `btusb` ACL ZLP support
+
+The `aic_zlp_quirk` companion module supplies the Bluetooth ACL bulk TX
+zero-length-packet behavior confirmed in
+[issue #63](https://github.com/shenmintao/aic8800d80/issues/63). It is now part
+of the normal `aic8800` DKMS build rather than a replacement for the
+distribution's Bluetooth driver.
+
+The validated failure was specific and reproducible: AAC playback through USB
+device `368b:8d81` stalled after about one minute, while SBC remained stable.
+Adding `URB_ZERO_PACKET` to the ACL bulk OUT URBs kept AAC connected for more
+than one hour. The standalone module was then verified with the system
+`btusb`, no loaded `aic_btusb`, and 2,113 observed ZLP injections.
+
+## Architecture and scope
+
+The module first tries to attach a kretprobe to the standard `btusb` function
+that allocates ACL bulk OUT URBs. The target is module-qualified as
+`btusb:alloc_bulk_urb`, avoiding similarly named symbols in unrelated USB
+drivers.
+
+Some distribution builds inline that private function. When the preferred hook
+is unavailable, the module falls back to the stable `usb_submit_urb` entry
+point. The fallback changes an URB only when all of these checks pass:
+
+- USB device is exactly `368b:8d81`;
+- the transfer is bulk OUT;
+- the endpoint belongs to Bluetooth interface 0 (`e0/01/01`).
+
+Both paths add only `URB_ZERO_PACKET`. Wi-Fi interfaces and unrelated USB
+devices are unchanged. If neither probe can be installed or kprobes are
+disabled, the module refuses to load and system `btusb` remains unchanged.
+
+The module carries a USB modalias for `368b:8d81`, so it is inactive on other
+hardware and normally autoloads only when the validated device appears.
+
+## Install from the unified branch
+
+```bash
+git fetch origin
+git switch test/unified-wifi-bt-zlp
+git pull --ff-only
+sudo ./install.sh
+sudo reboot
+```
+
+The installer removes the earlier `btusb-aic-zlp/0.1` and
+`aic-zlp-quirk/0.1` diagnostic DKMS packages when present. To remove them
+manually before installation, use:
+
+```bash
+sudo dkms remove btusb-aic-zlp/0.1 --all
+sudo dkms remove aic-zlp-quirk/0.1 --all
+sudo depmod -a
+```
+
+The unified installer also removes active configuration left by the obsolete
+custom `aic_btusb` transport.
+
+## Verify
+
+Confirm that system `btusb` owns Bluetooth interfaces 0/1 and that the quirk is
+loaded:
+
+```bash
+lsusb -t
+lsmod | grep -E '^(btusb|aic_zlp_quirk|aic_btusb)\b'
+modinfo -n btusb
+modinfo -n aic_zlp_quirk
+cat /sys/module/aic_zlp_quirk/parameters/hook
+cat /sys/module/aic_zlp_quirk/parameters/injections
+sudo ./diagnose_bt.sh
+```
+
+Expected results include:
+
+```text
+Bluetooth interfaces 0/1: btusb
+aic_btusb: not loaded
+aic_zlp_quirk: loaded
+active hook: btusb:alloc_bulk_urb
+```
+
+`active hook: usb_submit_urb` is also valid when the compiler inlined the
+preferred function. During Bluetooth traffic, the `injections` value must
+increase.
+
+For the promotion test, select AAC and play audio for at least one hour while
+also confirming that Wi-Fi scan, association, DHCP, and real traffic remain
+working.
+
+## Isolated retest helper
+
+`aic-zlp-quirk-test.sh` remains available only for isolated issue #63 retests.
+It builds the same canonical source from
+`drivers/aic8800/aic_zlp_quirk/aic_zlp_quirk.c` as a separate DKMS package. A
+normal installation should use the repository-level `install.sh` instead.
+
+## Kernel requirements
+
+- matching kernel headers;
+- `CONFIG_KPROBES=y` and kretprobe support;
+- standard `btusb` plus either its `alloc_bulk_urb` symbol or the USB core
+  `usb_submit_urb` symbol;
+- a valid module signature when Secure Boot policy requires one.
+
+The preferred function has the same signature in Linux 5.15, 6.1, 6.6, 6.12,
+6.18, and 7.1.3, although compilers may inline it. DKMS builds one module for
+each installed kernel from the single canonical source file.
@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="aic-zlp-quirk"
+PACKAGE_VERSION="0.1"
+MODULE_NAME="aic_zlp_quirk"
+KERNEL_RELEASE="${KERNEL_RELEASE:-$(uname -r)}"
+KERNEL_BUILD_DIR="/lib/modules/${KERNEL_RELEASE}/build"
+SOURCE_DIR="/usr/src/${PACKAGE_NAME}-${PACKAGE_VERSION}"
+MODULES_LOAD_FILE="/etc/modules-load.d/${PACKAGE_NAME}.conf"
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
+QUIRK_SOURCE="${REPO_ROOT}/drivers/aic8800/aic_zlp_quirk/aic_zlp_quirk.c"
+
+log() {
+    printf '[aic-zlp-quirk-test] %s\n' "$*"
+}
+
+die() {
+    printf '[aic-zlp-quirk-test] ERROR: %s\n' "$*" >&2
+    exit 1
+}
+
+require_root() {
+    [ "$(id -u)" -eq 0 ] || die "run this command as root"
+}
+
+require_command() {
+    command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"
+}
+
+stop_bluetooth() {
+    if command -v systemctl >/dev/null 2>&1; then
+        systemctl stop bluetooth.service 2>/dev/null || true
+    fi
+}
+
+start_bluetooth() {
+    if command -v systemctl >/dev/null 2>&1; then
+        systemctl start bluetooth.service 2>/dev/null || true
+    fi
+}
+
+module_loaded() {
+    [ -d "/sys/module/$1" ]
+}
+
+legacy_btusb_loaded() {
+    module_loaded aic_btusb
+}
+
+patched_btusb_installed() {
+    dkms status -m btusb-aic-zlp -v 0.1 2>/dev/null | grep -q .
+}
+
+copy_sources() {
+    install -d "${SOURCE_DIR}"
+    install -m 0644 "${QUIRK_SOURCE}" "${SOURCE_DIR}/"
+    install -m 0644 "${SCRIPT_DIR}/Makefile" "${SOURCE_DIR}/"
+    install -m 0644 "${SCRIPT_DIR}/dkms.conf" "${SOURCE_DIR}/"
+}
+
+rollback_install() {
+    log "rolling back the ZLP companion module"
+    rm -f -- "${MODULES_LOAD_FILE}"
+    modprobe -r "${MODULE_NAME}" >/dev/null 2>&1 || true
+    dkms remove -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" --all >/dev/null 2>&1 || true
+    rm -rf -- "${SOURCE_DIR}"
+    depmod -a "${KERNEL_RELEASE}" >/dev/null 2>&1 || true
+    start_bluetooth
+}
+
+verify_standard_btusb() {
+    if legacy_btusb_loaded; then
+        die "obsolete aic_btusb is loaded; run 'sudo modprobe -r aic_btusb' and remove its old autoload configuration first"
+    fi
+
+    if patched_btusb_installed; then
+        die "the patched btusb test package is still installed; remove it before testing the companion module"
+    fi
+
+    modprobe btusb || die "could not load the system btusb module"
+}
+
+install_module() {
+    require_root
+    require_command dkms
+    require_command make
+    require_command modprobe
+    require_command depmod
+
+    [ -r "${KERNEL_BUILD_DIR}/Makefile" ] || \
+        die "kernel build tree not found: ${KERNEL_BUILD_DIR}"
+
+    if command -v lsusb >/dev/null 2>&1 && ! lsusb -d 368b:8d81 >/dev/null 2>&1; then
+        die "this test is restricted to USB device 368b:8d81, which is not connected"
+    fi
+
+    verify_standard_btusb
+
+    if module_loaded "${MODULE_NAME}"; then
+        log "unloading the earlier companion module"
+        if ! modprobe -r "${MODULE_NAME}"; then
+            die "could not unload the earlier ${MODULE_NAME} module"
+        fi
+    fi
+
+    trap rollback_install ERR
+
+    if dkms status -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" 2>/dev/null | grep -q .; then
+        log "removing an earlier companion-module build"
+        dkms remove -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" --all
+    fi
+
+    rm -rf -- "${SOURCE_DIR}"
+    copy_sources
+
+    log "building the ZLP companion module for ${KERNEL_RELEASE}"
+    dkms add -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}"
+    dkms build -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" -k "${KERNEL_RELEASE}"
+    dkms install -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" \
+        -k "${KERNEL_RELEASE}" --force
+    depmod -a "${KERNEL_RELEASE}"
+
+    printf '%s\n' "${MODULE_NAME}" > "${MODULES_LOAD_FILE}"
+
+    stop_bluetooth
+    if ! modprobe "${MODULE_NAME}"; then
+        trap - ERR
+        rollback_install
+        die "the companion module could not attach; the system btusb was left unchanged"
+    fi
+    start_bluetooth
+    trap - ERR
+
+    log "loaded module: $(modinfo -n "${MODULE_NAME}")"
+    log "system btusb remains active; test AAC playback for at least one hour"
+}
+
+remove_module() {
+    require_root
+    require_command dkms
+    require_command modprobe
+    require_command depmod
+
+    stop_bluetooth
+    rm -f -- "${MODULES_LOAD_FILE}"
+    if module_loaded "${MODULE_NAME}" && ! modprobe -r "${MODULE_NAME}"; then
+        start_bluetooth
+        die "could not unload ${MODULE_NAME}; no files were removed"
+    fi
+    if dkms status -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" 2>/dev/null | grep -q .; then
+        if ! dkms remove -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" --all; then
+            start_bluetooth
+            die "DKMS removal failed; source files were left in place"
+        fi
+    fi
+    rm -rf -- "${SOURCE_DIR}"
+    depmod -a "${KERNEL_RELEASE}"
+    start_bluetooth
+
+    log "removed the companion module; the distribution btusb was never replaced"
+}
+
+show_aic_binding() {
+    local device
+    local driver
+
+    for device in /sys/bus/usb/devices/*; do
+        [ -r "${device}/idVendor" ] || continue
+        [ -r "${device}/idProduct" ] || continue
+        [ "$(cat "${device}/idVendor")" = "368b" ] || continue
+        [ "$(cat "${device}/idProduct")" = "8d81" ] || continue
+
+        driver="not bound"
+        if [ -L "${device}:1.0/driver" ]; then
+            driver="$(basename "$(readlink -f "${device}:1.0/driver")")"
+        fi
+
+        printf 'AIC BT driver: %s\n' "${driver}"
+        return
+    done
+
+    printf 'AIC BT driver: device not found\n'
+}
+
+show_status() {
+    local loaded="no"
+    local injections="unavailable"
+    local hook="unavailable"
+    local dkms_status
+
+    if module_loaded "${MODULE_NAME}"; then
+        loaded="yes"
+        if [ -r "/sys/module/${MODULE_NAME}/parameters/injections" ]; then
+            injections="$(cat "/sys/module/${MODULE_NAME}/parameters/injections")"
+        fi
+        if [ -r "/sys/module/${MODULE_NAME}/parameters/hook" ]; then
+            hook="$(cat "/sys/module/${MODULE_NAME}/parameters/hook")"
+        fi
+    fi
+
+    dkms_status="$(dkms status -m "${PACKAGE_NAME}" -v "${PACKAGE_VERSION}" 2>/dev/null || true)"
+    if [ -z "${dkms_status}" ]; then
+        dkms_status="not installed"
+    fi
+
+    printf 'kernel:        %s\n' "${KERNEL_RELEASE}"
+    printf 'btusb module:  %s\n' "$(modinfo -n btusb 2>/dev/null || printf 'not found')"
+    printf 'quirk module:  %s\n' "$(modinfo -n "${MODULE_NAME}" 2>/dev/null || printf 'not found')"
+    printf 'quirk loaded:  %s\n' "${loaded}"
+    printf 'active hook:   %s\n' "${hook}"
+    printf 'ZLP injections:%s\n' " ${injections}"
+    printf 'legacy aic_btusb: %s\n' "$(legacy_btusb_loaded && printf 'loaded' || printf 'not loaded')"
+    printf 'dkms status:   %s\n' "${dkms_status}"
+    show_aic_binding
+}
+
+case "${1:-}" in
+    install)
+        install_module
+        ;;
+    remove)
+        remove_module
+        ;;
+    status)
+        show_status
+        ;;
+    *)
+        printf 'Usage: %s {install|remove|status}\n' "$0" >&2
+        exit 2
+        ;;
+esac
@@ -0,0 +1,10 @@
+PACKAGE_NAME="aic-zlp-quirk"
+PACKAGE_VERSION="0.1"
+
+MAKE[0]="make KVER=${kernelver}"
+CLEAN="make KVER=${kernelver} clean"
+
+BUILT_MODULE_NAME[0]="aic_zlp_quirk"
+DEST_MODULE_LOCATION[0]="/updates/dkms"
+
+AUTOINSTALL="yes"
@@ -0,0 +1,87 @@
+# Unified Wi-Fi, Bluetooth, and ZLP branch test
+
+This branch tests replacing the separate `main` and `bluetooth` branches with
+one driver and installer. The Wi-Fi driver and firmware were already identical
+on both branches. This test unifies their installer, migration, diagnostics,
+packaging, and documentation, and adds the device-scoped ZLP fix from issue
+#63 as a third DKMS module.
+
+The expected architecture is:
+
+- `aic_load_fw` initializes every supported adapter and uploads firmware.
+- `aic8800_fdrv` handles Wi-Fi.
+- A combo adapter exposes a Bluetooth HCI USB interface after initialization;
+  the standard Linux `btusb` driver binds through normal USB device matching.
+- A Wi-Fi-only adapter exposes no HCI interface and does not need `btusb`.
+- The retired custom `aic_btusb` module is never installed or used.
+- USB device `368b:8d81` autoloads `aic_zlp_quirk`, which adds
+  `URB_ZERO_PACKET` only to its Bluetooth ACL bulk OUT transfers.
+- The distribution's original `btusb.ko` is never replaced.
+
+The installer deliberately does not force-load `btusb` and does not globally
+unblock Bluetooth through rfkill.
+
+## Install
+
+```bash
+git fetch origin
+git switch test/unified-wifi-bt-zlp
+git pull --ff-only
+sudo ./install.sh
+sudo reboot
+```
+
+## Test a Wi-Fi-only adapter
+
+Confirm that:
+
+1. The Wi-Fi interface is created.
+2. Scanning, association, DHCP, and real traffic work.
+3. No `aic_btusb` module is loaded.
+4. The absence of `btusb` or an HCI controller is treated as normal.
+
+## Test a Wi-Fi/Bluetooth combo adapter
+
+Confirm that:
+
+1. Wi-Fi scanning, association, DHCP, and real traffic work.
+2. `aic_load_fw` uploads the firmware before the HCI interface is used.
+3. The Bluetooth USB interface is bound to the standard `btusb` driver.
+4. `bluetoothctl` can power on, scan, pair, and exchange real traffic.
+5. No `aic_btusb` module, alias, soft dependency, or udev binding rule remains.
+
+## Test the `368b:8d81` ZLP path
+
+In addition to the combo-adapter checks, confirm that:
+
+1. `aic_zlp_quirk` loads automatically and system `btusb` owns interfaces 0/1.
+2. `hook` reports `btusb:alloc_bulk_urb` or `usb_submit_urb`.
+3. The `injections` counter increases during Bluetooth audio traffic.
+4. AAC playback remains connected for at least one hour.
+5. Wi-Fi scan, association, and traffic remain unaffected during the test.
+
+## Collect results
+
+```bash
+git rev-parse --short HEAD
+lsusb
+lsusb -t
+lsmod | grep -E 'aic|btusb|bluetooth'
+iw dev
+bluetoothctl list
+cat /sys/module/aic_zlp_quirk/parameters/{hook,injections} 2>/dev/null || true
+sudo ./diagnose_bt.sh | tee unified-wifi-bt-diagnostic.log
+sudo journalctl -k -b --no-pager | tee unified-wifi-bt-kernel.log
+```
+
+Please attach both logs and identify whether the tested adapter is Wi-Fi-only
+or a combo device.
+
+## Roll back during testing
+
+```bash
+git switch main
+git pull --ff-only
+sudo ./install.sh
+sudo reboot
+```