企业官网建设流程全解析

把一块 WiFi 模块从“系统能认出来”调到“能扫到、能连上、能跑满速率、休眠后还能醒来”，中间隔着的东西比多数人想的多。Linux WiFi设备驱动开发这件事，本质上是在三个世界之间搭桥：上面是 cfg80211/mac80211 这套内核无线子系统，下面是 PCIe、USB、SDIO 这些总线上的射频芯片，中间还夹着一个经常“不听话”的固件。我做过几轮从板级点亮到量产验证的完整流程，踩过的坑包括固件加载失败、32.768kHz 睡眠时钟缺失导致连上就掉、TX 功率表配错被 regulatory 打回、中断全压在 CPU0 上导致吞吐只有理论值的三分之一。

这篇东西写给三类人：刚接手一个 WiFi 模块、手上只有原理图和一颗裸芯片的嵌入式驱动工程师；想搞清楚iw敲下去之后内核里到底发生了什么的应用层同学；还有准备把 WiFi 做进产品、需要评估工作量和风险的项目负责人。我不会从“什么是网络设备”讲起，直接按我实际做项目的顺序拆：先划清驱动边界，再搭骨架，然后死磕收发路径、参数调优、调试排查，最后落到嵌入式裁剪和量产验证。所有参数和步骤都是我实际跑过的，能抄作业的地方我会直接给出来。

1. 先把边界划清楚：WiFi 驱动到底该干什么

很多人第一次看 WiFi 驱动代码，第一反应是“这也太短了吧”，几百行就注册完了；再看第二个反应是“怎么全是回调”。这个感受是对的，因为在 Linux 的无线栈里，驱动被刻意做“薄”了，大量协议逻辑被上收到内核公共层。

1.1 从用户态到天线的五层链路

一条wpa_supplicant发出的连接请求，往下走的路径大致是这样：

用户态wpa_supplicant/iw通过 generic netlink 发命令，落到内核的cfg80211层；cfg80211负责的是“与硬件无关的配置语义”——扫哪些频段、用哪个 BSSID、regulatory 域怎么限制功率、接口以什么模式存在。再往下是mac80211，如果是 SoftMAC 设备，这里会承担起管理帧的组装解析、扫描状态机、认证关联流程、块确认会话、聚合、电源管理这些事。再往下才是你的驱动，它只需要回答两个问题：内核让我发一帧，我怎么把这块内存交给硬件；硬件收到一帧，我怎么把它包装成skb交给上层。

再往下是总线层（PCIe/USB/SDIO）和芯片固件。固件干的是实时性要求最高、最贴近射频的活：信道切换时序、AGC、发射功率微调、低功耗状态机。芯片和固件之间的接口是各家私有寄存器，这层通常只对原厂开放，也正是驱动适配最“不通用”的地方。

理解这条链路的意义在于：遇到问题时要先判断该在哪一层查。扫不到 AP，可能是cfg80211的 regulatory 把信道屏蔽了；连上了但 ping 不通，可能是mac80211的密钥下发出错；能通但速率只有 6Mbps，那多半是速率控制或固件上报的速率信息有问题。查错的方向错了，能白熬一整晚。

1.2 FullMAC 和 SoftMAC 的分工差别

选型阶段第一件事是确认 IP 的架构类型，这决定了你的驱动工作量是“两周”还是“半年”。

我第一次做的时候吃了这个亏：拿了一颗 FullMAC 芯片，却按照 SoftMAC 的思路去写ieee80211_ops，写完发现根本没有管理帧收发路径可以挂钩，白白浪费了一周。判断方法很简单，看原厂给的参考驱动里有没有ieee80211_alloc_hw()，有就是 SoftMAC 路线，没有、只有wiphy_register()加一堆厂商私有命令，那就是 FullMAC。

1.3 为什么基本没人“从零写一个驱动”

现实一点讲，从零写一个能通过认证的 WiFi 驱动，工作量在 10 人年以上，而且射频校准那部分数据是你自己测不出来的——它需要原厂的校准仪器和产线治具。所以实际项目里的“驱动开发”，百分之九十是这四件事：

• 移植：把原厂基于某个内核版本（常见是 4.19 或 5.10）的驱动包，适配到你的 6.1/6.6 内核上，主要处理 API 变更（cfg80211的 op 签名、ieee80211_ops新增/删除的回调）。
• 板级适配：电源域、时钟、复位时序、SDIO 参数、设备树、GPIO 中断。
• 参数调优：TX 功率表、速率集、聚合窗口、队列深度、中断合并。
• 问题定位：掉线、吞吐不达标、休眠唤醒异常、与蓝牙共存互相干扰。

把这四件事想清楚，你的排期才不会写成一个笑话。下面我就按这个顺序往下讲。

注意：正式动手前，先向原厂索要三样东西——参考驱动包、固件二进制、校准数据写入工具。缺任何一样，项目都推不下去。尤其是校准数据，很多模组的 MAC/功率表烧在 OTP 里，出厂没烧的话，你拿到的板子发射功率是“未定义”状态。

2. 环境搭建与最小可加载骨架

环境这块看着琐碎，但它是最容易埋雷的地方。内核版本、编译器、固件目录、配置项，任何一处不对，表现出来都是“扫不到 AP”这种毫无指向性的现象。

2.1 内核版本对齐与配置项勾选

我建议不要一上来就冲到最新内核，先把原厂参考驱动能跑通的版本锁定，跑通之后再逐版本往上升。升级过程中最常见的三类 API 变化：

第一类是cfg80211_ops的签名变动。比如mgmt_frame_register这个回调在较新内核里已经删掉了，改成通过ieee80211_ops的mgmt_frame_register走；set_bitrate_mask的参数结构也调整过。

第二类是mac80211的ieee80211_ops新增强制回调。典型的是wake_tx_queue，5.0 之后引入的 TXQ 机制，如果你的驱动没实现这个回调，日志里会直接提示wake_tx_queue相关警告，且吞吐上不去。

第三类是skb相关辅助函数的更名，比如早期用skb_get_queue_mapping的写法在某些路径上被替换。这类改写是机械性的，但漏一处就编译不过。

配置项方面，必须确认打开的有：

# 无线子系统基础配置 CONFIG_CFG80211=y CONFIG_MAC80211=y CONFIG_CFG80211_CRDA_SUPPORT=y CONFIG_CFG80211_WEXT=y # 老工具兼容，按需 CONFIG_MAC80211_LEDS=y CONFIG_MAC80211_DEBUGFS=y # 调试阶段强烈建议打开 CONFIG_MAC80211_MESH=y # 不用 mesh 可关 CONFIG_WIRELESS_EXT=y

CONFIG_MAC80211_DEBUGFS一定要开，打开之后/sys/kernel/debug/ieee80211/phy0/下面会出现极其好用的统计目录，队列状态、聚合情况、每站点的速率信息都在里面。我第一次做的时候没开，靠打日志猜了两天，开了之后五分钟定位到问题。

还有一点，regulatory.db要放进/lib/firmware/。这个文件来自wireless-regdb包，缺了它内核会在启动日志里报failed to load regulatory.db，然后退回一个极其保守的默认域，5GHz 大部分信道直接不可用。这个报错在很多发行版上是“默认存在”的，容易被忽略。

2.2 三条总线的选型与代价

总线选型直接决定了板级适配的工作量和产品的极限吞吐。

嵌入式产品里 SDIO 是最常见的，因为它支持在系统休眠时把 WiFi 单独保持在低功耗监听状态，而且走线简单。代价是 SDIO 的时钟调优很烦：max-frequency、bus-width、cap-sdio-irq、keep-power-in-suspend这几个属性必须对着模组手册填，填错的表现是“枚举成功但一发包就 CRC 错误”。

设备树片段大致长这样：

&sdmmc1 { bus-width = <4>; max-frequency = <150000000>; cap-sdio-irq; disable-wp; keep-power-in-suspend; non-removable; mmc-pwrseq = <&sdio_pwrseq>; status = "okay"; wifi: wifi@1 { compatible = "vendor,chip-wifi"; reg = <1>; interrupt-parent = <&gpio3>; interrupts = <12 IRQ_TYPE_LEVEL_HIGH>; clocks = <&cru CLK_WIFI_32K>; clock-names = "32k"; vdd-supply = <&vcc_wifi>; }; };

那个 32k 时钟是新手最容易漏的。WiFi 芯片在低功耗状态下靠 32.768kHz 时钟维持时间基准，用来做 beacon 监听周期的对齐。这个时钟缺失或者频率不准，典型症状就是：连上 AP 一段时间后（几十秒到几分钟）掉线，重连又能用一会儿，日志里常见beacon loss或者时间戳相关告警。我见过不止一个项目卡在这个点上，最后查出来是 32k 时钟没在设备树里使能。

2.3 最小可加载模块的骨架代码

这一步的目标不是功能完整，而是“能insmod、能在dmesg里看到注册成功、iw dev能看到接口”。骨架是这样的：

#include <linux/module.h> #include <linux/pci.h> #include <net/mac80211.h> #include <net/cfg80211.h> struct my_wifi { struct ieee80211_hw *hw; struct pci_dev *pdev; void __iomem *mmio; struct ieee80211_vif *vif; /* 简化起见，实际用 vif 链表 */ }; static const struct ieee80211_ops my_ops = { .start = my_start, .stop = my_stop, .tx = my_tx, .add_interface = my_add_interface, .remove_interface = my_remove_interface, .config = my_config, .bss_info_changed = my_bss_info_changed, .configure_filter = my_configure_filter, .sta_add = my_sta_add, .sta_remove = my_sta_remove, .wake_tx_queue = my_wake_tx_queue, }; static int my_wifi_probe(struct pci_dev *pdev, const struct pci_device_id *id) { struct my_wifi *priv; struct ieee80211_hw *hw; int ret; hw = ieee80211_alloc_hw(sizeof(*priv), &my_ops); if (!hw) return -ENOMEM; priv = hw->priv; priv->hw = hw; priv->pdev = pdev; /* 关键：声明支持哪些硬件能力 */ hw->flags = IEEE80211_HW_SIGNAL_DBM | IEEE80211_HW_AMPDU_AGGREGATION | IEEE80211_HW_REPORTS_TX_ACK_STATUS; hw->queues = 4; hw->max_rates = 4; hw->max_rate_tries = 11; set_wiphy_dev(hw->wiphy, &pdev->dev); ret = ieee80211_register_hw(hw); if (ret) goto err_free; pci_set_drvdata(pdev, hw); dev_info(&pdev->dev, "wifi driver registered\n"); return 0; err_free: ieee80211_free_hw(hw); return ret; }

hw->flags和hw->queues这两处是“信任开关”。你在这里声明的能力，mac80211会无条件相信。声明了IEEE80211_HW_AMPDU_AGGREGATION但硬件其实不做聚合，上层会拼命发聚合帧，硬件解析不了就静默丢包，现象是“能连上、小包能通、大包几乎不通”，很难查。所以原则是：先声明最低能力跑通，再逐项打开并验证。

hw->queues = 4对应的是mac80211的四个 AC（voice、video、best effort、background）。如果你的硬件只有一个 TX 队列，就填 1，然后自己在驱动里按优先级映射，别硬撑四个。

2.4 模块编译与自动加载

调试阶段用 out-of-tree 模块最快，不用重编整个内核：

obj-m += my_wifi.o my_wifi-y := main.o tx.o rx.o debugfs.o KDIR ?= /lib/modules/$(shell uname -r)/build all: $(MAKE) -C $(KDIR) M=$(PWD) modules clean: $(MAKE) -C $(KDIR) M=$(PWD) clean

有个小技巧：把CONFIG_CFG80211=m和CONFIG_MAC80211=m也编成模块，这样改mac80211加调试打印时不用重编内核，重启次数能少一半。等你确定要改公共层代码了再改成=y。

实操心得：加载模块前先rmmod掉系统里可能自动加载的同芯片厂商驱动，比如brcmfmac、rtw88这类，否则会出现两个驱动抢同一颗芯片的情况，表现是设备能枚举但不产生网络接口。用lsmod | grep -i wifi先排查一遍。

3. 收发主路径：扫描、连接、发包、收包

骨架搭好之后，真正花时间的都在这一章。我按数据流方向拆，每一段都给出「驱动该做什么」和「容易错在哪」。

3.1 扫描流程与结果上报

扫描是用户态第一个会触发的功能，iw dev wlan0 scan一敲，链路就活了。

cfg80211收到NL80211_CMD_TRIGGER_SCAN后，走到mac80211，SoftMAC 设备上mac80211会自己组装 probe request 帧，然后调用驱动的tx回调把帧发出去。驱动要做的是：拿到skb，填好发送描述符，触发 DMA。回来的 probe response 由硬件收到，驱动在 RX 路径里识别出这是管理帧，用ieee80211_rx_irqsafe()交上去。mac80211解析后调用cfg80211_scan_rx之类的接口，把 BSS 信息缓存起来，等扫描周期结束再一次性上报给用户态。

如果你的硬件固件自己会做扫描（FullMAC 或带 offload 的 SoftMAC），流程变成：驱动下发扫描命令给固件，固件返回结果列表，驱动用cfg80211_scan_done配合cfg80211_inform_bss_frame_data上报。这里最容易错的是上报的 BSS 信息不完整：只填了 SSID 和 BSSID，没填信道和信号强度，结果iw scan输出里全是空值，用户态选网逻辑直接失效。信号强度这一项必须按 dBm 填，且要确认固件的单位是 dBm 还是半 dBm，差一倍的表现就是“明明在 AP 旁边，显示 -120dBm”。

还有一种坑：上报缓存的时间戳不对。cfg80211用时间戳做 BSS 老化，时间戳如果用了不单调的时钟，扫描结果会随机消失。用ktime_get_boottime()这类单调时钟，别用墙上时钟。

3.2 认证关联阶段的责任划分

SoftMAC 设备上，认证和关联帧都是mac80211生成的，驱动不需要碰。驱动在这个阶段真正要做的是响应bss_info_changed回调，把上层决定的配置写进硬件：

• BSS_CHANGED_BSSID：把目标 AP 的 MAC 写进硬件过滤表。
• BSS_CHANGED_BEACON_INT：beacon 周期，用于低功耗唤醒调度。
• BSS_CHANGED_ERP_CTS_PROT：是否开启 CTS 保护，老 AP 混合环境要用。
• BSS_CHANGED_QOS：QoS 使能状态。
• BSS_CHANGED_ASSOC：关联状态变化，这才算真正“连上”。

密钥下发走的是sta_add和set_key路径。这里有个隐藏的时序要求：set_key必须在sta_add之后调用，而且如果硬件需要密钥在关联完成前就写入（有的芯片要求这样），你得在sta_add里预先把密钥材料缓存起来。顺序反了的表现是“握手完成但收不到任何数据帧”，抓包能看到 AP 在发加密包，本地全丢。

另外一个新手常踩的坑是configure_filter没实现。mac80211通过这个回调告诉硬件“现在需要接收哪些类型的帧”，实现不到位的时候表现很有意思：能连上，但过一段时间就会因为收不到 beacon 而判定掉线。因为你的过滤器把 beacon 也挡掉了。

3.3 TX 路径：从 skb 到 DMA 描述符

发包是性能的关键路径，我把它拆成四个阶段。

阶段一：接收skb。mac80211调tx回调，传入的skb已经带了 802.11 头部和可能的加密头。驱动的control.hw_key字段指示是否已由软件加密完毕——如果硬件支持加密卸载，这里会是NULL，需要你把密钥索引写进描述符。

阶段二：映射 DMA。用dma_map_single()映射skb->data，拿到物理地址写进描述符。这里必须处理映射失败的情况，尤其是带 IOMMU 的平台上地址空间紧张时。映射失败要返回NETDEV_TX_OK并释放 skb（因为mac80211不像网卡驱动那样支持返回NETDEV_TX_BUSY重试，强行返回会导致内核警告）。

阶段三：写描述符、敲门铃。描述符环通常是环形缓冲区，需要一个生产索引和一个硬件消费索引。写完描述符后按芯片要求触发 DMA（写 MMIO 寄存器或按 SDIO 的块传输）。这一步之后不能再访问skb->data，因为 DMA 方向是到设备。

阶段四：回收。硬件发完产生 TX 完成中断，驱动在中断或 NAPI 里回收描述符，dma_unmap_single()，ieee80211_tx_status()通知上层结果。这里如果不及时回收，TX 环会满，触发NETDEV_TX_BUSY或直接丢包。

我实测过的一个典型问题：TX 环深度设成 32，在 iperf3 打流时频繁出现tx ring full，吞吐停在 180Mbps。把环深加到 256 并开启 TX 完成中断合并（每 8 个描述符或 1ms 触发一次），吞吐直接到 520Mbps。环深度和中断合并是吞吐调优里性价比最高的两个参数。

3.4 RX 路径与 NAPI 收包

RX 侧的性能瓶颈通常在中断风暴上。10G 级别的 WiFi 芯片在满速率下每秒十几万帧，如果每帧一次中断，CPU 直接被打满。

标准做法是 NAPI：

static irqreturn_t my_wifi_isr(int irq, void *data) { struct my_wifi *priv = data; /* 关中断，调度 NAPI */ my_disable_rx_irq(priv); napi_schedule(&priv->napi); return IRQ_HANDLED; } static int my_wifi_poll(struct napi_struct *napi, int budget) { struct my_wifi *priv = container_of(napi, struct my_wifi, napi); int done = 0; while (done < budget) { struct sk_buff *skb = my_rx_dequeue(priv); if (!skb) break; ieee80211_rx_irqsafe(priv->hw, skb); done++; } if (done < budget) { napi_complete(napi); my_enable_rx_irq(priv); } return done; }

budget的建议值在 64 到 256 之间。太小了中断切换开销大，太大了单核独占时间过长影响其他队列。我一般从 128 起步，用mpstat看软中断占比来微调。

还有一点容易忽略：ieee80211_rx_irqsafe()之后skb的所有权就交给上层了，不能再动。有人在后面加了个dev_kfree_skb()想“防止泄漏”，结果就是随机崩溃。

3.5 低功耗与 WoWLAN

产品形态一旦是电池供电，这一章的每个字都要抠。

驱动侧主要实现三个回调：suspend、resume、set_wakeup。进入suspend时，你要判断是否允许 WiFi 保持唤醒：wiphy->wowlan->flags里声明支持的模式，比如WIPHY_WOWLAN_MAGIC_PKT（收到魔数包唤醒）、WIPHY_WOWLAN_DISCONNECT（掉线唤醒）。

实现上的关键点是不要把整个芯片断电，而是让它进入监听状态。这时候 32k 时钟的精度直接决定监听周期能不能对齐 AP 的 beacon。同时要注意 SDIO 的keep-power-in-suspend属性必须打开，否则 MMC 控制器在系统休眠时会把 SDIO 总线断掉，芯片直接失联。

我遇到过的一个很隐蔽的问题：唤醒后第一次收包总是丢。原因是resume回调里重新使能了中断，但 RX 环里还残留着休眠期间硬件写入的描述符，驱动没有先清理就直接用，导致索引错位。修法是在resume里强制复位 RX 环再重新使能。

4. 参数调优：功率、速率、队列与 CPU

同样的硬件和驱动，参数调得好和调不好，实测吞吐能差三倍。这一章讲我验证过有效的几个方向。

4.1 TX 功率校准与 regulatory 的相互制约

TX 功率是驱动里最“玄学”的部分，因为它不是一个寄存器说了算。完整的功率控制链是：

校准数据（EEPROM/OTP）→ 每信道每速率的目标功率 → 温度补偿 → regulatory 上限裁剪 → 最终写入芯片功率表

校准数据是原厂产线用仪器测出来的，包含几项关键指标：IQ 不平衡、DC 偏置、PA 偏置点、每信道的输出功率对照表。这里解释一下为什么需要 IQ 校准：射频前端把基带信号调制到载波上时，I 路和 Q 路两个支路不可能完全对称，幅度和相位都有微小误差，在星座图上表现为整体旋转和拉伸，解调误码率上升。校准就是把这两个误差量测出来，补偿到数字预失真里。

温度补偿同样重要。PA 的增益随温度漂移，室温下调好的功率在 60 度机箱里可能掉 3dB。有的芯片内置温度传感器自动补偿，有的需要驱动定期读温度并查表调整。

regulatory 是最后一道闸。即使你的校准表写着 20dBm，如果当前设定的是某个把该信道限制在 14dBm 的域，最终发射功率就是 14dBm。这里有个很实际的问题：用户态可以通过iw reg set改变域，如果你的驱动没有正确实现set_regulatory相关的限制回调，就可能出现超限发射。合规不是可选项，产品认证时这是硬指标。所以我建议在驱动里对目标功率做一次最终钳位，取 min(校准值, 域上限)，不要完全信任上层传下来的值。

排查功率问题的实用手段：iw phy phy0 info能看到当前域和每信道的允许功率；iw dev wlan0 station dump能看到实际协商的速率和信号强度；要验证实际发射功率得上频谱仪，但在开发阶段可以用“不同距离下的吞吐衰减曲线”做相对判断。

4.2 速率控制与聚合窗口

速率控制是mac80211做的（minstrel_ht或minstrel_ht的变体），驱动要做的是准确上报发送结果。这个因果关系很多人搞反：他们以为速率是驱动挑的，其实驱动只是告诉上层“这一帧发成功了没有、重传了几次、对方有没有回 BA”。

所以如果你发现速率死活上不去，第一件事是检查tx_status上报是否准确。常见错误是只上报前 N 个描述符的状态，后面批量完成的不报，导致minstrel认为有大量丢包，自动降速到 6Mbps。hw->flags里打开IEEE80211_HW_REPORTS_TX_ACK_STATUS就要求你每帧都如实上报。

聚合窗口是另一回事。A-MPDU 的窗口大小由hw->max_tx_aggregation_subframes声明，实际协商值通过 ADDBA 帧和 AP 谈。嵌入式场景里我一般先设成 32，验证稳定后再升到 64。窗口开太大而硬件缓冲区不够，会出现“发了但收不到 BA”的情况，mac80211会误判为丢包触发重传，反而降速。

提示：速率控制的调试信息在/sys/kernel/debug/ieee80211/phy0/netdev:wlan0/stations/<mac>/rc_stats。这个文件直接给出每个速率档位的成功率和当前选择，是排查速率问题最直接的入口，比抓包快得多。

4.3 中断合并与 CPU 亲和性

多核平台上一个很反直觉的现象：CPU 核心越多，WiFi 吞吐反而可能越低。原因是所有 WiFi 中断都落在同一个核上，那个核的软中断占比冲到 100%，其他核在闲着。

三个手段解决：

第一是设置中断亲和性。找到 WiFi 的中断号，把 RX 和 TX 完成中断分别绑到不同核：

# 查看中断号 grep -i wifi /proc/interrupts # 假设是 128 号，绑到 CPU2 echo 4 > /proc/irq/128/smp_affinity # 关闭 irqbalance 避免它把设置改回去 systemctl stop irqbalance

4这个值是位掩码，0b100表示 CPU2。别直接填<cpu号>，这是最常见的错误。

第二是启用 RPS/RFS，让内核在协议栈层面把skb分散到多个核处理。对 WiFi 来说 RPS 的效果比有线下更明显，因为mac80211解析和加解密都是 CPU 密集的。

第三是驱动里实现中断合并。不要每帧一次中断，攒一批再报。代价是延迟增加，实时性要求高的场景要谨慎，一般设成 1ms 或 16 帧，取先到的。

我在一块四核 ARM 板上实测过这几项的组合效果：

610Mbps 距离 2x2 80MHz 的理论 866Mbps 还有距离，但已经接近这块板子 SDIO 总线的实际上限了。这个结论很重要：调优之前先算清楚瓶颈在哪一层，SDIO 走在 100MHz 4bit 模式下理论也就 200MB/s，扣掉协议开销和读写方向的切换，600Mbps 左右的网络吞吐就是天花板。

4.4 队列深度与内存对齐

最后两个细节，影响不大但很容易做错。

队列深度不要盲目加大。环深 512 确实能扛住突发，但每个描述符对应的 DMA 缓冲都要常驻内存，512 × 1600 字节说多不多，在内存只有 256MB 的嵌入式设备上就很可观了。我一般按“最大聚合长度 × 4”来定，A-MPDU 64 帧的情况下用 256 描述符就很够。

内存对齐方面，DMA 缓冲一定要按 cache line 对齐。Cache line 通常是 64 字节，如果缓冲跨界，DMA 写入时会把相邻数据冲掉，表现为“偶发的、无法复现的数据校验错”。用dma_alloc_coherent()分配控制结构，用netdev_alloc_skb()配合skb_reserve()做对齐，别自己 malloc。

5. 调试手段与问题排查实录

这一章是我个人觉得最有价值的部分，因为 WiFi 驱动的问题，80% 的现象都长得很像（连不上、掉线、慢），但原因可能完全不同。

5.1 工具链的正确定位

不要一上来就抓包。抓包信息量大但解读成本高，先用下面这套定位到层，再决定要不要抓。

ftrace这块值得多说一句。mac80211内置了大量 tracepoint，打开方式：

cd /sys/kernel/debug/tracing echo 0 > tracing_on echo 1 > events/mac80211/enable echo 1 > events/cfg80211/enable echo 1 > tracing_on # 复现问题 cat trace | tail -100

这个手段的威力在于能看到状态机的完整流转。比如“连不上”这个现象，trace里可能显示auth发出了、auth响应收到了、assoc发出了、然后超时——说明问题在关联阶段，大概率是加密配置不匹配。这种粒度是抓包给不了的。

5.2 常见故障速查表

下面这张表是我这些年攒下来的，按现象索引：

有两条我想展开讲，因为太经典了。

第一条是“PCI 设备显示 unclaimed”。这个提示来自lspci -k，意思是设备存在但没有驱动绑定。很多人第一反应是驱动有问题，其实九成情况是 vendor/device ID 表没写对，或者驱动是按模块编的但没insmod。还有一个隐蔽情况：驱动已经在跑，但用的是另一颗芯片的 ID。解决方法很直接，lspci -nn看实际的 ID，跟pci_device_id表逐位对一遍。如果驱动是内置的，还要确认CONFIG_XXX=y真的生效了，/boot/config-*里搜一下最稳。

第二条是“速率卡在最低档”。这个我卡了整整三天。iw station dump显示速率 6Mbps，重传率极高。抓包看空口，发现 AP 其实发得挺快，是本地在不停地降速。最后查出来是我的 TX 完成中断处理里，为了省事只处理了描述符环的前 8 个，后面的等下一次中断一起处理——但硬件不会产生“下一次中断”了。结果就是大量帧的完成状态丢失，minstrel认为丢包率 50% 以上，直接降到最低速率保命。改成每个完成中断处理完整批后就正常了。

5.3 固件加载失败的三层排查法

固件问题极其常见，我总结了一个三层排查顺序。

第一层，文件是否在位。request_firmware()失败会返回-ENOENT，日志里是Direct firmware load for xxx.bin failed with error -2。去/lib/firmware/下ls一下，注意大小写和子目录。有的驱动会尝试多个名字（比如带版本号的、不带版本号的），日志里只显示最后一个，实际前面还试过几个。

第二层，文件是否完整。传输过程中被截断的固件文件长度对不上，加载时会返回-EILSEQ或校验失败。对比一下 md5 最保险。

第三层，芯片是否准备好接收固件。这是最容易被忽略的一层。固件加载前，芯片需要完成上电、复位释放、时钟稳定这一串动作。如果复位脉冲宽度不够、或者电源还没稳你就开始写寄存器，芯片根本不在监听状态，写入的数据全部丢弃，表现为“固件文件没问题但加载超时”。

这里有个实用技巧：在probe里读一下芯片的 ID 寄存器。这个动作同时验证了三件事——电源正常、时钟正常、总线通信正常。ID 读出来是0xFFFFFFFF或0x00000000，别往下走了，先解决板级供电和时序。我后来把这个检查写成了标准流程，能省掉一大半无效排查。

5.4 板级问题：天线、匹配、干扰

驱动调好了不代表产品能跑好，天线这块的问题往往在整机装配之后才暴露。

最典型的是天线匹配。模组的射频输出口和天线之间有一段走线，走线的特征阻抗要控在 50 欧姆，长度尽量短。这段没做好，表现是发射功率正常但接收灵敏度差，也就是“能连上但距离比设计值短很多”。验证方法：在屏蔽房里用标准 AP，看相同距离下的 RSSI。我的经验是，如果实测 RSSI 比理论值低 6dB 以上，天线匹配大概率有问题。

第二是干扰。整机上 WiFi 和蓝牙共用一套射频前端的情况极常见，二者都在 2.4GHz，必须做时分复用。这就是共存（coex）机制，一般通过 BT/WiFi 之间的硬件信号线（比如 coexistence 接口的BT_ACTIVE、WL_ACTIVE三线协议）或者固件内部仲裁来协调。驱动侧要做的是把共存参数（比如 WiFi 在蓝牙高优先级业务时让出多少时隙）通过私有命令下发给固件。

实测影响有多大？我做过一组对比：不做共存协调时，蓝牙音频播放 + WiFi 打流同时进行，WiFi 吞吐从 480Mbps 掉到 90Mbps，音频还有断续；加上共存参数（WiFi 让步窗口设为 30% 时隙）之后，WiFi 稳定在 320Mbps，音频完全流畅。这个取舍要在产品需求层面决定，驱动只是执行者。

第三是功耗噪声。开关电源的纹波如果落在射频敏感频段，会抬高接收底噪。表现是近距离没问题、远距离丢包严重，且不同信道表现差异明显。这个用示波器看电源纹波配合扫频就能定位。解决办法通常是加 LC 滤波或者改电源芯片的开关频率，属于硬件改动，所以最好在驱动开发完成之前就把射频底噪测一遍，别等到最后才发现要改板。

6. 嵌入式落地：裁剪、共存与量产验证

最后一章讲从“开发板上能跑”到“产品能出厂”之间的事。这段路在很多项目里被严重低估，我见过太多项目在开发阶段一切正常，量产时才发现镜像体积超了、或者一致性测试通不过。

6.1 内核裁剪与驱动形态选择

嵌入式产品的 flash 空间往往很紧张，内核镜像加驱动加固件，很容易就超了预算。裁剪的思路是分清“必须”和“可以没有”。

必须保留的：cfg80211、mac80211、你的驱动、regulatory.db。这几个是功能底线。

可以裁掉的：CONFIG_CFG80211_DEBUGFS（量产固件关闭，能省下不少代码）、CONFIG_MAC80211_MESH、CONFIG_CFG80211_WEXT（如果不用老工具）、各种不相关的无线驱动（只留你用的那一个）。这一步的收益比想象中大，满配的mac80211加上可选特性有 800KB 左右，精简后能到 300KB 出头。

驱动编译成模块还是内置，取决于启动时序。如果你的 WiFi 需要在根文件系统挂载前就工作（比如用网络挂载 rootfs 的场景），必须内置。如果是常规启动，编成模块更灵活，还能通过modprobe参数传配置。我个人的偏好是：开发阶段模块，量产转内置，避免模块加载顺序带来的偶发问题。

固件文件也可以考虑压进内核。CONFIG_EXTRA_FIRMWARE允许把固件二进制直接编译进内核镜像，好处是不依赖根文件系统，代价是内核变大。固件一般几百 KB，如果空间允许，这是个省心的选择。

6.2 与蓝牙共存的参数下发

上一章提到共存，这里讲具体下发什么。

共存的本质是给两个射频使用者分配时间。参数一般有这几类：

• 优先级仲裁：蓝牙的语音链路（SCO）优先级最高，WiFi 的 beacon 接收次之，然后是数据。这个优先级表通常在固件里，驱动可以覆盖。
• 时隙分配：WiFi 在每个共存周期里能占用多少时间。这个值设太小 WiFi 慢，设太大蓝牙音频断。
• 保护间隔：两个系统切换时留的空白时间，防止互相干扰。太小会有邻道泄漏，太大浪费时隙。

下发方式各家不同，SoftMAC 芯片一般通过vendor_cmd类的私有 netlink 命令，或者直接写寄存器。我见过的实现里，比较规范的做法是在驱动里注册一组 debugfs 节点，把参数暴露出来，这样产线调试和现场排查都能动态改，不用重编固件。

调试共生效果的手段比较直观：用蓝牙音箱持续播放音频，同时跑 iperf3，用mpstat看中断分布，用音频的主观听感判断有没有断续。两者同时达标才算通过。

注意：共存参数的最优值跟天线隔离度、外壳材质、整机结构强相关。开发板上调好的值换到整机上大概率要重调，所以把参数做成可配置的，别硬编码在驱动里。这是我踩过的一个实实在在的坑，重编固件刷机花了整整两天。

6.3 量产阶段的射频一致性验证

量产阶段要验证的是“每一台设备都符合设计”。射频这块的验证项比功能测试严格得多，通常这几项是必测的：

RSSI 准确性这一项经常被忽略，但它直接影响漫游决策。如果设备报告的 RSSI 系统性偏高，终端会一直粘在弱信号的 AP 上不切换，用户感知就是“网速慢”。测试方法很简单：用标准信号源在固定功率下发信号，读设备的 RSSI 上报值，比对偏差。偏差大就在驱动侧加一个校准偏移量。

校准数据的一致性同样要检查。产线烧录的校准数据如果写错地址或校验和不对，芯片会用一个默认的保守功率表工作，表现是“能用但距离明显比样机短”。所以产线上要有一个环节读回校准数据做校验，这一步千万别省。

最后一个实际经验：量产镜像里保留一套最小诊断能力。每个设备出厂时不需要debugfs，但至少要能通过/proc或 sysfs 读到固件版本、校准数据 CRC、当前域这几个值。现场出问题时，能远程读到这几个数，排查效率完全不一样。我见过因为没有版本信息，把同型号但不同批次固件的两台设备混在一起排查，绕了很大的弯。

最后分享一个小技巧收尾。在驱动的probe里加一个“自检开关”，通过模块参数控制，打开时会依次做几件事：读芯片 ID、读固件版本、回环测试一小段数据、打印校准数据校验和。这个自检在开发阶段能快速排除板级问题，在量产阶段能让产线工人两秒钟判断一块板子是不是硬件不良。我把它加进去之后，产线返回的“疑似硬件问题”里有三分之二其实是驱动配置错误，一下子省了大量返修工时。