去年年底接了块RK3588的开发板项目，板载方案里WiFi模组用的是O9201SB，走的是SDIO接口。当时觉得挺简单，毕竟RK3588的SDIO控制器在Linux内核里支持得挺成熟了，结果真调起来才发现，从设备树写法到驱动加载策略，到处都有需要注意的细节。这篇文章就把我在RK3588平台上把O9201SB WiFi模组接入Linux系统的完整过程记录下来，包括硬件设计要点、内核配置、设备树修改、常见坑位排查和性能测试方法，希望能帮你绕开我踩过的那些坑。
这个内容主要面向做RK3588方案评估或产品开发的嵌入式工程师，也适合正在调试其他SDIO接口WiFi模组的同学参考。如果你手头正好有O9201SB这颗模组，或者正在梳理RK3588的SDIO设备树配置逻辑，这篇文章可以直接照着做。
1. 项目背景与方案选型思考
1.1 O9201SB模组定位与核心参数
O9201SB是一颗支持WiFi 6协议的SDIO接口模组，在RK3588这类高性能ARM平台上主要承担无线网络接入功能。它给我的第一印象是封装比较紧凑，RF前端和基带集成度很高，外围电路要求不复杂，对板级设计来说压力不大。从实际规格来看，它支持2.4GHz和5GHz双频段，在5GHz频段理论速率可以到1200Mbps级别，这个吞吐能力配合RK3588的多核CPU和高速外设，做视频推流或者数据采集传输是完全够用的。
不过这里要提醒一句，标称速率只是理论上限，实际吞吐受天线设计、板级布线和驱动配置影响很大。我在测试中发现，同一个模组在不同板卡上跑出来的TCP吞吐能差出30%以上，后面会专门聊这块。
1.2 为什么选SDIO而不是USB或PCIe
很多人在RK3588上接WiFi模组会优先考虑USB接口，因为Linux下的USB WiFi方案最省事，插上就能用。但实际产品化的时候，SDIO接口的优势就体现出来了：首先是延迟更低，SDIO是CPU侧的总线协议，和USB这种外部设备总线相比，中断路径更短；其次是功耗控制更精细，WiFi模组在待机时可以通过SDIO的时钟停振机制进入低功耗状态，这对电池供电的设备很重要；再有就是带宽稳定性，SDIO 3.0在4-bit模式下就可以跑到SDR104的104MB/s，实际WiFi数据流根本不会把这条总线打满，不会像USB那样出现带宽竞争问题。
代价就是配置复杂度高了不少。SDIO WiFi模组不仅需要正确的内核驱动，还需要设备树里把电源、时钟、中断、复位等引脚全对上，任何一个环节出错，模组都起不来或者不稳定。下面的内容就是围绕着"如何把这些配置一次做对"展开的。
2. 硬件层面的SDIO接口设计要点
2.1 引脚定义与最小连接拓扑
O9201SB的SDIO接口用的是标准4-bit模式，信号引脚一共6根：SDIO_CLK、SDIO_CMD、SDIO_D0、SDIO_D1、SDIO_D2、SDIO_D3。除此之外，模组还有几个控制引脚，包括WIFI_REG_ON（硬件复位/使能脚）、WIFI_HOST_WAKE（中断唤醒脚）、以及供电引脚VBAT、VDDIO。
我当时设计的连接拓扑是这样的：SDIO_CLK、SDIO_CMD、SDIO_D0~D3直接连到RK3588的SDIO控制器引脚上；WIFI_REG_ON接到一个GPIO上，这样驱动里可以通过GPIO控制模组的上下电时序；WIFI_HOST_WAKE接到RK3588的一个可唤醒中断引脚，用做WiFi模组主动唤醒主控的信号线。这里有个细节值得注意：WIFI_HOST_WAKE的极性以及是否需要上拉，必须以模组手册为准，不同厂商的设计逻辑不太一样，接反了会导致休眠唤醒功能完全失效。
硬件上还有一个容易忽略的地方是SDIO_CLK的走线长度。SDIO时钟频率在SDR104模式下可以跑到200MHz，这个频率下时钟线的回沟、过孔带来的寄生电容都会影响信号质量，严重时直接导致数据不稳定。我当时布板的时候把CLK线控制在和CMD、DATA线尽量等长，且在CLK线旁边铺了地线隔离，后面调试过程中几乎没有出现过信号问题。
2.2 电源、复位与上电时序
电源设计这块，O9201SB需要两路电源：一路是VBAT主供电，通常为3.3V，给射频前端和内部电路供电，瞬间峰值电流在WiFi发射时能到500mA以上；另一路是VDDIO，为SDIO接口的电平转换电路供电，可以和主控的IO电平一致，一般也是3.3V或1.8V。我在RK3588开发板上用的是两路独立的LDO/DCDC分别供电，避免WiFi发射时电流波动干扰主控的其他外设。
比供电更需要注意的是上电时序。SDIO WiFi模组对上电顺序特别敏感，如果VDDIO先于VBAT上电，可能导致模组内部电平转换电路工作异常，轻则第一次驱动加载失败，重则烧坏模组。合理的时序是：先给VBAT供电，等电源稳定后再拉高WIFI_REG_ON，最后等模组内部的复位完成信号输出正常后再去初始化SDIO总线。
我在实际调试中遇到过一次很典型的时序问题：把WIFI_REG_ON直接接在了RK3588的某个上电默认为高的GPIO上，导致系统启动时模组提前上电，等到SDIO驱动初始化时模组已经进入了一个异常状态，dmesg里反复报"mmc1: error -110"的错误。后来把WIFI_REG_ON改到了上电默认拉低的GPIO，配合驱动里的GPIO控制，问题就解决了。
2.3 布线层面的三个注意点
板级布线直接决定WiFi射频性能和SDIO信号稳定性，这里分享三个经验：
第一，SDIO数据信号线要远离射频天线区域。SDIO时钟和数据的谐波会和WiFi射频信号产生互扰，影响灵敏度。我当时在天线下方区域禁止了所有SDIO信号线走线，保留完整的参考地平面。
第二，SDIO_CLK线上建议串接22欧姆左右的电阻。这个电阻可以抑制时钟信号过冲，同时减少信号振铃。调试初期不确定走线寄生参数时，先串一个22欧姆电阻是比较稳妥的做法，后面如果发现信号质量没问题可以再移除。
第三，天线馈点周围要留足净空区。O9201SB的RF输出引脚到天线馈点之间的微带线阻抗要控制在50欧姆，周围不要铺铜，否则射频性能会大幅下降。实测过同样的模组和驱动配置，天线处净空良好的板子比净空不足的板子，5GHz频段的吞吐率能高出接近一倍。
3. 内核与设备树配置实操
3.1 内核驱动配置项
RK3588平台在Linux内核里对SDIO WiFi模组的支持已经比较完善，前提是内核配置选项打开对了。我用的内核版本是5.10，需要确保以下几个配置项被开启：
CONFIG_MMC=y CONFIG_MMC_SDHCI=y CONFIG_MMC_SDHCI_PLTFM=y CONFIG_MMC_SDHCI_OF_DWCMSHC=y CONFIG_MMC_SDHCI_ROCKCHIP=y CONFIG_WIRELESS=y CONFIG_CFG80211=y CONFIG_MAC80211=y CONFIG_BRCMFMAC=y CONFIG_BRCMFMAC_SDIO=yO9201SB使用的驱动框架是Broadcom的brcmfmac，所以连接WiFi功能的关键是CONFIG_BRCMFMAC和CONFIG_BRCMFMAC_SDIO被编译进内核或编译成模块。如果用的是模块方式，还需要确保对应的固件文件放到了文件系统的/lib/firmware/brcm/目录下，比如brcmfmac43455-sdio.bin和对应的txt配置文件。
这里踩过的一个坑是：最初编译内核时只开了CONFIG_BRCMFMAC，没开CONFIG_BRCMFMAC_SDIO，导致SDIO总线上的驱动根本没注册，设备树配得再对也没用。检查的方法很简单，启动后执行find /sys/bus/sdio/devices -type l，如果能列出设备说明SDIO枚举成功，否则需要回到内核配置排查。
3.2 设备树节点编写与参数解释
设备树这块是整个SDIO WiFi接入的重头戏，我把最终可用的节点贴出来，然后逐段解释关键参数的含义：
&sdio { status = "okay"; bus-width = <4>; cap-sdio-irq; non-removable; keep-power-in-suspend; pinctrl-names = "default"; pinctrl-0 = <&sdio_clk &sdio_cmd &sdio_bus4>; sd-uhs-sdr104; #address-cells = <1>; #size-cells = <0>; wifi@1 { compatible = "brcm,bcm43455"; reg = <1>; interrupts-extended = <&gpio3 RK_PB5 IRQ_TYPE_LEVEL_LOW>; interrupt-parent = <&gpio3>; interrupts = <RK_PB5 IRQ_TYPE_LEVEL_LOW>; pinctrl-names = "default"; reset-gpios = <&gpio0 RK_PC4 GPIO_ACTIVE_LOW>; }; };这个节点里，bus-width = <4>表示使用SDIO 4-bit模式，cap-sdio-irq表示支持通过SDIO的命令线来传输中断，这是SDIO WiFi模组常用的异步中断方式。non-removable是因为WiFi模组是焊接在板上的，不会热插拔，告诉内核不要做热插拔检测。
sd-uhs-sdr104开启的是SDIO 3.0的高速模式，最高时钟200MHz。这里有个调优经验：如果发现模组在高速模式下不稳定，可以先去掉这行，强制降低传输速率来定位问题。reset-gpios就是前面提到的WIFI_REG_ON引脚，驱动加载时会通过这个GPIO控制模组的上下电。
3.3 编译烧录与驱动加载验证
设备树和内核配置改好之后，就可以编译烧录了。RK3588的SDK一般提供了一键编译脚本，直接用脚本编出boot.img和resource.img，然后通过RKDevTool烧录到开发板。烧录完成后，重启系统，用下面几个命令验证驱动加载情况：
# 查看SDIO总线上的设备枚举情况 find /sys/bus/sdio/devices -type l # 查看WiFi网卡是否注册成功 ip link show # 查看驱动加载日志 dmesg | grep -E "brcmfmac|mmc1|sdio"正常情况下，find命令能看到类似/sys/bus/sdio/devices/mmc1:0001:1的设备，ip link show能出现wlan0，dmesg里能看到brcmfmac: brcmf_fw_alloc_request: using brcm/brcmfmac43455-sdio.bin这样的固件加载信息。如果这些输出都正常，说明驱动已经起来了，剩下的就是连接测试了。
如果dmesg里有报错但设备又出现了，多半是固件版本或者nvram配置的问题，后面我专门开一节讲排查方法。
4. 调试实录：五大常见坑与排查
4.1 坑一：SDIO设备无法枚举，报mmc1: error -110
这是我遇到的第一个拦路虎。启动日志里不停刷mmc1: error -110，这个错误码对应的是超时，意味着SDIO控制器和模组之间的通信一直没有建立起来。
排查思路是逐层往上游找。首先测量WIFI_REG_ON引脚的电压，确认模组上电了；然后用示波器看SDIO_CLK引脚有没有时钟信号输出。我当时测下来发现CLK有波形、电压正常，但依然报超时，最后定位到是VDDIO供电的LDO输出只有1.2V，而模组要求VDDIO是3.3V，电平不匹配导致SDIO信号无法正确识别。把LDO输出电压调整到3.3V后，设备枚举立刻正常了。
这类问题的排查有一个很有效的分层方法：先硬件后软件，先电压后信号，先时钟后数据。不要一上来就怀疑设备树写错了，把万用表、示波器拿出来，把每个引脚的静态状态确认一遍，往往能快速缩小范围。
4.2 坑二：设备能枚举但扫描不到热点
设备枚举成功，wlan0也出现了，但iw dev wlan0 scan的结果是空列表。这个问题我排查了很久，最后发现问题出在板级天线匹配上。
O9201SB模组的射频输出到天线的走线阻抗如果不匹配，回波损耗会非常大，导致射频信号发不出去也收不进来。我当时用的还是半成品的测试板，天线部分是手工焊接的，馈线长度和走线宽度都没按50欧姆设计，导致射频链路几乎全反射。重新按参考设计做了天线匹配之后，扫描热点就正常了。
另一个可能导致扫描不到热点的原因是国家码或信道设置问题。可以试试用iw reg set CN设置国家码，然后重新扫描。如果你的AP刚好在某个信道，而模组固件里的信道列表没有包含这个信道，也会出现扫描为空的情况。
4.3 坑三：连接成功但频繁掉线
扫描正常、也能连上AP，但过一会儿就掉线，这种情况多数和电源纹波及功耗管理策略有关。
WiFi发射时电流波动很大，如果电源的瞬态响应能力不足，电压跌落会导致模组内部自动重启，表现为掉线后立刻重新关联。解决方法是检查VBAT供电线路上的去耦电容是否足够，通常需要预留一个100uF的钽电容或大容量MLCC，靠近模组的VBAT引脚放置。
另外，Linux内核自带的电源管理框架可能会在系统空闲时把SDIO设备挂起，导致WiFi模组的tcp连接被断开。调试阶段可以先用下面的命令临时停掉WiFi的电源管理，确认掉线问题是否由电源管理策略引起：
iw dev wlan0 set power_save off如果关掉电源管理后掉线频率明显下降，就说明是电源管理策略配置的问题，需要检查设备树里的keep-power-in-suspend和cap-sdio-irq配置是否正确。
4.4 坑四：吞吐率远低于标称值
WiFi连接正常、ping稳定，但TCP吞吐率只有几十Mbps，和标称的1200Mbps差很远。我当时的测试结果是下行只有80Mbps左右，问题出在SDIO总线的速率模式没有跑起来。
查看/sys/kernel/debug/mmc1/ios里的时钟和总线模式，发现时钟只有50MHz，远低于SDR104的200MHz。这是因为设备树里的sd-uhs-sdr104没有生效，或者内核在启动时因为检测到信号质量问题自动降级到了较低速率。把设备树的sd-uhs-sdr104配置确认好之后，时钟频率提升到了200MHz，吞吐率也提高到了400Mbps以上。
如果确认SDR104已经生效，吞吐率还是不够，可以检查TCP窗口大小和中断处理效率。SDIO WiFi模组通常会产生大量中断，如果中断亲和性设置不合理，会导致所有中断都集中在一个CPU核上处理，形成瓶颈。我后来通过配置中断亲和性，把WiFi中断分散到多个核心上，吞吐率又提升了一截。
4.5 坑五：休眠唤醒后WiFi丢失
在默认配置下，系统进入深度睡眠后，再唤醒时wlan0消失了，必须重启系统才能恢复。这个问题的核心是设备树里缺少电源管理相关配置。
需要在SDIO节点里加上keep-power-in-suspend，同时在WiFi子节点里确认中断唤醒配置正确。这里的原理是：系统休眠时，SDIO控制器会切断对模组的供电和时钟，如果没有特殊标记，内核会认为设备已经移除，唤醒后自然就找不到wlan0了。
我最终的设备树方案里除了keep-power-in-suspend，还把WIFI_HOST_WAKE引脚配置成了唤醒源，这样模组在接收到AP的唤醒帧后可以主动唤醒主控，而不是仅仅靠主控侧的定时唤醒来恢复连接。这个配置对功耗和体验都有明显改善。
5. 验收测试与性能优化建议
5.1 稳定性验证三板斧
接入完成后，不能只测试"能连上WiFi"就结束了，尤其是要量产或做长时间运行场景的话，下面三个测试建议都要做：
第一，压力传输测试。用iperf3跑持续30分钟以上的双向传输，观察吞吐率是否平稳、有无掉线重连、延迟有无突增。如果一个方向跑不满，多半是链路质量问题，需要回到射频和SDIO配置去排查。
第二，休眠唤醒测试。反复让系统进入休眠再唤醒，每次唤醒后都要检查wlan0是否存在、能否自动重新关联AP。我测试时会写一个脚本，自动执行50次休眠唤醒循环，把每次的结果记录下来，彻底排除偶发性问题。
第三，弱信号场景测试。在远离AP的位置（RSSI在-70dBm以下）测试连接稳定性和重连能力。很多模组在强信号下表现很好，但弱信号下就频繁断开，这时候需要调整天线增益、增加外部PA，或者优化驱动里的漫游阈值参数。
5.2 几个值得尝试的优化方向
如果测试结果都正常，有几个方向可以继续挖掘性能潜力：
一个方向是调整SDIO总线频率和命令超时参数。在SDR104模式下，如果信号质量允许，可以把时钟配到200MHz甚至更高；如果不太稳定，牺牲一点频率换取稳定性反而更划算。另一个方向是检查WiFi驱动的TX队列和NAPI调度参数，适当增大网卡队列深度可以减少高负载下的丢包率。
还有一点容易被忽略：O9201SB模组的固件和nvram配置参数，不同版本对性能影响很大。我在测试中发现，使用原厂提供的最新固件，可以修复一些旧版固件里偶发的断流问题，而且扫描速度也有明显提升。量产前一定要去模组原厂或代理那边确认最新的固件版本，并集成到你的系统镜像里。
如果你做的是对功耗有要求的产品，还可以深入调一下WiFi的DTIM和PS策略。通过iw命令调整wlan0的功率节省参数，可以让设备在待机状态下的网卡功耗降到一个很低的水平，同时保持网络连接的可达性。这个调整需要结合实际场景反复测试，没有通用的最优参数，但是值得花时间去做。
我在实际调试RK3588的SDIO WiFi时，最大的体会是：SDIO WiFi接入工作，看起来是纯软件配置，但真正决定成败的往往是硬件细节。设备树写错了一个pinctrl，或者电源时序差了那么几十毫秒，都会让驱动无法正常初始化。建议大家在动手之前，把模组的手册和数据手册完整看一遍，把电源时序、引脚定义、推荐走线这些硬件要求先用图表梳理清楚，再开始写设备树和调驱动。另外，调试过程中建议保留一份"问题排查日志"，把每个异常现象对应的解决方案记录下来，后续做别的平台或者别的模组时，这份日志就是最宝贵的经验库。