在 Debian 13(内核 6.12)上给绿联 AX900 编译 WiFi 驱动
环境:Debian 13 (trixie) / 内核
6.12.117+deb13-amd64/ 绿联 AX900(USB ID0bda: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
三、获取驱动源码
渠道有两种:
- Realtek 官方发布包 (文件名类似
rtl8851bu_linux_v1.19.10_xxx.zip),最稳妥; - 第三方镜像仓库 ,例如:
镜像的版本可能和官方不同,解压后先看
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
4.2 cfg80211_cac_event 多了 link_id 参数
新签名是 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。
九、小结
- 绿联 AX900 = RTL8851BU,Debian 13 内核只有 PCIe 版
rtw89_8851be,没有 USB 版,只能编厂商驱动; - 6.12 上有三处 API 变化,按第 4 节打补丁即可,全部用版本宏保护;
- 编完一定要把日志级别从 4 降到 2,否则驱动会用每分钟上千条日志把你的系统日志冲掉------这一步比补丁更重要;
- 内核升级后要重编,顺序不能反。
参考
- friendlyarm/rtl8851bu
- biglinux/RTL8851bu
- themrleon/realtek-8851bu-driver
- morrownr/USB-WiFi 讨论区(AX900 芯片确认)
本文的补丁、日志数据均来自一台 Debian 13 + 内核 6.12.117 的真机实测。