Linux WiFi驱动开发实战：从cfg80211框架到ARM平台适配全攻略

搞WiFi驱动这件事，说难不难，说简单也真不简单。我最近在一块ARM板子上适配新的WiFi模块，把Linux WiFi设备驱动开发从框架学习到实际调通的完整流程又重新走了一遍。这中间涉及的东西特别杂，从cfg80211/mac80211框架的理解、设备树配置、驱动注册流程，到固件加载、数据收发路径、最终的性能调优，每一步都有不少容易踩的坑。这篇文章我就以自己的实际项目为主线，把整个开发过程、关键原理、代码框架和排查经验整理出来，给准备接触或者正在做WiFi驱动的朋友一个可以直接参考的路线图。

1. 先看明白Linux WiFi驱动框架的底子

1.1 从无线扩展到cfg80211/mac80211的演进

早期Linux内核里，WiFi驱动用的是一套叫无线扩展（Wireless Extensions，简称WE）的接口，也就是我们常说的iwconfig那套工具。它的设计思路是把无线网卡的各种操作抽象成一套ioctl命令，驱动只需要实现对应的处理函数就行。这套接口在802.11a/b/g时代还算够用，但到了802.11n之后，功能需求越来越复杂，比如多天线、多队列、更细粒度的功率控制、软件扫描等，WE那种"每个操作一个ioctl"的模式变得又臃肿又难维护。

所以内核后来引入了cfg80211作为新的无线配置管理层，配合mac80211这个软MAC框架一起工作。cfg80211负责对上跟用户态工具（如iw）交互，对下给驱动提供注册接口和操作集；mac80211则是一个半成品的MAC层实现，帮SoftMAC驱动处理了大量802.11协议逻辑，比如帧封装、管理帧处理、扫描流程等。

我自己的体会是，理解这层演进对后续开发帮助很大。如果你接手的是一个老平台，内核版本还在2.6.x，那很可能还是WE那一套；但如果做新项目，基本全部都是cfg80211/mac80211的新框架，差别非常大。

1.2 FullMAC驱动和SoftMAC驱动怎么选

硬件芯片厂商在设计WiFi方案时，会根据芯片内部固件的功能划分出两类驱动架构。

FullMAC的意思就是，MAC层的大部分功能都在芯片内部固件里完成了，比如关联、扫描、漫游、帧聚合这些都有固件处理，驱动程序相对简单，主要工作是传输数据包、把用户配置命令透传给固件。典型的FullMAC驱动有USB接口的网卡，例如MT7601U、RTL8188EU这类。

SoftMAC是指芯片只实现了物理层和部分基带功能，MAC层协议逻辑大部分要靠主机CPU跑mac80211来处理。这种方案芯片可以做得更简单、成本更低，但驱动要做的事情很多，不仅要处理好数据面，还要处理各种管理帧、控制帧，以及扫描、连接状态的同步。常见的SoftMAC芯片比如MT76x2系列、Atheros的ar9287，以及目前主流的MT7915、MT7921等。

选型的时候怎么判断？如果你的产品追求低成本、低功耗，主控CPU性能不充裕，优先考虑FullMAC芯片；如果你要做高吞吐、需要灵活的协议定制，SoftMAC更合适，但驱动开发和调试的复杂度明显更高。我自己做ARM平台产品时，大多数情况选FullMAC，因为适配周期短、问题少，能快速出活。

2. 开发环境准备与内核配置要点

2.1 内核版本与Kconfig配置

动手之前先把内核版本定下来。不同内核版本对cfg80211和mac80211的接口变化还挺大的，尤其是一些结构体成员和回调函数签名，内核ABI并不稳定。比如早期版本里ieee80211_ops的sw_scan_start/sw_scan_complete回调，跟新版相比参数类型都有调整。所以建议先确定目标内核版本，然后以该版本的源码为准去学习接口，不要随便拿网上老代码来编译。

内核Kconfig里需要勾选的选项，最核心的是：

CONFIG_CFG80211=y CONFIG_MAC80211=y CONFIG_WLAN=y CONFIG_WIRELESS=y

如果你的无线网卡是USB接口，还需要保证下面这些打开了：

CONFIG_USB=y CONFIG_USB_NET_DRIVERS=y CONFIG_USB_NET_AX8817X=y # 这行不一定需要，取决于网卡方案

具体驱动相关的选项，一般芯片厂商会提供一个Kconfig片段，直接放到drivers/net/wireless/下面，然后加进上一级的Kconfig和Makefile里。这块别手动乱加，尽量按厂商提供的路径走，避免编译时出现符号找不到的问题。

2.2 交叉编译工具链与目录结构

做嵌入式WiFi驱动，交叉编译是跑不掉的。工具链的选择最好跟你的buildroot或yocto环境保持一致，否则后面把驱动模块放到目标板上加载，会出现kernel module版本不匹配、 vermagic不一致的问题。

我常用的做法是把内核源码单独放一份，在源码目录下执行：

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- defconfig make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- menuconfig make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- modules -j8

需要把驱动编译成模块时，在menuconfig里选中对应驱动为M，然后单独编译模块：

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- M=drivers/net/wireless/my_wifi_driver modules

编译出来的.ko文件先不要急着拷到目标板，先检查一下module的vermagic：

modinfo my_wifi.ko

如果显示的vermagic跟你目标板内核的vermagic不一致，模块加载会直接报错，最常见的错误是"version magic 'xxx' should be 'yyy'"。这通常意味着你编译内核时的配置跟目标板不一样，需要把.config对齐。

2.3 根文件系统与固件放置

WiFi驱动几乎都依赖固件文件，芯片上电后需要把固件从文件系统加载到芯片内部的RAM里。固件的存放路径传统上都在/lib/firmware目录下。为了防止单个目录东西太多，内核支持子目录，比如rtlwifi/rtl8821cu.bin。

如果你用buildroot，加固件最简单的方式是把固件文件放到board目录下，然后在post-build脚本里拷贝到目标系统的/lib/firmware。别偷懒等到系统起来以后再手工丢，因为很多驱动在probe阶段就要请求固件，文件缺失会导致probe失败。

调试初期建议把文件系统做成NFS挂载，改固件、换驱动模块都方便，不用反复烧写整个根文件系统。

3. 核心数据结构与驱动注册全流程

3.1 两个核心对象：wiphy和ieee80211_hw

很多第一次做WiFi驱动的人会被cfg80211和mac80211的那一套数据结构绕晕，其实抓住两个核心对象就够了。

一个是cfg80211层面的wiphy，它代表一个物理无线设备。wiphy里包含了设备的频段能力（2.4G/5G）、支持的速率、接口类型（STA/AP/Ad-Hoc）、加密方式等。你可以把它理解成"这个无线设备对外暴露的能力清单"。用户态用iw看到的很多信息，本质上都是从wiphy里读出来的。

另一个是mac80211层面的ieee80211_hw，它是mac80211框架给SoftMAC驱动分配的一个硬件描述结构。对于SoftMAC驱动，ieee80211_hw是主对象，里面包含了硬件相关的参数、操作回调、私有数据区。不过对FullMAC驱动来说，实际上更常见的是直接用wiphy来注册，mac80211那层用得少一些。

这两个对象的关系，可以简单理解成：wiphy是给用户态看的"外皮"，ieee80211_hw是给内核协议栈用的"内脏"。如果你做SoftMAC驱动，两者都存在；做FullMAC驱动时，很多情况下只跟wiphy打交道。

3.2 操作集回调：驱动和协议栈的桥梁

先说cfg80211层面的操作集，叫cfg80211_ops。这个结构体里的回调函数非常多，挑几个核心的：

• add_virtual_intf：创建虚拟网络接口，比如创建monitor模式接口时就会调它
• del_virtual_intf：删除接口
• change_virtual_intf：切换接口模式（STA/AP/Monitor）
• add_key / del_key / set_default_key：密钥管理
• connect：STA模式下发起连接
• disconnect：断开连接
• scan：发起主动扫描

如果是mac80211框架的驱动，还需要实现ieee80211_ops：

• start：启动硬件
• stop：停止硬件
• config：处理信道、功率等配置
• configure_filter：配置硬件接收帧的过滤规则
• tx：发送数据帧
• add_interface / remove_interface：接口创建和删除

这些回调函数命名很直观，但真正写起来需要注意的是，很多回调会在原子上下文或者持锁的情况下被调用，所以不能在回调里做太耗时的操作，比如睡眠等待、大块内存申请。否则很容易出内核调度相关的问题，典型的比如"scheduling while atomic"。

3.3 一个最小驱动注册骨架

以FullMAC驱动的注册为例，最简单的流程是分配wiphy、设置属性、注册。代码骨架大概长这样：

#include <net/cfg80211.h> #include <linux/wireless.h> static struct cfg80211_ops my_cfg80211_ops = { .add_virtual_intf = my_add_virtual_intf, .del_virtual_intf = my_del_virtual_intf, .change_virtual_intf = my_change_virtual_intf, .scan = my_scan, .connect = my_connect, .disconnect = my_disconnect, }; static int my_wifi_probe(struct platform_device *pdev) { struct wiphy *wiphy; struct my_priv *priv; int ret; // 分配wiphy，第二个参数是私有数据区大小 wiphy = wiphy_new(&my_cfg80211_ops, sizeof(*priv)); if (!wiphy) return -ENOMEM; priv = wiphy_priv(wiphy); priv->pdev = pdev; platform_set_drvdata(pdev, priv); // 设置wiphy基本属性 wiphy->max_scan_ssids = 4; wiphy->max_scan_ie_len = 500; wiphy->interface_modes = BIT(NL80211_IFTYPE_STATION) | BIT(NL80211_IFTYPE_AP); wiphy->bands[NL80211_BAND_2GHZ] = &my_band_2ghz; // 注册wiphy ret = wiphy_register(wiphy); if (ret) { wiphy_free(wiphy); return ret; } return 0; } static int my_wifi_remove(struct platform_device *pdev) { struct my_priv *priv = platform_get_drvdata(pdev); wiphy_unregister(priv->wiphy); wiphy_free(priv->wiphy); return 0; } static const struct of_device_id my_wifi_of_match[] = { { .compatible = "vendor,my-wifi" }, { } }; static struct platform_driver my_wifi_driver = { .probe = my_wifi_probe, .remove = my_wifi_remove, .driver = { .name = "my_wifi", .of_match_table = my_wifi_of_match, }, }; module_platform_driver(my_wifi_driver); MODULE_LICENSE("GPL");

这里要特别说一下wiphy_new的第二个参数，它是私有数据区的大小。驱动里经常需要保存自己的状态，比如供电GPIO、中断号、当前工作的信道等，这些都可以放到私有数据区里，不需要额外再加成员变量。

3.4 注册顺序为什么不能乱

wiphy_register的调用时机非常关键。内核在通知用户态设备已就绪时，会从wiphy里读取能力信息并生成对应的网络接口。如果你在wiphy_register之前没有把bands、channels、interface_modes这些参数设置好，用户态看到的设备能力就不完整，后面用iw命令操作时会找不到对应功能。

我自己调试时就遇到过一个问题：网卡注册成功了，但用iw去扫描时提示"command failed: Operation not supported"。排查半天发现是wiphy->bands里的channel数组没有初始化完整，导致扫描用的频点信息缺失。所以注册前一定要把两个频段的信道表填全，包括center_freq、hw_value、max_power等字段。

另外，wiphy的注册顺序跟无线核心的netlink通知也有关系。如果在框架还没ready的时候就注册，可能出现用户态拿到不完整事件的情况，所以一般建议在probe函数的最后再调用wiphy_register。

4. 数据收发路径与关键回调实现

4.1 TX路径：从网络协议栈到硬件

理解Tx路径，是理解WiFi驱动最重要的一步。以SoftMAC驱动为例，内核网络协议栈要发送一个数据包时，会通过ndo_start_xmit进入驱动的发送入口，然后驱动调用mac80211提供的ieee80211_tx_dequeue取出一帧，完成硬件描述符填充、加校验、触发DMA等操作，最后写寄存器通知硬件发送。

很多人不理解为什么SoftMAC驱动里还要经过一层mac80211处理，而不是直接把skb写到硬件。原因是mac80211要做很多协议层面的工作，比如给数据帧加802.11头、做软件加密、管理队列、处理聚合等。对FullMAC驱动来说，这些都在固件里做完了，驱动只要把上层给的数据包转给固件即可。

TX路径中容易出问题的点有：

• DMA buffer一致性：如果硬件是DMA方式读取数据，要用dma_map_single做好映射，并在传输完成后用dma_unmap_single回收。
• skb生命周期管理：有些硬件要求驱动在发送完成后释放skb，有些则在提交时就把skb的所有权拿走。这个要看芯片手册，处理错了直接内存泄漏或者访问野指针。
• 队列停止和唤醒：在发送队列满的时候要调用netif_stop_queue停掉上层发送，有了缓冲空间再netif_wake_queue唤醒。这个节奏没控制好，会出现吞吐量突然掉零或者丢包率飙升。

4.2 RX路径：从硬件中断到协议栈

RX路径的难点不在把数据从硬件搬到内核，而在于处理802.11帧头的各种情况。

硬件收到数据包后，通常会通过DMA把数据写到驱动分配好的环形缓冲区，然后触发中断。驱动在中断处理函数里识别中断类型，如果是RX完成中断，就把对应缓冲区的skb交给mac80211，即调用ieee80211_rx_irqsafe或者ieee80211_rx。mac80211内部会完成帧格式转换、解密、解聚合等，最终变成普通网络包上送协议栈。

这里有个值得注意的细节：在中断上下文直接调用ieee80211_rx_irqsafe比ieee80211_rx更安全。原因在于ieee80211_rx对调用上下文有要求，而irqsafe版本会把处理推迟到工作队列里，避免在硬中断里做复杂操作。很多初学者在中断里调了ieee80211_rx，导致内核栈溢出或者调度异常。

另外，接收路径一定要处理错误帧。比如CRC错误、长度异常、未知的帧类型，这些帧如果不丢弃，轻则统计信息混乱，重则影响协议栈稳定性。硬件一般会用RX描述符里的状态位标示这些错误，驱动读取描述符后要判断并跳过。

4.3 扫描、连接和状态上报

WiFi驱动开发里，扫描是最容易出问题的流程之一。用户态发起的扫描请求，经过cfg80211层后进入驱动或者mac80211。对于FullMAC，固件自己会完成扫描并上报结果；对于SoftMAC，驱动需要自己管理扫描的过程。

扫描动作无论是谁发起，最终都要通过cfg80211_scan_done通知上层扫描完成。这个回调带一个参数是scan_info，里有个aborted字段，表示扫描是否被中断。如果你的驱动因为某个高优先级任务中止了扫描，一定要把aborted置为true，否则用户态会一直等不到扫描完成的事件，表现就是iw dev wlan0 scan卡住。

连接过程类似。STA模式下发起连接后，驱动要等待硬件上报关联成功或者失败，然后调用cfg80211_connect_result上报结果。连接成功后，内核会自动配置IP、路由等。很多调试问题出在"连上了但上不了网"，这种就要先确认驱动上报的BSSID、频段、是否关联成功这些信息是否正确。

5. 设备树配置与硬件资源的绑定

5.1 一个典型的WiFi设备树节点

现在的嵌入式Linux项目，WiFi芯片大多挂在新式总线上，比如SDIO、USB、PCIe，或者直接是平台设备挂在SoC内部总线上。对于平台设备，设备树节点的写法会直接影响驱动probe是否能被触发。

一个典型的设备树节点长这样：

&usdhc2 { status = "okay"; pinctrl-names = "default", "sleep"; pinctrl-0 = <&pinctrl_usdhc2_wifi>; pinctrl-1 = <&pinctrl_usdhc2_wifi_sleep>; non-removable; cap-power-off-card; keep-power-in-suspend; vmmc-supply = <&wlan_en_reg>; mmc-pwrseq = <&wifi_pwrseq>; }; &iomuxc { pinctrl_usdhc2_wifi: usdhc2wifi { fsl,pins = < MX8MP_IOMUXC_SD2_DATA0_USDHC2_DATA0 0x1f0 MX8MP_IOMUXC_SD2_DATA1_USDHC2_DATA1 0x1f0 MX8MP_IOMUXC_SD2_DATA2_USDHC2_DATA2 0x1f0 MX8MP_IOMUXC_SD2_DATA3_USDHC2_DATA3 0x1f0 MX8MP_IOMUXC_SD2_CMD_USDHC2_CMD 0x1f0 MX8MP_IOMUXC_SD2_CLK_USDHC2_CLK 0x3f0 >; }; };

如果是USB WiFi，设备树里通常只需要确认对应的USB控制器enable了，不需要单独为WiFi写节点，驱动会通过USB的VID/PID匹配。PCIe接口的WiFi也一样，在PCIe控制器节点下面配置好EP供电、复位、时钟，驱动通过PCIe枚举找到设备。

5.2 GPIO、复位和使能引脚的时序控制

WiFi模块除了数据传输总线，一般还有几个控制引脚，比如WLAN_EN（使能）、HOST_WAKE（唤醒）、复位脚等。这些引脚的上下电时序在芯片手册里都有严格定义。我碰到过的一个典型问题就是，板子上WiFi模块的使能脚在供电之后没有延时就被拉低，导致芯片一直处于复位状态，SDIO枚举时根本看不到设备。

推荐的做法是把这些引脚的控制交给regulator或者pwrseq设备树节点来管理，驱动里不要去直接操作GPIO。比如用mmc-pwrseq节点统一管理SDIO WiFi的上电顺序：

wifi_pwrseq: wifi-pwrseq { compatible = "mmc-pwrseq-simple"; reset-gpios = <&gpio1 3 GPIO_ACTIVE_LOW>; post-power-on-delay-ms = <80>; };

这样内核的mmc核心层会在上电时按顺序执行，避免驱动里自己操作GPIO产生时序冲突。

5.3 中断与唤醒配置

WiFi芯片的HOST_WAKE引脚一般会接到SoC的一个GPIO上，并配置为中断输入。这个中断用来告诉主机，硬件有事件需要处理，比如扫描完成、收到唤醒帧等。

在设备树中要正确指定中断号和触发方式：

wifi_wake: wifi-wake { compatible = "vendor,wifi-wake"; interrupt-parent = <&gpio1>; interrupts = <7 IRQ_TYPE_EDGE_FALLING>; };

如果用的是SDIO WiFi，很多SoC还支持在SDIO接口上直接产生中断，这种就不需要单独配HOST_WAKE脚。不过很多产品为了低功耗，还是会加一根HOST_WAKE线做唤醒专用。

唤醒功能的调试比较麻烦，经常出现"休眠后无法唤醒"的问题。排查思路一般是先看内核日志确认系统是否进入了suspend，再看WiFi芯片的电源是否被切断，以及HOST_WAKE中断在suspend期间是否被正确保留。很多SoC的GPIO在系统suspend时会丢失中断配置，需要在设备树或者驱动里单独处理irq_set_irq_wake。

6. 调试工具、固件问题与性能调优

6.1 调试三板斧：dmesg、iw、Tracepoint

WiFi驱动调试，我跟团队里的小兄弟说得最多的就是先把这三个东西用熟。

第一个是dmesg，驱动打印的所有日志都在这里。开发阶段不要省打印，在probe、remove、scan、connect、tx/rx这些关键路径上都要留日志。但打印也不能瞎打，尤其不能在数据热路径上printk，否则吞吐量直接崩。

第二个是iw，这是跟cfg80211交互的核心工具。常用命令：

iw dev wlan0 info # 查看接口信息 iw dev wlan0 scan # 扫描 iw dev wlan0 connect "SSID" # 连接 iw dev wlan0 set channel 6 # 手动设置信道 iw phy phy0 info # 查看物理设备能力 iw event # 监听内核无线事件

iw event特别有用，可以实时看到内核上报了哪些无线事件，比如scan结果、连接成功、断开原因等，能快速定位问题出在内核还是用户态。

第三个是tracepoint，特别是mac80211层的trace事件：

trace-cmd record -e mac80211:* -e cfg80211:* sleep 5 trace-cmd report

可以看到每个帧的收发流程、在哪个函数停留了多长时间，对分析驱动卡死、吞吐量低这类问题非常管用。

6.2 固件加载失败的类型化排查

固件加载失败，是在实际项目里遇到最多的问题之一，而且报错方式多种多样。

最常见的一种是驱动请求固件时，文件不存在。这种情况下dmesg一般会打印类似"Direct firmware load for xxx.bin failed with status -2"。解决办法很简单，把固件放到/lib/firmware下，注意文件名要跟驱动请求的一致，包括目录路径。

第二种是固件文件存在，但版本不匹配。有些芯片固件和驱动代码有严格的版本对应关系，比如新驱动要求新固件。这种报错通常是"firmware version mismatch"或者固件校验失败。处理方法是去芯片厂商官网或者驱动源码仓库找配套的固件版本。

第三种是固件加载过程中硬件没有ready，导致加载超时。这种往往是上电时序问题，芯片还没来得及完成初始化，驱动就开始load固件了。解决方式是检查WLAN_EN引脚的时序，适当增加延时，或者让驱动在probe之前等待硬件准备好。

我自己的经验是，如果固件加载失败，先别急着怀疑驱动代码，按"文件是否存在 -> 文件名是否一致 -> 版本是否匹配 -> 硬件是否上电 -> 时序是否OK"这个顺序去排查，效率最高。

6.3 吞吐量上不去的常见瓶颈

WiFi驱动调通了，接下来就是性能测试。如果吞吐量一直上不去，别一上来就怀疑驱动代码，逐层排查才是正解。

首先是链路本身的信号质量。用iw dev wlan0 link看一下信号强度rssi和速率rate，如果信号本身就差，别指望驱动能救回来。这种时候优先调天线位置、AP信道。

其次是协议层面的聚合情况。高吞吐依赖帧聚合，如果固件或者驱动没有正确开启A-MPDU/RX BA session，吞吐量会一直卡在很低的水平。可以用perf或者ethtool统计看下重传率，重传率高了基本可以怀疑聚合没生效。

再次是中断和DMA的瓶颈。WiFi数据量大时，中断频率很高，如果SoC的中断处理开销太大，吞吐量就会被拖累。这时候可以考虑启用NAPI、合并中断、或者使用多队列。

我踩过的一个比较典型的坑是，SDIO WiFi吞吐量低，排查到最后发现是SDIO时钟频率配得太低，只有25MHz。把设备树里SDIO控制器的max-frequency改到100MHz之后，吞吐量几乎翻倍。所以做WiFi性能调优时，底层总线的速率一定要先确认。

7. 实测中遇到的坑与避坑心得

7.1 高频问题速查表

这张表是我这两个月调驱动时反复翻看的整理结果，大部分问题其实都不是什么高深的技术难题，而是基础配置错误。所以遇到问题时，先从最基础的开始排查，能少走很多弯路。

7.2 我的几点实操心得

最后分享几个我自己调试WiFi驱动时的体会。

第一，日志分级一定要做好。建议自己封装一个带level的打印宏，比如wifi_info、wifi_dbg、wifi_err，这样开发阶段开full debug，量产固件里关掉debug，不用到处改代码。

第二，调试阶段先别用最高性能模式跑。我习惯先把芯片固定在2.4GHz、20MHz带宽，用固定信道和固定速率去验证基本功能。等基本收发包都正常了，再去开5GHz、80MHz带宽、自动速率这些高级特性。不然一出问题变量太多，根本定位不到根因。

第三，跟芯片原厂FAE沟通的时候，一定要带上完整的信息：内核版本、驱动版本、固件版本、设备树配置、完整dmesg、复现步骤。缺一个信息就得多来回一轮，浪费的是自己的时间。

第四，做一个稳定的测试基准。我的习惯是同一个AP、同一个位置、同一台设备，每次都先跑iperf3测试打底，确保环境一致，再改驱动代码做对比，否则吞吐量的变化根本没参考意义。

WiFi驱动开发这东西，边界非常多，硬件、协议、内核、用户态工具都可能出问题。但只要框架理清了，流程走顺了，调试方法对了，大部分问题都是能逐步收敛的。希望这篇分享能给正在搞Linux WiFi设备驱动的朋友一些实际帮助。

最后再补一个小技巧：调试过程中如果发现WiFi模块反复probe失败，可以试试在设备树里把相关电源域的regulator改成always-on先跑通功能，等确认软件逻辑没问题后，再做精细的电源管理。这样能把电源问题和驱动问题分开排查，效率会高很多。