企业官网建设流程全解析

搞Linux WiFi驱动的这两年，我被问得最多的一类问题是：板子上的无线模组明明是好的，系统跑起来之后连个 wlan0 都看不到，日志里只有一行冷冰冰的报错。Linux WiFi设备驱动开发这件事，说穿了就是在内核网络子系统和一颗具体芯片之间搭桥——桥没搭好，上层再怎么配 iw、wpa_supplicant 都是白费力气。它解决的是一颗无线芯片从"上电被识别"到"能正常收发数据帧"的全过程，中间要过总线枚举、固件下载、mac80211 注册、信道与速率表协商这几道关。这篇文章适合三类人看：一是刚接手嵌入式无线项目的驱动工程师，二是想把随身WiFi、迷你主机上的无线网卡跑通甚至做裁剪的折腾党，三是面试前想把 Linux 设备驱动那一套串起来的开发者。下面我按自己实际做项目的顺序，把这条链路从架构到代码、从设备树到调试，一层一层拆开讲，中间会穿插大量踩过的坑。文中涉及的芯片型号和参数都以常见公开资料为准，具体项目请以你手上的数据手册为准。

1. 先搞明白Linux WiFi驱动的整体分层

很多人一上来就问"驱动怎么写"，其实更该先问"这段代码在内核里站在哪一层"。Linux 的无线子系统经过十几年演进，已经形成了一套相当固定的分层结构，你写的代码只是其中薄薄的一层，理解位置比会敲代码重要得多。

1.1 从硬件到应用的五层结构

把整条链路自上而下拆开，大概是这么五层。最上面是应用层，也就是iw、wpa_supplicant、hostapd这些工具，它们通过 netlink 和内核通信，用户态几乎不感知底层是哪家芯片。往下是cfg80211，它是内核里负责无线配置的统一接口层，管的是扫描请求、认证关联、信道设置、监管域这些"管理面"的事情，同时它也是 netlink 消息的收发窗口。再往下是mac80211，这一层是软 MAC 框架，负责 802.11 的帧结构、聚合、重传、速率控制、节能这些"数据面+控制面"逻辑，是绝大多数现代无线驱动都会挂靠的框架。再往下就是你要写的驱动本体，也就是通常说的 low-level driver 或 hw driver，它只干两件事：把 mac80211 交代的操作翻译成寄存器读写，把芯片上报的中断和数据搬进内核。最底下是总线与硬件，PCIe、USB、SDIO 三条路都通向同一颗无线 SoC。

这个分层最大的价值是职责隔离。管理面的事情你不用管，cfg80211已经替你处理了；协议栈的复杂度你基本不用碰，mac80211兜住了。你要专注的只有寄存器级操作和 DMA 数据搬运。我第一次做驱动时想"顺手把扫描逻辑也写进去"，结果发现完全是重复造轮子，而且和框架的行为对不上，最后还是老老实实退回 mac80211 的 ops 回调。

1.2 为什么mac80211加cfg80211是绕不开的核心

有人会问，我直接写一个字符设备或者网络设备不行吗？从技术上说可以，早期确实有 FullMAC 和 SoftMAC 之争，也有驱动自己实现整套协议栈的。但今天再这么做，代价高到不划算。原因有三条：一是上游兼容性，你自建协议栈意味着所有无线工具链、所有发行版的网络管理器都得为你适配；二是功能覆盖，mac80211 里成熟的速率控制算法、A-MPDU 聚合、块确认、省电模式，自己实现一遍至少要几个人年；三是维护成本，内核每合并一个大版本，无线框架都会有调整，挂在框架上你只需要跟着改回调，自己写就得跟着全套改。

所以现实中的选择非常清晰：如果你的芯片带完整的 MAC 硬件（FullMAC），驱动就注册到cfg80211，实现cfg80211_ops；如果芯片只做部分 MAC 或者不带 MAC（SoftMAC），驱动就注册到mac80211，实现ieee80211_ops。市面上大量 USB 网卡走的是前者，而多数 PCIe 和高性能 SDIO 模组走的是后者。判断标准其实就一条：看芯片手册里 MAC 层功能是在硬件里做还是需要软件参与。

1.3 三条总线路径怎么选

总线选型直接决定了驱动的骨架写法，也决定了后面调试的难易程度。我把三条路的核心差异整理成表，方便对照。

PCIe 的优势是寄存器空间直接映射，出问题时可以lspci看配置空间、devmem看寄存器，甚至用逻辑分析仪抓 TLP，排查路径最短。USB 的优势是即插即用、供电简单，但 URB 的生命周期管理很容易出 bug，一旦提交/回调的时序没对齐就表现为"用一会儿断流"。SDIO 介于两者之间，难点通常在 SD 控制器本身的时序和供电，很多"WiFi 时好时坏"最后查出来是 SD 时钟分频或者电源纹波的问题，跟驱动代码一点关系都没有。

提示：总线选型不要只看芯片性能参数，还要看你的板子能给什么接口、团队熟悉哪条路径。我见过为了追求吞吐硬上 PCIe，结果板子没有 PCIe 控制器、外加桥片又增加成本，最后退回 SDIO 反而更稳的案例。

2. 开发环境与内核源码的准备工作

环境这块看起来是体力活，但配错一次能浪费两三天。我的习惯是先固定内核版本，再固定工具链，最后才动代码，顺序反了就会出现"改了半天发现是编译器行为不一致"的尴尬。

2.1 内核版本选择与关键配置项

第一个决定是用厂商 BSP 内核还是主线内核。厂商内核的好处是驱动可能已经写好，坏处是版本老、补丁多、后期难以升级。主线内核的好处是框架新、社区支持好，坏处是可能没有你芯片的驱动，要自己移植。我的经验是：如果芯片是主流方案，优先看主线是否已有驱动，有就直接用主线；如果芯片很新或者很冷门，先用厂商 BSP 把功能跑通，再逐步往主线靠。

配置上，无线相关的几个选项必须打开，否则后面会莫名其妙找不到符号：

# 核心无线框架 CONFIG_CFG80211=y CONFIG_MAC80211=y # 速率控制算法，至少留一个 CONFIG_MAC80211_RC_MINSTREL=y CONFIG_MAC80211_RC_MINSTREL_HT=y # 加密套件，按需裁剪 CONFIG_CFG80211_CRDA_SUPPORT=y CONFIG_MAC80211_MESH=n # 不用 mesh 就关掉 # 调试相关，开发阶段建议开 CONFIG_CFG80211_DEBUGFS=y CONFIG_MAC80211_DEBUGFS=y CONFIG_DYNAMIC_DEBUG=y CONFIG_DEBUG_FS=y

注意CONFIG_CFG80211和CONFIG_MAC80211可以编成模块，也可以编进内核。嵌入式量产固件通常编进内核，减少启动时的依赖；开发阶段建议编成模块，改一次代码只要insmod，不用整机重启，效率差好几倍。

2.2 交叉编译与模块编译骨架

自己写的驱动一般先用外部模块方式编译，验证通过再考虑进内核树。最简的Makefile长这样：

obj-m += mywifi.o mywifi-objs := main.o hw.o txrx.o KDIR ?= /lib/modules/$(shell uname -r)/build PWD := $(shell pwd) all: $(MAKE) -C $(KDIR) M=$(PWD) modules clean: $(MAKE) -C $(KDIR) M=$(PWD) clean

交叉编译时把KDIR指向你目标平台内核源码目录，并显式传ARCH和CROSS_COMPILE：

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KDIR=../linux-6.6 modules

这里有个容易忽略的点：内核源码必须是已经配置并编译过的，至少执行过一次make modules_prepare，否则会报找不到Module.symvers或者autoconf.h。我第一次搭环境就卡在这，折腾了半天才发现是源码树没 prepare。

2.3 固件加载机制与存放位置

现在的无线芯片基本都要下固件才能工作。内核提供了request_firmware()这组接口，驱动在 probe 阶段调用，把固件从用户态的文件系统读进来，再通过总线写到芯片的 SRAM 里。固件默认查找路径是/lib/firmware/，也可以编译时通过CONFIG_EXTRA_FIRMWARE把固件直接嵌进内核镜像，省掉文件系统依赖。

static int load_fw(struct my_dev *dev) { int ret; const struct firmware *fw; ret = request_firmware(&fw, "mywifi/rtl_xxx.bin", dev->dev); if (ret) { dev_err(dev->dev, "firmware load failed: %d\n", ret); return ret; } ret = download_fw_to_chip(dev, fw->data, fw->size); release_firmware(fw); return ret; }

注意：固件版本和驱动版本经常要成对匹配。我遇到过升级驱动后没换固件，结果芯片能起来但收包全是错的，日志里一点报错都没有，最后靠对比校验和才发现。量产时把固件和驱动版本号绑定记录，能省掉很多售后排查。

3. 设备树配置与板级适配

对 PCIe 和 USB 来说，设备树通常不用你操心，总线的枚举机制会自动发现设备。但 SDIO 模组、以及带独立电源和复位的模组，就必须靠设备树把板级信息传进来。这一节能省下大量"为什么探不到设备"的排查时间。

3.1 SDIO模组的设备树节点写法

一个典型的 SDIO WiFi 节点，需要描述清楚插在哪个 SD 控制器上、用哪个中断引脚、供电怎么来：

&mmc1 { status = "okay"; bus-width = <4>; non-removable; cap-power-off-card; keep-power-in-suspend; vmmc-supply = <&vcc_wifi>; vqmmc-supply = <&vcc_io>; max-frequency = <50000000>; #address-cells = <1>; #size-cells = <0>; wifi@1 { compatible = "vendor,wifi-module"; reg = <1>; interrupt-parent = <&gpio4>; interrupts = <12 IRQ_TYPE_LEVEL_HIGH>; interrupt-names = "host-wake"; device-wake-gpios = <&gpio4 13 GPIO_ACTIVE_HIGH>; reset-gpios = <&gpio4 14 GPIO_ACTIVE_LOW>; }; };

几个属性的作用值得展开说。non-removable告诉内核这张卡焊死在板子上，不走热插拔流程，能省掉一堆探测重试。cap-power-off-card允许在挂起时断电省功耗，但前提是你的模组支持重新初始化，否则唤醒后会掉。keep-power-in-suspend则相反，挂起时保持供电，唤醒快但费电——这两个属性按产品需求二选一，选错的表现是"休眠唤醒后 WiFi 没了"。

3.2 供电、时钟与复位引脚的顺序问题

板级适配里最容易翻车的是上电时序。无线模组一般要求 3.3V 主电、1.8V 或 3.3V IO 电、外部晶振或时钟、复位信号，这几路有明确的先后顺序。驱动里如果只是简单拉一下reset-gpios，很可能因为电源还没稳就释放复位，导致芯片内部状态机卡死。

我的做法是在 probe 里显式控制时序，并在关键步骤之间加延时：

static int hw_power_on(struct my_dev *dev) { int ret; regulator_enable(dev->vmmc); msleep(10); regulator_enable(dev->vqmmc); msleep(5); gpio_set_value(dev->reset_gpio, 0); msleep(20); gpio_set_value(dev->reset_gpio, 1); msleep(50); ret = clk_prepare_enable(dev->clk); if (ret) return ret; msleep(10); return 0; }

这里的延时值不要照抄，要对着手册的时序图算。我曾经为了省事把 20ms 改成 2ms，结果十块板子里有三块起不来，概率性故障最难查，最后还是老老实实按手册来。

3.3 设备树配置的验证方法

设备树改完怎么确认生效？三个动作。第一，启动后看/proc/device-tree/下对应节点是否存在，属性值对不对。第二，看内核日志里 platform 设备有没有被创建，ls /sys/bus/sdio/devices/能不能看到设备。第三，如果设备出现了但驱动没绑定，说明compatible字符串和驱动里的of_match_table对不上，这是最高频的错误，注意大小写和连字符，vendor,wifi-module和vendor,wifi_module是两个完全不同的字符串。

提示：设备树改动后不需要重新编译整个内核，单独替换 dtb 即可。把 dtb 挂到开发板的 TFTP 目录，uboot 里tftpboot加载再启动，一轮验证不到一分钟，比全量烧写快得多。

4. 驱动核心代码：从probe到数据通路

前面都是铺垫，这一节进入真正的代码骨架。我会按 probe 的调用顺序讲，每一步说清楚"为什么这么写"，而不是只贴代码。

4.1 probe入口与硬件初始化

无论总线是哪条，probe 的结构都差不多：拿资源、上电、读芯片 ID、下固件、注册无线设备、注册中断。第一步读芯片 ID 特别重要，它是判断"总线通了但芯片没起来"还是"芯片起来了但型号不对"的分水岭。

static int my_probe(struct sdio_func *func, const struct sdio_device_id *id) { struct my_dev *dev; u32 chip_id; int ret; dev = devm_kzalloc(&func->dev, sizeof(*dev), GFP_KERNEL); if (!dev) return -ENOMEM; dev->func = func; sdio_set_drvdata(func, dev); sdio_claim_host(func); ret = sdio_enable_func(func); if (ret) { dev_err(&func->dev, "enable func failed %d\n", ret); goto err_release; } chip_id = sdio_readl(func, REG_CHIP_ID, &ret); if (ret || chip_id != EXPECTED_CHIP_ID) { dev_err(&func->dev, "chip id mismatch: 0x%08x\n", chip_id); ret = -ENODEV; goto err_disable; } sdio_release_host(func); ret = hw_power_on(dev); ... }

sdio_claim_host和sdio_release_host是 SDIO 特有的，因为 SD 总线是共享的，任何一次读写都必须先拿主机锁。忘了释放的后果是系统其他 SD 设备全部卡死，这种 bug 表现为"插上 WiFi 后 TF 卡读不了"，很有迷惑性。

4.2 通过cfg80211注册wiphy

如果是 FullMAC 方案，接下来就是创建并注册 wiphy。wiphy_new会按你传入的cfg80211_ops分配一个无线设备对象，wiphy_register把它挂到 cfg80211 子系统里，同时触发监管域、可用信道等信息的上报。

static const struct cfg80211_ops my_cfg80211_ops = { .start = my_start, .stop = my_stop, .add_virtual_intf = my_add_vif, .del_virtual_intf = my_del_vif, .scan = my_scan, .connect = my_connect, .disconnect = my_disconnect, .set_channel = my_set_channel, .set_wiphy_params = my_set_params, }; static int my_register_wiphy(struct my_dev *dev) { struct wiphy *wiphy; int ret; wiphy = wiphy_new(&my_cfg80211_ops, sizeof(struct my_dev *)); if (!wiphy) return -ENOMEM; wiphy->interface_modes = BIT(NL80211_IFTYPE_STATION) | BIT(NL80211_IFTYPE_AP); wiphy->bands[NL80211_BAND_2GHZ] = &dev->band_2g; wiphy->max_scan_ssids = 8; wiphy->max_scan_ie_len = 512; wiphy->flags |= WIPHY_FLAG_PS_ON_BY_DEFAULT; *((struct my_dev **)wiphy_priv(wiphy)) = dev; dev->wiphy = wiphy; ret = wiphy_register(wiphy); if (ret) { wiphy_free(wiphy); return ret; } return 0; }

wiphy_priv那块空间是给你存私有指针的，用它把 wiphy 和你的设备结构体关联起来，后面任何回调里都能通过wiphy_priv找回自己的 dev。这个模式在无线驱动里到处都是，值得记牢。

如果是 SoftMAC 方案，把wiphy_new换成ieee80211_alloc_hw，cfg80211_ops换成ieee80211_ops，wiphy_register换成ieee80211_register_hw，其余结构基本一致。mac80211 会替你处理大部分管理面逻辑，你只需要实现tx、start、stop、add_interface这些底层回调。

4.3 收发路径与中断处理

数据通路的核心是两条：发送方向挂ndo_start_xmit，接收方向在中断里把数据搬进内核再交给框架。发送时通常要把 skb 复制到 DMA 缓冲，然后启动发送引擎，芯片发完产生中断，你在中断里回收缓冲。这里最容易出问题的是缓冲区生命周期——如果提前释放了还在被 DMA 使用的内存，表现是数据偶发错乱，日志里什么都看不到。

中断处理建议用上半部加下半部的经典结构：上半部只做寄存器读取和中断清除，确认中断源，剩下的收包、状态更新全部扔给 tasklet 或 workqueue。原因很直接：无线的中断频率在高速率下能到每秒数万次，中断里做太多事情会把系统软锁死。接收时也不要一个包一次处理，配合 NAPI 机制批量收取，CPU 占用能降一大截。

static irqreturn_t my_isr(int irq, void *data) { struct my_dev *dev = data; u32 status = my_read_reg(dev, REG_INT_STATUS); if (!status) return IRQ_NONE; my_write_reg(dev, REG_INT_STATUS, status); if (status & INT_RX) napi_schedule(&dev->napi); return IRQ_HANDLED; }

5. 内核裁剪与性能调优

驱动能跑通只是及格，嵌入式的真正考验是把它塞进几十兆的固件里，还得在有限算力下跑出够用的吞吐。这一节讲裁剪思路和几个实测有效的调优点。

5.1 裁剪的原则与常用开关

裁剪的核心原则是先减依赖再减功能。依赖层面，去掉 WEXT 这套老接口能省不少空间，现在 wpa_supplicant 早就走 nl80211 了；去掉用不到的网络协议（比如 AppleTalk、IPX）也是常规操作。功能层面，加密套件按产品需求裁剪，只保留 WPA2 和 WPA3 就够了；速率控制算法留一到两个；mesh、P2P、AP 模式不用就全关。

关CONFIG_DEBUG_FS要特别小心，因为不少无线工具依赖它统计信息，关了之后iw的部分输出会失效。我的做法是开发版全开、量产版在最后一步再关，中间用两份 defconfig 管理。

5.2 影响吞吐的几个调优点

吞吐上不去，先别急着改协议参数，按这个顺序查效率最高。第一看总线宽度和时钟，SDIO 用 1 位模式和 4 位模式差距能到三倍，PCIe 看是不是跑在 x1 Gen1 而芯片支持 Gen2。第二看DMA 缓冲数量，收发环太浅会导致频繁等待，太深又占内存，一般 64 到 256 之间找平衡。第三看中断合并，高速率下每秒中断次数过万，开启中断合并（或者用 NAPI 的预算参数调节）能明显降低 CPU 占用。

还有两个容易被忽略的点。一是电源管理，量产固件为了省电常开省电模式，但省电模式会引入几十毫秒的往返延迟，测吞吐时务必先关掉，iw dev wlan0 set power_save off。二是监管域设置，信道带宽和发射功率都受监管域约束，如果没正确设置，可能只跑在 20MHz 带宽上，自然达不到预期速率。设置方式和具体区域的合规要求请参考你所在地区的公开规范，产品化时按规定配置即可。

注意：调优要有量化对比，每次只改一个变量，记录吞吐和 CPU 占用。我见过一次性改五六个参数，结果性能反而下降，最后根本不知道是哪个参数导致的，只能全部推倒重来。

6. 调试与常见问题排查实录

驱动开发的时间大概七成花在调试上。这一节我把这些年遇到的高频问题整理成表，再补充几条别人不太会写进文档的经验。

6.1 排查思路与工具链

排查顺序我总结成一句话：先看设备有没有，再看驱动绑没绑，然后看固件下没下，最后才看数据通不通。这四步对应四组工具：

• 设备枚举：lspci -nn、lsusb -t、ls /sys/bus/sdio/devices/
• 驱动绑定：lsmod、dmesg | grep -i wifi、ls /sys/bus/*/drivers/*/
• 固件加载：dmesg | grep -i firmware、ls /lib/firmware/
• 数据通路：ip link、iw dev、ethtool -S wlan0、cat /proc/interrupts

/proc/interrupts这个文件很多人不常用，但它能直接告诉你中断有没有真的进来。如果中断计数一直是零，说明要么中断线没配对，要么芯片压根没起来，问题定位瞬间缩小一半。

6.2 常见问题速查表

这张表里的每一行我都至少踩过一次，尤其是unclaimed那条。它的本质是内核发现了一个设备，但没有驱动声明能处理它，所以挂着不动。很多人以为是驱动没编译进去，其实是驱动在，只是compatible字符串差了一个字符，或者device_id表里漏了这条。

6.3 几条不在文档里的实操心得

第一条，保留一份最简可复现环境。我习惯在调试时准备一块只装最小系统加驱动的板子，不带任何多余服务。因为网络管理器和驱动抢接口控制权的情况太常见了，NetworkManager会在你还没调完驱动的时候就发一堆配置命令进来，日志里全是干扰项。用systemctl stop NetworkManager停掉，或者干脆用最小 rootfs，排查效率翻倍。

第二条，给每次实验打版本标记。驱动、固件、设备树三者的组合可能有很多种，我见过同事一天之内换了七八种组合，最后自己也说不清哪块板子烧的是哪套，只能全部重来。我的做法是启动脚本里打一行版本日志，包含驱动 commit、固件校验和、dtb 时间戳，一条dmesg就能还原现场。

第三条，重视错误码而不是错误信息。内核打印的信息有时很笼统，比如就一句 "probe failed"，但返回的-EPROBE_DEFER和-ENODEV含义天差地别。前者说明资源还没准备好，内核会自动重试；后者说明真的匹配失败，重试也没用。我在 probe 里每一处失败都单独打错误码，后面排查省了无数时间。

第四条，性能问题先怀疑板子，再怀疑代码。我遇到过一例吞吐只有标称值三分之一的案例，查了三天代码，最后发现是模组供电的 LDO 选型裕量不够，负载一上来电压就往下掉，芯片自己降速保护。后来换了个压差更小的 LDO 就好了。这类问题驱动层完全看不出来，只能靠示波器量电源纹波。

第五条，优先用现成驱动的框架结构。如果主线内核里已经有一个结构相似的驱动，把它的 probe 流程和注册顺序抄过来，能避开大量顺序性陷阱。无线驱动的初始化顺序非常讲究，先注册中断还是先注册 wiphy，先下固件还是先读 ID，错了就会出现各种概率性故障。参考一个经过无数人验证的顺序，是最省事的做法。

最后说一句实在话，Linux WiFi 驱动开发的门槛不在代码量，而在这条链路上每一环的细节都得对。总线枚举、供电时序、固件版本、设备树字符串、监管域配置，任何一环偏了都表现为"WiFi 用不了"这个笼统的结果。我的习惯是每完成一个环节就独立验证一次，别等到最后一起测，那样出了问题只能大海捞针。