企业官网建设流程全解析

搞嵌入式Linux这几年，要说哪个外设驱动最让人头大，WiFi绝对排前三。它不是单纯的一个设备驱动，而是整个协议栈、射频硬件、用户态网络管理三者绑在一起的组合拳。很多人拿到一块板子，明明照着芯片手册把WiFi模块焊上去了，内核里也加了配置，结果开机后ifconfig -a下面光秃秃的，连个wlan0都看不到，这时候才体会到什么叫真正的懵。

这篇文章打算把Linux WiFi设备驱动开发这条路上的关键节点全部过一遍：从内核无线子系统的架构分工，到具体的数据结构、回调函数、设备树配置，再到驱动加载、AP关联、吞吐测试和问题排查的完整流程。适合正在啃WiFi驱动的嵌入式工程师，也想帮刚入门的同学少走点弯路。内容会偏实操，不会只讲概念，文中所有命令和配置我都实测过，你可以直接拿来参考。

1. 先看懂Linux无线子系统这盘棋

1.1 为什么WiFi驱动让新手劝退

WiFi驱动难，难在它不是“一个驱动”，而是一条完整的链路。写一个GPIO驱动，你只需要操作寄存器、处理中断，最多再对接一个gpiolib。写一个串口驱动，也就是tty层以下的事。但WiFi驱动要面对的是：硬件本身有非常复杂的射频前端和基带处理，固件要负责大量协议帧的处理，驱动要在内核无线子系统里注册自己的能力，用户态还得有wpa_supplicant、DHCP客户端配合才能把网络“用起来”。

这条链路上任何一环出问题，表象都是“WiFi不能用”，但根因可能差着十万八千里。比如扫描不到AP，可能是天线没接、可能是regulatory domain限制了信道、可能是驱动没把扫描请求发给固件，甚至可能是wpa_supplicant的配置文件写错了。这种“共同表象、多类根因”的问题，是WiFi驱动调试最耗人心智的地方。

另外，WiFi芯片厂商的文档开放程度普遍不高。很多芯片的数据手册只讲硬件接口，协议层完全是黑盒，驱动怎么写、固件怎么交互，全靠厂商SDK里那堆不太美观的代码去反推。所以新手一头扎进去，经常是被代码带着跑，而不是带着问题去读代码，越看越糊涂。

1.2 mac80211、cfg80211、nl80211的分工关系

Linux无线子系统在内核里主要分三层：nl80211、cfg80211和mac80211，驱动在这三层下面干活。用一个不太严谨但很好懂的类比：cfg80211是政策制定者，负责对用户态开放API、维护无线配置规则；mac80211是项目经理，负责处理802.11协议里那些通用逻辑，比如管理帧、帧聚合、速率选择；驱动是执行层，真正去操作硬件寄存器、提交DMA描述符；硬件和固件是底层的员工，干最脏最累的活。

用户态工具（比如iw、wpa_supplicant）通过netlink和nl80211通信，nl80211是cfg80211提供给用户态的接口封装。cfg80211做完策略检查后，把请求转给mac80211或直接转给驱动。这里有个关键分支：如果芯片是FullMAC类型，固件把MAC层的活全干了，驱动只需要实现cfg80211_ops，直接跟cfg80211对接；如果芯片是SoftMAC类型，驱动的上层是mac80211，驱动通过ieee80211_ops结构体向mac80211注册自己的硬件能力，MAC层协议逻辑由mac80211用软件实现。

mac80211这一层特别重要，它把大量协议处理（比如管理帧的解析、帧重传、速率自适应）放在通用代码里，驱动不用重复造轮子。但也正因为这一层是软件实现的，它对驱动的回调要求很严格，你在ieee80211_ops里漏实现一个关键回调，表现就是某个功能莫名其妙不可用，而且内核不会给你任何提示。

1.3 FullMAC还是SoftMAC：先选好路线再动手

在动手写代码之前，先搞清楚你的芯片属于哪一类，这会决定你整个驱动的开发模式和难度。

FullMAC驱动开发起来快，很多USB WiFi网卡都是这种，固件把一切处理好了，驱动只要做做配置、收发数据就行。但一旦遇到协议行为异常，你没法在驱动层定位问题，只能怀疑固件，而固件是闭源的，基本没得查。

SoftMAC虽然开发工作量大，但可控性好。管理帧、控制帧都能在主机侧看到，出问题可以用抓包工具直接看无线帧，定位到具体是哪个环节出了问题。主线内核里大量的WiFi驱动（比如rtw89、mt76、iwlwifi）都是SoftMAC路线，代码结构上也更统一。如果你是在做一个需要长期维护、深度定制的嵌入式产品，我建议优先选SoftMAC的芯片，哪怕前期多花点时间，后面调试和功能扩展都会舒服很多。

2. 开发环境搭建与方案选型

2.1 内核、交叉工具链和根文件系统的版本搭配

很多人一上来就装最新的内核源码，结果交叉编译工具链版本不对，编译到一半报一堆莫名其妙的错误。WiFi驱动开发和普通内核模块开发一样，版本匹配是第一道门槛。

我的建议是：内核源码优先选长期支持版本（LTS），比如5.15、6.1、6.6这些。这里有个很现实的原因：新一代WiFi芯片的驱动支持往往只回推到较新的LTS，老内核想要驱动新芯片，要么自己移植厂商SDK，要么背一堆补丁，非常痛苦。交叉工具链用内核文档里推荐的GCC版本范围，太老或太新的GCC都可能跟内核源码的某些语法不兼容。根文件系统方面，至少要确保iw、wpa_supplicant、ip这几个工具存在，很多精简版busybox为了省空间把这些去掉了，结果驱动加载成功也scan不出AP，还以为是驱动的问题。

另外，运行时环境里/lib/firmware目录必须有，而且要和内核配置里的CONFIG_EXTRA_FIRMWARE_DIR对应。WiFi芯片的固件动辄几百KB，一般放在根文件系统的/lib/firmware下，驱动的request_firmware接口会从这里读取固件文件。常见的问题是固件文件名对不上，比如驱动要rtw89/rtw8852b_fw.bin，你放了个rtw8852b_fw.bin，它照样加载失败，但dmesg给的提示可能非常隐晦。

2.2 内核配置：从menuconfig选中WiFi驱动需要什么

WiFi驱动不是只开一个驱动选项就能跑起来的，它的前置依赖不少。以SoftMAC路径为例，至少需要打开这些配置项：

CONFIG_CFG80211=y CONFIG_MAC80211=y CONFIG_WLAN=y CONFIG_WLAN_VENDOR_REALTEK=y CONFIG_RTW89=m

如果是其他厂商芯片，把CONFIG_WLAN_VENDOR_*换成对应的厂商选项就行。这里有个容易被忽略的点：CONFIG_CFG80211和CONFIG_MAC80211一旦被编译成模块，驱动模块加载时就需要依赖它们，如果根文件系统里没有对应的.ko文件，modprobe会报依赖缺失。所以嵌入式场景下我一般建议把这两个选项直接编译进内核（=y），省去模块依赖的麻烦。

另外，WiFi驱动通常依赖CONFIG_CRC32、CONFIG_FW_LOADER、CONFIG_WIRELESS_EXT等。CONFIG_FW_LOADER尤其关键，不打开的话request_firmware直接失效，固化在驱动里的加载逻辑就没法工作。如果你是SDIO接口的模块，还要确认CONFIG_MMC、CONFIG_MMC_SDHCI这些SDIO控制器相关的选项已经打开，总线枚举都过不了的话，后面全白搭。

2.3 设备树里那些看似不起眼的属性

嵌入式平台（尤其是ARM、RISC-V）上，WiFi模块一般通过SDIO或USB接口连接主控，设备树配置是避不开的一环。以SDIO接口的WiFi模块为例，设备树节点一般长这样：

&sdhci1 { status = "okay"; mmc-pwrseq = <&wifi_pwrseq>; wifi@1 { compatible = "realtek,rtl8852bs"; reg = <1>; interrupt-parent = <&gpio0>; interrupts = <28 IRQ_TYPE_LEVEL_LOW>; reset-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>; sdio-max-frequency = <150000000>; }; };

这个节点里有几个属性特别容易踩坑。compatible必须和驱动里of_match_table里的字符串完全一致，差一个字符都不行，而且内核的device table匹配是大小写敏感的。reg = <1>表示SDIO function编号，WiFi模块通常是function 1，有的模块是function 0，如果你发现驱动probe根本没被调用，先查这个。

interrupts触发类型要跟芯片手册对上，有的芯片要求电平触发，有的要求边沿触发，设错了驱动虽然能加载，但可能一直收不到中断，表现就是能扫描到AP但关联后没数据。reset-gpios和power引脚的控制时序也经常出问题，模块需要先上电、再拉高reset、再等待一段时间，驱动里通常会在probe流程中操作，但设备树里如果漏掉了电源控制节点，模块可能根本没被唤起。这类问题调试起来最折磨人，因为硬件上看起来一切正常，就是你dmesg里看不到任何设备枚举信息。

2.4 厂商SDK和内核主线驱动怎么选

这是每个做WiFi驱动的工程师都会面临的抉择。厂商SDK的优势是即拿即用，Realtek、Broadcom这些厂商给的驱动包，解压后make就能出.ko，FAQ也多。但劣势同样明显：SDK代码几乎不遵守内核编码规范，大量平台相关的#ifdef和magic number，很难看懂；而且SDK驱动一般不跟随内核API演进，你换一个内核小版本，可能编译就过不去了。

我的建议是：能走主线驱动就走主线，除非你的芯片实在太老或者太偏门，主线确实没有支持。主线驱动有大量开发者维护和review，代码质量有保障，同时跟随内核演进，生命周期长。比如Realtek的rtw88/rtw89驱动、MediaTek的mt76驱动、Intel的iwlwifi驱动，都已经进入主线，虽然初期可能有一些功能缺失，但基本的使用场景都能覆盖。如果你是做产品而不是搞研究，主线驱动能让你少维护一个定时炸弹。

3. 核心数据结构和注册逻辑一次讲透

3.1 从ieee80211_hw到wiphy：驱动和mac80211的握手

SoftMAC驱动最关键的两个数据结构是struct ieee80211_hw和struct wiphy。ieee80211_hw代表一个MAC层硬件实例，wiphy是cfg80211向用户态暴露的“无线物理设备”抽象，每个物理WiFi设备对应一个wiphy。它们的关系是：驱动用ieee80211_alloc_hw分配ieee80211_hw，hw->wiphy指向内部的wiphy结构，用户态通过iw list看到的“物理设备信息”就是这个wiphy的能力描述。

注册流程的骨架是：

static int rtw89_register_hw(struct rtw89_dev *rtwdev) { struct ieee80211_hw *hw = rtwdev->hw; // 设置硬件支持的能力标志 hw->flags |= IEEE80211_HW_SIGNAL_DBM | IEEE80211_HW_AMPDU_AGGREGATION; hw->wiphy->interface_modes = BIT(NL80211_IFTYPE_STATION) | BIT(NL80211_IFTYPE_AP); hw->wiphy->bands[NL80211_BAND_2GHZ] = &rtw89_band_2ghz; hw->wiphy->bands[NL80211_BAND_5GHZ] = &rtw89_band_5ghz; hw->wiphy->max_scan_ssids = 10; return ieee80211_register_hw(hw); }

这段代码里最需要关注的是bands数组。如果你没把2.4G或5G频段的ieee80211_supported_band结构体填好，iw list里就会缺失对应的频段信息，扫描时也扫不到对应频段的AP。很多新入门的人在这里栽过跟头：驱动明明加载成功了，iw dev wlan0 scan就是扫不到5G的AP，最后发现是band里channels数组没填完整，或者n_channels计数不对。

另外，hw->flags的配置要跟你的硬件能力匹配。比如你的芯片支持信号强度上报，就设IEEE80211_HW_SIGNAL_DBM；不支持，就不要设，否则用户态拿到的信号强度是假数据，会导致Roaming逻辑混乱。

3.2 绕不开的ieee80211_ops回调

ieee80211_ops是SoftMAC驱动的核心，mac80211通过它来调用驱动做事。下面是几个关键回调的说明：

tx回调是最忙的，它接收mac80211发来的skb，驱动要把它挂到DMA描述符上，告诉DMA从哪个地址搬运数据。驱动程序写到这里时，记住一个原则：tx回调里尽量做轻量化处理，把耗时的DMA映射和描述符提交操作放到合适的上下文中，不要在原子上下文里做可能导致睡眠的操作。

set_key对于大多数消费级芯片是可以不实现的，因为固件会处理密钥相关工作。但如果你的芯片需要主机侧配合做加密，那么这个回调就必须认真实现，否则连不上WPA2/WPA3网络。判断依据很简单：扫描、关联都正常，但一输入密码就是连不上，大概率是set_key没处理对。

3.3 注册时序：中断、DMA、固件加载的先后次序

一个SoftMAC驱动的probe流程基本遵循这样的顺序：

1. 探测总线接口（SDIO/PCIe/USB），获取设备基本信息
2. 分配ieee80211_hw和私有数据结构
3. 初始化硬件：上电、复位、加载固件
4. 注册中断处理函数
5. 配置DMA相关资源
6. 填充wiphy能力字段
7. 调用ieee80211_register_hw完成注册

这个顺序里，有一个非常常见的错误：让固件加载和DMA初始化放在中断注册之前。你可能会想，中断都没开，不会有人打扰，多安全。但问题是，有些固件在加载完成后会主动发出一个中断事件，如果中断还没注册，这个事件就丢了，驱动和固件就会处于一种鸡同鸭讲的状态。

另一个常见的坑是固件加载的时机。request_firmware函数是可能睡眠的，所以不能在原子上下文里调用。有些新手把它放在中断处理函数里去加载，结果内核直接报BUG: scheduling while atomic，场面极其尴尬。正确做法是在probe线程上下文里加载固件，加载完成后再做后续的硬件初始化。

3.4 电源管理和唤醒：断连问题的隐藏来源

功耗管理缺陷是WiFi驱动上线后最容易暴露的问题。典型症状是：设备待机一段时间后，WiFi断开且再也连不上，必须重启模块才能恢复。这种问题排查起来非常耗时，因为你平时测试时，设备一直处于active状态，根本触发不了它。

根因通常是驱动没有正确实现suspend/resume回调，或者set_wakeup配置不对，导致系统进入低功耗状态后，WiFi模块的供电被切断，但驱动并不知道，等系统唤醒后，模块已经失联了。规范的驱动应该在suspend时把固件状态保存好，resume时重新初始化硬件。如果你的硬件平台有独立的WiFi电源域，还应该在设备树里把电源和唤醒引脚配置正确。

这里给个调试思路：遇到“待机后断连”的问题，先别急着改驱动代码，用powercfg或者cat /sys/power/state手动让系统进入suspend，再从唤醒后的dmesg里看驱动日志，确认模块是否重新初始化过。如果日志里根本没有resume相关的打印，说明驱动压根没有实现这个路径。另外，USB接口的WiFi网卡特别容易受autosuspend影响，很多“用着用着就掉线”的问题，都是USB autosuspend在捣乱，可以先通过echo -1 > /sys/bus/usb/devices/.../power/autosuspend_delay_ms来排查。

4. 实操：把一块WiFi 6模块在嵌入式板子上跑起来

4.1 硬件连接确认：不只是把线接上

这次实验我用了一块SDIO接口的WiFi 6模块（Realtek RTL8852BS方案，类似笔记本上常见的RTL8852BE的嵌入式版本），主控是瑞芯微的一颗应用处理器，内核版本6.1。板子本身不大，模块通过SDIO接口挂载，另外还有几根控制线：复位脚、电源脚、中断脚。

硬件上最容易出错的地方有三处：

第一，SDIO的数据线不能太长，布线阻抗和长度匹配都有讲究，如果PCB设计不当时钟频率上不去，表现就是驱动加载正常，但传输吞吐很低或者偶发超时。第二，中断脚的电气特性必须和主控GPIO的配置匹配，很多模块的中断脚是开漏输出，需要外部上拉，主控侧也要配置成带上拉的输入模式。第三，天线接口必须接好，WiFi模块如果天线没接，信号强度会低到-80dBm以下，虽然理论上还能工作，但实际体验就是“能扫到AP但连接不上”。这个坑真的很多人踩过，我调试的时候习惯第一步就用iw看RSSI，如果低于-70dBm，优先检查天线连接，而不是去翻驱动代码。

4.2 设备树和内核配置的最终形态

结合前面讲过的要点，我最终在板子设备树里添加了这样的节点：

/ { wifi_pwrseq: wifi-pwrseq { compatible = "mmc-pwrseq-simple"; reset-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>; post-power-on-delay-ms = <50>; power-off-delay-us = <100>; }; }; &sdhci1 { status = "okay"; no-1-8-v; mmc-pwrseq = <&wifi_pwrseq>; #address-cells = <1>; #size-cells = <0>; wifi@1 { compatible = "realtek,rtl8852bs"; reg = <1>; interrupt-parent = <&gpio0>; interrupts = <28 IRQ_TYPE_LEVEL_LOW>; sdio-max-frequency = <150000000>; }; };

这里需要特别说明两件事。第一，mmc-pwrseq节点是内核标准机制，用来控制SDIO设备的电源时序，启动时会先拉高reset-gpios对应的引脚，实现模块的复位释放。如果没有这个节点，模块可能在SDIO控制器初始化之前就已经上电了，但复位时序不对，导致设备无法枚举。第二，sdio-max-frequency不是越高越好，有些模块在高频率下不稳定，我会先从50MHz起步，确认稳定后再逐步提高。150MHz是这颗模块的标称上限，但我实测下来100MHz下最稳，后面就一直用这个值。

内核配置方面，除了前面列的那些CONFIG，还需要确认：

CONFIG_RTW89=y CONFIG_RTW89_8852B=y CONFIG_MMC=y CONFIG_MMC_SDHCI=y CONFIG_MMC_SDHCI_PLTFM=y CONFIG_FW_LOADER=y

RTW89是Realtek新的mac80211驱动框架，支持8852系列芯片。如果你用的是其他厂商芯片，就去CONFIG_WLAN_VENDOR_*下面找对应的厂商驱动选项。固件文件从linux-firmware仓库拿对应版本，放到根文件系统的/lib/firmware/rtw89/目录下。

4.3 编译、烧录、加载驱动的完整流程

我把驱动编译进内核而不是编成模块，原因很简单：嵌入式根文件系统里模块加载的依赖管理是个麻烦事，cfg80211、mac80211先加载还是驱动先加载，顺序错了就会报Unknown symbol。编进内核就没这个烦恼。

编译的时候，有几个小坑值得提醒。第一，make menuconfig选完配置之后，一定确认.config里CONFIG_RTW89相关的行是正确的，有时候配置界面里改了，但保存的时候覆盖了之前的配置，导致白忙一场。第二，编译新内核之前，最好把旧的内核模块清理干净，make ARCH=arm64 mrproper是个不错的选择，不然你可能一直在用上一版编译器编译出来的旧模块。第三，烧录之前对比一下内核System.map里的版本字符串和根文件系统/lib/modules下的目录是否匹配，很多“模块加载失败但不知道原因”的情况，其实就是版本不匹配。

烧录完后首次启动，先用dmesg | grep -i rtw89看驱动初始化日志。正常的日志应该包含固件加载成功、硬件初始化完成、ieee80211_register_hw调用成功这些信息。如果什么都没有，先检查平台设备有没有probe到，用ls /sys/bus/sdio/devices/确认SDIO function枚举是否正常。如果这里也是空的，那问题在SDIO控制器层，跟WiFi驱动本身没关系，回到设备树检查sdhci1节点是否使能。

4.4 用iw系列工具验证驱动是否“活”了

驱动加载成功的标志是出现wlan0网络接口。接着用iw命令一步步验证：

# 查看物理设备能力 iw list # 查看网络接口 iw dev # 查看链路状态 ip link show wlan0 # 启动接口 ip link set wlan0 up # 扫描周边AP，观察是否能看到目标AP iw dev wlan0 scan | grep -E "SSID|signal|freq|RSN"

iw list的输出要重点看Band 1和Band 2这两节，确认2.4G和5G频段都列出了，并且HT/VHT/HE能力标志都打开了。如果扫不到5G频段，回cfg80211的regulatory设置里找原因。iw dev能看到接口类型是Station，后面如果有需要，可以用iw dev wlan0 interface add wlan1 type __ap命令临时创建一个AP接口来测试多接口能力。

扫描这一步是最直接的“冒烟测试”。如果iw scan一直没有结果，回dmesg看有没有cfg80211相关的错误提示。我遇到过一种情况：扫描请求发出去了，但内核返回Operation not supported，原因是驱动没有实现hw_scan回调，而mac80211又没有正确回退到软件扫描，这种情况要么升级驱动版本，要么检查ieee80211_ops里是否实现了需要的回调。

4.5 关联AP、获取IP、测吞吐量

驱动工作正常之后，接下去就是把网络真正“用起来”。这里用wpa_supplicant关联一个WPA2的AP，配置文件/etc/wpa_supplicant.conf：

ctrl_interface=/var/run/wpa_supplicant network={ ssid="MyAP" psk="12345678" key_mgmt=WPA-PSK }

启动wpa_supplicant：

wpa_supplicant -B -D nl80211 -i wlan0 -c /etc/wpa_supplicant.conf # 等待几秒后，查看是否成功关联 iw dev wlan0 link

iw dev wlan0 link如果输出Connected to xx:xx:xx:xx:xx:xx，说明关联成功。这时候再用DHCP获取IP：

udhcpc -i wlan0 # 或者 dhclient wlan0

拿到IP之后，用iperf3测一下TCP/UDP吞吐量。我的这块板子在2.4G频段、20MHz带宽下能跑到约70Mbps，5G频段、80MHz带宽下跑到约500Mbps，这个水平对SDIO接口的WiFi 6模块来说已经算正常。如果吞吐量明显偏低，先确认信号强度，再用iw dev wlan0 station dump查看当前连接速率、MCS索引、RX/TX重试率等参数，这些数据能帮你判断是速率协商问题还是射频环境问题。

5. 高频问题排查和log分析实录

5.1 驱动加载失败：从“找不到固件”说起

驱动加载失败的报错形态一般分两种：modprobe时报Unknown symbol，或者内核日志里有明确的错误信息。前者几乎都是依赖模块没加载或者版本不匹配，用modprobe --dump-modversions比对符号即可；后者最常见的是固件加载失败，日志类似：

rtw89_8852bs mmc1:0001:1: firmware failed to load

这个报错背后通常有三种可能：固件文件不存在、文件名不对、路径不对。排查顺序建议是：

# 1. 确认固件文件存在 ls -l /lib/firmware/rtw89/ # 2. 确认文件名和驱动代码里定义的名称一致 strings /lib/modules/$(uname -r)/kernel/drivers/net/wireless/realtek/rtw89/rtw89_8852b.ko | grep rtw89 # 3. 确认文件系统挂载正常 mount | grep -E "rootfs|mmcblk"

还有一类比较隐蔽：request_firmware请求时，文件系统还没挂载到/lib/firmware。如果你的根文件系统是initramfs方式，但固件文件放在了主rootfs上，开机早期驱动加载时就会因为找不到固件失败。解决办法是把固件文件同时放进initramfs，或者把WiFi驱动改成模块，等系统起来后再手动加载。

5.2 扫描不到AP：射频和regulatory的锅

扫描不到AP，优先用排除法。第一步查硬件，看信号强度——不过既然扫描列表是空的，你连RSSI都看不到，所以要先查天线连接和模块供电。如果硬件确认没问题，再查驱动和regulatory。

regulatory domain（无线法规区域）是个很隐蔽的问题。内核里cfg80211默认启用了一个world regulatory domain，它会限制可用的信道范围。如果你的板子工作在5G频段，而默认的world domain只允许少数几个信道，正好你的AP用了被限制的信道，那扫描结果就是空的，或者能看到AP但无法关联。解决方法是用iw reg set CN把区域设置成中国，或者在内核配置里把CONFIG_CFG80211_INTERNAL_REGDB打开，并在设备树或驱动里指定默认的regulatory域。

驱动侧还有一个经常出问题的地方：扫描请求的SSID过滤。如果你在ieee80211_ops里实现了hw_scan，但实现得不够完整，比如没有正确处理ieee80211_scan_completed的调用时机，就会导致扫描结果始终为空。排查方法是打开mac80211的调试选项，echo 0xffff > /sys/module/mac80211/parameters/debug，把扫描相关的调试日志全打出来，看mac80211是否把扫描结果正确更新到了内部BSS列表。

5.3 能扫描、连不上：wpa_supplicant与密钥管理的坑

能扫描到AP，却连不上，分两种情况：始终在4-way handshake阶段失败，或者关联后立即断开。

4-way handshake失败，先怀疑wpa_supplicant的配置。key_mgmt、pairwise、group这些参数必须和AP的实际配置匹配。比如AP是WPA2-PSK+AES，你配置文件里写的是proto=WPA，那肯定握手失败。用调试模式启动wpa_supplicant能看到非常详细的握手过程：

wpa_supplicant -D nl80211 -i wlan0 -c /etc/wpa_supplicant.conf -dd

日志里重点关注WPA: 4-Way Handshake相关的行，它会告诉你失败在哪个步骤。如果握手阶段正常，但关联后立刻断开，常见原因有两个：一是AP开启了802.11r快速漫游，而驱动不支持；二是驱动在set_key回调里没有正确配置密钥索引，导致数据面加密失败。第二种情况在SoftMAC驱动里尤其常见，因为mac80211会把ieee80211_key_conf结构体传给驱动，你要根据keyidx正确映射到底层硬件密钥表，映射错了就解密不了数据，AP端看到的是大量解密失败的帧，自然会把客户端踢掉。

5.4 连上就断、吞吐极低：电源管理和聚合问题的排查

“连上就断”在驱动开发里真的能让一个人怀疑人生。我的排查经验是：先排除省电模式的干扰。在STA模式下，打开省电功能后，驱动要正确处理PS-Poll或U-APSD机制，如果固件和驱动的配合有问题，AP发给你的缓存帧收不到，TCP连接就会超时断开。先用这个命令临时关闭省电：

iw dev wlan0 set power_save off

如果关闭省电后问题消失，说明就是省电路径有bug。顺着mac80211的电源管理回调排查，重点看conf_tx是否正确设置了QoS队列的唤醒参数。

吞吐量低的问题，除了信号强度，大概率出在帧聚合。查看iw dev wlan0 station dump里的rx_aggregated和tx_aggregated字段，如果一直为0，说明聚合没有生效。在mac80211里需要驱动实现ampdu_action回调，并在ieee80211_hw里正确设置IEEE80211_HW_AMPDU_AGGREGATION。还有一个容易忽略的点：聚合缓冲区大小。struct ieee80211_sta里的ht_cap和vht_cap字段描述了station支持的聚合能力，驱动必须根据这些字段合理设置硬件描述符里的buffer size，设小了吞吐上不去，设大了硬件内存不够又可能崩。

5.5 按分层思路抓log

WiFi问题排查，千万不要一上来就盯着驱动代码看。我的做法是分层定位：先分“用户态配置”、“内核无线子系统”、“驱动硬件交互”、“射频环境”四层，逐层确认。

抓log具体操作上，建议在复现问题前先开好三个通道：dmesg -w实时看内核日志，wpa_supplicant -dd记录用户态无线管理过程，必要时再用tcpdump -i wlan0 -w wifi.pcap抓数据面报文。三层log对照着看，基本能把问题定位到具体模块。还有一种情况，连API层面都是正常的，但就是上网异常——比如你连的是一个需要浏览器门户认证的公共WiFi，这时候ping不通外网不代表WiFi连接有问题，先把网关注册、DNS解析、HTTP重定向这几个环节过一遍，别傻乎乎地去抓驱动log。

我个人在实际操作中的体会是，WiFi驱动调试最核心的一课，就是学会分层。驱动层只是整个无线链路里的一环，你把驱动翻个底朝天之前，先用工具把用户态、内核态、硬件态分开验证，会省下一大半时间。再分享一个小技巧：调试开始时，把iw event挂在后台实时监听无线事件，很多看似玄学的断连问题，在事件流里都有明确的上下文。做WiFi驱动快十个年头了，踩过的坑比写过的代码还多，但每次解决完一个诡异问题，回头看基本都逃不出这个分层框架。希望这篇文章能帮你少走几个弯路，尤其是那些我当年反复折腾到凌晨的坑，你直接绕开就好。