在 Debian 13(内核 6.12)上给绿联 AX900 编译 WiFi 驱动

在 Debian 13(内核 6.12)上给绿联 AX900 编译 WiFi 驱动

环境:Debian 13 (trixie) / 内核 6.12.117+deb13-amd64 / 绿联 AX900(USB ID 0bda:b851)

驱动版本:Realtek rtl8851bu v1.19.10-95-gd09729e85.20241205

绿联 AX900 这颗 USB 网卡用的是 Realtek RTL8851BU (WiFi 6,2.4/5GHz,同一颗芯片还带蓝牙)。Debian 13 的内核里没有 它的驱动,必须自己编译厂商驱动,而且原始驱动直接 make 是编不过的------它按 2024 年的内核 API 写的,遇到 6.12 有三处不兼容。

这篇文章把整个过程、三处补丁、以及一个几乎所有人都会踩的坑(驱动默认开启调试日志,能把系统日志冲垮)都写清楚,命令可以直接复制。


TL;DR

bash 复制代码
# 1. 依赖
sudo apt update
sudo apt install -y build-essential linux-headers-$(uname -r)

# 2. 拿到 rtl8851bu 源码,解压后进入目录,按第 4 节打 3 个补丁

# 3. 编译安装
make clean
make -j$(nproc) all
sudo make install
sudo depmod -a
sudo modprobe 8851bu

# 4. 确认
lsmod | grep 8851bu
ip -br link

一、先确认你的网卡是不是这颗芯片

插上网卡,执行:

bash 复制代码
lsusb | grep -i realtek

如果你的输出里有这一行:

复制代码
Bus 001 Device 005: ID 0bda:b851 Realtek Semiconductor Corp. 802.11ax WLAN Adapter

那就是 RTL8851BU ,本文适用。0bda:b851 是它的 USB ID,8851BU 和同门的 8831BU 共用一个驱动。

再看内核有没有自带驱动:

bash 复制代码
modinfo rtw89_8851bu

如果报 Module not found,说明内核里确实没有:

bash 复制代码
$ ls /lib/modules/$(uname -r)/kernel/drivers/net/wireless/realtek/rtw89/
rtw89_8851be.ko.xz    ← PCIe 版(8851BE)
rtw89_8851b.ko.xz     ← 公共部分
rtw89_8852ae.ko.xz
...

注意这里只有 rtw89_8851be(PCIe 版) ,没有 8851bu(USB 版)。所以内核的 rtw89 帮不上忙,只能编厂商驱动。


二、准备编译环境

bash 复制代码
sudo apt update
sudo apt install -y build-essential linux-headers-$(uname -r)

确认版本对得上(必须完全一致,否则编出来的模块加载不了):

bash 复制代码
uname -r
# 6.12.117+deb13-amd64
ls /usr/src/ | grep linux-headers
# linux-headers-6.12.117+deb13-amd64

三、获取驱动源码

渠道有两种:

  1. Realtek 官方发布包 (文件名类似 rtl8851bu_linux_v1.19.10_xxx.zip),最稳妥;
  2. 第三方镜像仓库 ,例如:

镜像的版本可能和官方不同,解压后先看 include/rtw_version.h 里的版本号,本文基于 v1.19.10-95-gd09729e85.20241205。版本不同,补丁的行号会有偏移,但改法是一样的。


四、让驱动在 6.12 内核上编过(三处补丁)

直接 make 会连续报错,本质是内核 API 做了三处不兼容修改。全部用 LINUX_VERSION_CODE 宏包起来,这样同一个源码在旧内核上也能编。

4.1 cfg80211_ops.set_monitor_channel 多了 netdev 参数

内核 6.12 给这个回调加了 struct net_device *dev 参数(在 wiphy 之后、chandef 之前)。

修改 os_dep/linux/ioctl_cfg80211.c:

diff 复制代码
 static int cfg80211_rtw_set_monitor_channel(struct wiphy *wiphy
+#if (LINUX_VERSION_CODE >= KERNEL_VERSION(6, 12, 0))
+	, struct net_device *dev
+#endif
 #if (LINUX_VERSION_CODE >= KERNEL_VERSION(3, 8, 0))
 	, struct cfg80211_chan_def *chandef
 #else
 	, struct ieee80211_channel *chan
 	, enum nl80211_channel_type channel_type
 #endif
 	)
 {
 	_adapter *padapter = wiphy_to_adapter(wiphy);
 	struct rtw_chan_def target_chdef = {0};
 	u8 ht_option;
 	struct _ADAPTER_LINK *padapter_link = GET_PRIMARY_LINK(padapter);
 
+#if (LINUX_VERSION_CODE >= KERNEL_VERSION(6, 12, 0))
+	(void)dev;
+#endif

新签名是 cfg80211_cac_event(netdev, chandef, event, gfp, link_id)。os_dep/linux/wifi_regd.c 里有两处调用(异步 worker 和同步分支),都要补最后一个参数 0:

diff 复制代码
-		cfg80211_cac_event(evt->netdev, &evt->chandef, evt->event, GFP_KERNEL);
+		cfg80211_cac_event(evt->netdev, &evt->chandef, evt->event, GFP_KERNEL, 0);
diff 复制代码
-			cfg80211_cac_event(iface->pnetdev, &chdef, event, GFP_KERNEL);
+			cfg80211_cac_event(iface->pnetdev, &chdef, event, GFP_KERNEL, 0);

4.3 wdev->cac_started 被挪进了 links[0]

6.12 的多链路改造把 CAC 状态从 struct wireless_dev 顶层移到了 links[0]。在 os_dep/linux/wifi_regd.c 顶部加一个宏:

c 复制代码
#if (LINUX_VERSION_CODE >= KERNEL_VERSION(6, 12, 0))
/* Kernel 6.12 moved the CAC state from struct wireless_dev into links[0] */
#define RTW_WDEV_CAC_STARTED(wdev)	((wdev)->links[0].cac_started)
#else
#define RTW_WDEV_CAC_STARTED(wdev)	((wdev)->cac_started)
#endif

然后把文件里所有 iface->rtw_wdev->cac_started(共 4 处)替换成宏调用:

diff 复制代码
-		if (!iface->rtw_wdev || !iface->rtw_wdev->cac_started)
+		if (!iface->rtw_wdev || !RTW_WDEV_CAC_STARTED(iface->rtw_wdev))

三处修改汇总

报错位置 文件 原因
set_monitor_channel 参数数量不匹配 os_dep/linux/ioctl_cfg80211.c 6.12 新增 netdev 参数
cfg80211_cac_event 参数数量不匹配 os_dep/linux/wifi_regd.c 6.12 新增 link_id 参数
struct wireless_dev 无 cac_started 成员 os_dep/linux/wifi_regd.c 字段移入 links[0]

这三处都只影响监听模式 和 DFS 雷达检测,不碰正常的收发数据路径,所以改完可以放心用。


五、编译与安装

bash 复制代码
cd rtl8851bu     # 源码目录
make clean
make -j$(nproc) all

编完应该生成 8851bu.ko。然后:

bash 复制代码
sudo make install
sudo depmod -a
sudo modprobe 8851bu

make install 会把它装到:

复制代码
/lib/modules/$(uname -r)/kernel/drivers/net/wireless/8851bu.ko

两个小提醒:

  • 不要用 sudo make ,会让生成的 .o 全变成 root 所有,下次普通用户编译就失败;
  • 厂商的 make clean 清不干净,会残留一个 .module-common.o,想彻底重来就手动 rm -f .module-common.o。

六、验证

bash 复制代码
lsmod | grep 8851bu
# 8851bu   8118272  0
# cfg80211 1404928  1 8851bu

ip -br link
# wlx001122334455  UP  192.168.1.100/24 ...   (接口名 = wlx + MAC)

dmesg | tail -20

网卡接口名通常是 wlx 加 MAC 地址。用 NetworkManager 或 nmcli 连 WiFi:

bash 复制代码
nmcli device wifi list
nmcli device wifi connect "你的SSID" password "你的密码"

七、必做:关掉驱动的调试日志(重点)

这是我踩得最狠的一个坑,单独列一节。

这个厂商驱动默认是"调试编译版" :Makefile 里

make 复制代码
CONFIG_RTW_DEBUG = y
CONFIG_RTW_LOG_LEVEL = 4        # 4 = INFO
CONFIG_RTW_PHL_LOG_LEVEL = 4    # 4 = INFO

结果是驱动内部所有调试信息都往内核日志里灌。实测数据:

场景 时长 内核日志条数
开机后一段时间 6 分 43 秒 RTW: 10,567 条 + PHL: 3,281 条
另一次开机 18 分钟 RTW: 26,901 条 + PHL: 2,511 条

大概 每分钟 1500~2000 条 。后果不只是日志难看:我的机器一次连续运行 26 小时的记录,journalctl 里只存下了最近 2 小时------更早的全被这些日志刷掉了。真出问题的时候,什么线索都查不到。

改法

第一步 ,改 Makefile:

diff 复制代码
 CONFIG_RTW_DEBUG = y
-CONFIG_RTW_LOG_LEVEL = 4
-CONFIG_RTW_PHL_LOG_LEVEL = 4
+# 0=NONE 1=ALWAYS 2=ERR 3=WARN 4=INFO 5=DEBUG
+CONFIG_RTW_LOG_LEVEL = 2
+CONFIG_RTW_PHL_LOG_LEVEL = 2

第二步 ,删掉源码里一行残留的调试 printk(在 core/rtw_xmit.c,每次初始化都会打印 eric-tx CALL alloc_txring !!!!):

diff 复制代码
 #ifdef RTW_PHL_TX //alloc xmit resource
-	printk("eric-tx CALL alloc_txring !!!!\n");
 	if (alloc_txring(padapter) == _FAIL) {

然后重新 make clean && make -j$(nproc) all && sudo make install,最后:

bash 复制代码
sudo modprobe -r 8851bu
sudo modprobe 8851bu

效果

改之前 改之后
内核日志量 1500~2000 条/分钟 0 条(只保留错误)
日志留存 26 小时只剩 2 小时 完整保留

随时检查有没有复发(需要 root 才能读内核日志):

bash 复制代码
sudo journalctl -k -b | grep -c 'RTW:'

⚠️ 一个反直觉的点

不要 把 CONFIG_RTW_DEBUG 直接设成 n。源码里 #ifdef CONFIG_RTW_DEBUG ... #endif 没有 #else 分支 ,关掉之后所有 RTW_INFO() / PHL_INFO() 宏都不存在,33 个文件会报"函数未定义",根本编不过。

正确做法就是:保留 debug 编译,但把日志级别降到 2(只输出 ERROR)。


八、常见疑问

Q:日志里的 PHL: Rx reorder timer expired, sta=0x... 是故障吗?

不是。这是 802.11 接收端乱序重组缓冲区的超时释放:缺了一个 MPDU,等 500ms 还没到,就把后面的帧先放行。代码逻辑和内核 mac80211 的 ieee80211_sta_reorder_release() 一致,属于设计内行为。它只是用 INFO 级别打印,配合上面的降级就不刷了。

Q:TXPWR_ByRate.txt:: Error reading file、prepare ext_regd_name[0] = NULL 要紧吗?

不要紧。这是驱动找不到可选的发射功率表和扩展监管域文件,会退回内置默认值,不影响使用。我这边旧版本日志里也有,不是编译引入的。

Q:想把日志临时调详细怎么办?

两个级别生效方式不一样:

bash 复制代码
# 驱动级:可以运行时改,立即生效
sudo sh -c 'echo 4 > /sys/module/8851bu/parameters/rtw_drv_log_level'

# PHL 级:只在模块加载时读取,需要重新加载
sudo modprobe -r 8851bu
sudo modprobe 8851bu rtw_phl_log_level=4

Q:内核一升级,网卡就没了?

正常。out-of-tree 模块不跟着内核走,升级内核后必须先装新内核的头文件、再重编、最后重启:

bash 复制代码
sudo apt install linux-headers-$(uname -r)   # 装当前内核的
make clean && make -j$(nproc) all
sudo make install && sudo depmod -a
sudo modprobe -r 8851bu; sudo modprobe 8851bu

顺序反了(先重启再说)就会出现"新内核启动、没有网卡"的局面,只能插网线或者用旧内核恢复。

Q:蓝牙要单独装吗?

不用。这颗芯片的蓝牙走内核自带的 btrtl,固件 rtl_bt/rtl8851bu_fw.bin 由 linux-firmware 提供,WiFi 驱动装好、系统更新过固件包就能用。

Q:插上没反应,ip link 里没有 wlx 接口?

按顺序排查:

bash 复制代码
lsusb | grep 0bda          # 硬件认到了吗
dmesg | tail -50           # 模块加载报错吗
lsmod | grep 8851bu        # 模块在吗

另外,如果开了 Secure Boot ,未签名的 out-of-tree 模块会被内核拒绝加载(dmesg 里会有 Loading of unsigned module is rejected),需要签名(MOK)或关掉 Secure Boot。


九、小结

  1. 绿联 AX900 = RTL8851BU,Debian 13 内核只有 PCIe 版 rtw89_8851be,没有 USB 版,只能编厂商驱动;
  2. 6.12 上有三处 API 变化,按第 4 节打补丁即可,全部用版本宏保护;
  3. 编完一定要把日志级别从 4 降到 2,否则驱动会用每分钟上千条日志把你的系统日志冲掉------这一步比补丁更重要;
  4. 内核升级后要重编,顺序不能反。

参考

本文的补丁、日志数据均来自一台 Debian 13 + 内核 6.12.117 的真机实测。