简介RTL8189FS Linux驱动包是由Realtek官方提供的无线网卡驱动源码包面向嵌入式Linux或Android开发者专为海思平台上的RTL8189FS芯片移植、编译与调试设计支持802.11b/g/n标准并针对设备厂商提供了一站式驱动方案。包内共45个文件约15.53MB包括23份PDF文档、10个gz压缩包、4个diff补丁、4个conf配置文件、2个txt说明、1个sh脚本和1个tgz包涵盖驱动源码、编译脚本、HAL层、配置文件和用户空间工具并包含README说明和测试程序。驱动包覆盖Android 4.4、5.x、8.0、9.0等版本对应的Wi-Fi SDK并提供wpa_supplicant/hostapd工具集以及TDLS、WOW、SoftAP等功能的说明文档。已有995人学习使用。开发者可借助Quick Start系列快速完成环境搭建通过diff补丁移植内核模块利用配置和测试工具验证无线功能文档按版本和功能模块分类结构清晰定位便捷是一套适用于设备厂商和驱动开发人员的完整参考资源。 干了这么多年嵌入式Linux跟射频芯片驱动的爱恨情仇能写一箩筐。今天要拆的RTL8189FS_linux_v5.7.9_35795.20191128.zip是Realtek官方放出来的RTL8189FS WiFi模组Linux驱动包。这颗芯片在低成本的平板、电视盒子、工控板、开源开发板上出现频率极高SDIO接口2.4GHz单频802.11 b/g/n架构简单到没什么可吹的但它恰恰是很多设备联网的唯一通道。这个zip包里的东西说复杂不复杂说简单也不简单。很多人拿到手第一反应是丢给内核编译一下结果不是编译报错就是加载后wlan0不出现再不然就是频繁掉线。我自己在好几个方案上都踩过同样的坑所以这篇文章打算把这包驱动的完整使用链路从头到尾捋一遍怎么认识包名、怎么配交叉编译、怎么加载固件、怎么调设备树最后把常见坑也列出来。无论你是刚入行的学生还是半路接手项目的工程师照着这个流程走基本能把RTL8189FS整明白。1. 拆解包名RTL8189FS、v5.7.9和35795这些数字到底是什么意思1.1 先搞清楚芯片本身是什么RTL8189FS是瑞昱推出的一颗SDIO接口WiFi芯片工作在2.4GHz频段支持802.11 b/g/n空间流只有1x1最高协商速率72.2Mbps。这颗芯片最大的特点是便宜、外围器件少、内部集成了PA和LNA所以模组厂做出来pcb面积可以做到很小非常适合对成本敏感的消费类产品。它跟USB WiFi芯片RTL8188FU是同一个IP体系的兄弟芯片只不过接口从USB换成了SDIO。两种芯片的驱动代码结构几乎一样很多厂商在移植的时候甚至会把8188FU的驱动改个名字来用。这也解释了为什么你在翻代码的时候会看到很多重复的宏定义和ifdef分支。这颗芯片在市场上的定位很清晰不需要太高的吞吐量但要求连接稳定、成本可控。比如Linux单板的学习板、安卓平板、OTT盒子、智能家电的联网模组这些都是RTL8189FS的典型用武之地。它走SDIO把数据交到主控SoC不占用USB控制器资源对同时需要挂U盘、4G模组、蓝牙等USB设备的方案来说比USB WiFi更友好。1.2 版本号v5.7.9不是Linux内核版本这是我把很多工程师带跑偏的地方。看到文件名里的v5.7.9下意识以为驱动要求内核5.7.9实际上这是瑞昱自己的驱动版本号。瑞昱的驱动包命名规则一直是“芯片型号_操作系统_驱动版本_内部构建号.zip”所以35795.20191128是瑞昱内部构建号加构建日期代表2019年11月28日编译的版本。驱动版本和内核版本没有一一对应关系这对移植很关键。RTL8189FS官方这套驱动的代码是基于Linux 3.x到4.x时代的内核接口写的如果你把它拿到Linux 5.15甚至更高版本的内核上直接编译大概率会遇到API不兼容的报错。这不是驱动坏了而是内核变了驱动没跟上。注意判断驱动能不能用要看的是SoC厂商BSP里自带的内核版本以及是否有过适配补丁而不是驱动包文件名里的版本号。我经手过的项目里有在Linux 3.10的老内核上跑得好好的也有在Linux 5.4内核上被补丁修过之后正常工作的。最稳妥的办法是先找主控厂商Rockchip、Amlogic、Allwinner这些提供的BSP源码里是否已经带了对应的RTL8189FS驱动分支如果没有再回到官方包基础上自己打补丁。2. 拿到源码包后的第一件事目录结构与构建前准备2.1 解压并看懂目录结构先把包解压出来unzip RTL8189FS_linux_v5.7.9_35795.20191128.zip tar -xjf RTL8189FS_linux_v5.7.9_35795.20191128.tar.bz2 cd RTL8189FS_linux_v5.7.9_35795.20191128打开目录后别急着make先花五分钟把结构搞清楚。这套驱动的代码规模不小但目录逻辑很清晰core/驱动的协议栈核心RTL8189F的MAC层、命令处理、电源管理等逻辑都在这通称为RTWRealtek WiFi核心。hal/寄存器级硬件抽象层RTL8189FS跟硬件打交道的寄存器读写、RF初始化、PHY配置都在这里。os_dep/操作系统适配层所有跟Linux内核API相关的封装都在这个目录里比如网络设备注册、工作队列、定时器、线程休眠这部分是移植时改动最频繁的地方。platform/平台相关的文件从平台获取IO、功耗控制等。Makefile编译入口同时也是整个移植过程中需要重点修改的文件。如果把驱动比作一套房子os_dep就是大门的门槛所有的Linux内核更新导致的问题绝大多数都会先砸到这块门槛上。2.2 Makefile里的交叉编译三板斧平台、工具链、内核路径官方包默认生成的Makefile第一眼是给x86 PC编译用的。我们做嵌入式ARM平台首先要做三件事打开Makefile找到里面大写的CONFIG_PLATFORM系列选项CONFIG_PLATFORM_I386_PC n CONFIG_PLATFORM_ARM_S3C6K4 n ... CONFIG_PLATFORM_ARM_RK3188 y不同SoC平台对应不同的配置项比如瑞芯微方案选CONFIG_PLATFORM_ARM_RK3188三星平台选CONFIG_PLATFORM_ARM_S3C6K4全志平台可能选CONFIG_PLATFORM_ARM_SUN6I或别的变量名。选好之后再改工具链前缀和内核源码路径CONFIG_CROSS_COMPILE arm-linux-gnueabihf- CONFIG_KERNEL_DIR /home/workspace/kernel有些厂商BSP的Makefile写法不太一样会把ARCH和CROSS_COMPILE放在编译命令里而不是Makefile内但本质一样。这里最常见的翻车点是选了某个平台选项之后Makefile内部会额外做一些平台相关的配置比如自动启用某些电源管理宏导致你明明只改了一个选项编译结果跟预期不一样。所以改完Makefile后建议执行一下make clean把之前的编译中间文件全部清掉。提示工具链版本尽量和主控SoC厂商BSP的要求一致。比如arm-linux-gnueabihf交叉编译器版本太新或太老都可能冒出莫名其妙的头文件兼容问题。3. 编译入口从x86到ARM的完整编译流程3.1 编译模块并确认产物做好Makefile配置后执行编译。一般情况下编译命令是这样make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- -j4如果你的Makefile里Platform选的是某个固定ARM平台也可以只敲make。编译过程中看到的输出是在编译一组.o文件最终产物中最重要的文件是8189fs.ko。这个ko文件名是从芯片型号来的8189f sdio的s连起来就是8189fs。编译结束后先用file命令检查ko文件的架构file 8189fs.ko输出里应该明确看到ARM架构比如ARM, EABI, mod_unload modversions ARMv7。如果显示x86-64说明ARCH没传对要么是Makefile里的平台没选到ARM分支要么是命令里没带ARCH参数。接下来把ko文件放到板子的文件系统里然后加载insmod 8189fs.ko模块加载成功后用以下命令确认lsmod | grep 8189 dmesg | tail -n 30 iw dev正常执行完insmod后dmesg里一般会出现类似“RTL8189FS: init”和“wlan0”的日志iw dev也会列出wlan0这个无线网卡接口。如果走到这一步驱动的基本加载就已经成功。3.2 固件处理、开机自启和调试参数RTL8189FS的驱动跟很多WiFi驱动一样运行时需要固件。区别在于瑞昱很多老版本驱动把固件数组直接编译进了驱动的C代码里不需要额外放固件文件但也有编译选项会把固件放在内核固件路径下加载。如果dmesg后看到类似“Direct firmware load for rtlwifi/rtl8189fs.bin failed”的日志那就是需要外部固件的版本。此时把源码包里的rtl8189fs.bin或者rtl8189fs_fw.bin文件复制到板子文件系统的/lib/firmware/rtlwifi/目录下就行了mkdir -p /lib/firmware/rtlwifi cp rtl8189fs.bin /lib/firmware/rtlwifi/要驱动开机自动加载建议把它写进modprobe配置文件而不是直接在rc.local里insmod因为modprobe会自动解析依赖echo 8189fs /etc/modules或者进一步指定加载参数比如关闭节能模式保证无线稳定echo options 8189fs rtw_power_mgnt0 /etc/modprobe.d/8189fs.confrtw_power_mgnt这个参数值得单独说一下。RTL8189FS默认开了省电模式在部分板子上可能导致响应慢、Ping延迟高甚至断流。rtw_power_mgnt0表示关闭省电rtw_power_mgnt1是普通省电rtw_power_mgnt2是最大省电。很多做产品的人会直接把它设成0用一点功耗换取稳定实测效果立竿见影。4. 设备树与SDIO的配合为什么在开发板上总是识别不到wlan04.1 硬件层面容易踩的坑代码编译加载只是一半另一半在硬件和内核设备树。RTL8189FS走的是SDIO接口它本质上是一个SDIO外设所以内核能不能识别它取决于SDIO控制器驱动能不能枚举到这颗芯片以及芯片的上电时序和复位脚是否正常。硬件上最典型的几个坑SDIO_D1、SDIO_D2、SDIO_D3这三个数据线没接全只用1-bit模式导致速率极低。复位脚/使能脚的GPIO没在设备树里正确配置芯片一直处于复位状态SDIO枚举完全看不到设备。VCCIO和主控的IO电平不匹配实测表现是时好时坏有时候开机偶尔识别有时候完全不识别。排查的时候如果dmesg里看不到类似“mmc1: new high speed SDIO card at address 0001”的日志基本可以断定是SDIO总线层面就没枚举出设备先别急着查驱动回头检查硬件和电源时序才是正确的方向。4.2 设备树节点示例设备树配置没有一个放之四海而皆准的模板因为不同SoC的MMC控制器节点写法不一样。但核心思路是相同的让RTL8189FS连接的MMC控制器在系统启动时被正确初始化SDIO主机控制器能发出SDIO卡检测流程。下面是一个在ARM平台设备树中比较典型的配置片段mmc1 { status okay; non-removable; bus-width 4; cap-sdio-irq; keep-power-in-suspend; mmc-pwrseq wifi_pwrseq; vmmc-supply vcc_sdio; vqmmc-supply vcc_sdio_io; #address-cells 1; #size-cells 0; rtl8189fs: wifi1 { compatible realtek,rtl8189fs; reg 1; interrupt-parent pio; interrupts 0 6 IRQ_TYPE_LEVEL_LOW; }; }; wifi_pwrseq: wifi_pwrseq { compatible mmc-pwrseq-simple; reset-gpios pio 0 7 GPIO_ACTIVE_LOW; };这里的non-removable很重要告诉内核这张SDIO卡不是可插拔设备不要去做热插拔轮询和电源切换。bus-width 4把数据线改成4位模式如果不写默认可能只跑1位吞吐量直接砍到四分之一。interrupts里的中断脚和reset-gpios里的GPIO要根据自己板子的实际走线来填。很多新手直接抄网上别人的DTS抄完发现完全识别不了十有八九就是GPIO号跟实际硬件对不上。这块没有捷径必须对着原理图一个个确认。5. 常见问题与排查记录5.1 编译期间的典型错误Linux内核API变更旧驱动的最大敌人是内核API变动。RTL8189FS官方包在Linux 5.x以上版本编译时最常见的报错集中在这些位置sk_buff结构体字段的存取方式变了。timer_list相关的初始化接口变了旧代码用init_timer新内核要求timer_setup。set_fs在5.10以后被移除了而驱动里可能在读写固件时用了它。各种rtw_mdelay、udelay的封装跟内核版本不匹配。解决办法没有银弹。如果BSP内核版本跟官方包发布时间差距在两年以内通常一个小补丁就能过如果差距太大建议先看厂商有没有已适配版本再决定是否要继续啃。我个人的习惯是在公司内部维护一个补丁文件记录每个内核版本下改了什么下次再换内核就有的放矢。这里给一个判断思路编译报错时先去os_dep/目录下找对应的头文件和c文件看它调用的内核函数在当前内核里的定义。比如报错指向net device操作函数就去include/linux/netdevice.h里看struct net_device_ops成员是否变化。这样定位比盲改快得多。5.2 加载模块时的固件与SDIO识别问题驱动编译好了insmod也不报错但iw dev里就是没有wlan0。这种情况多半是驱动在等待固件加载但固件没放到预期位置。打开服务端日志抓重点dmesg | grep -i firmware dmesg | grep -i rtl看到Firmware H2C fail这类日志一般是固件和驱动版本不匹配解决办法是换同一个版本包里的固件文件或者改成编进驱动的固件数组版本重新编译一次。另一种情况SDIO识别问题。dmesg里可能只有“mmc1: error”。这种情况优先检查SDIO时钟频率。有些SoC的MMC控制器默认跑在某些频率下和WiFi芯片的最高频率不匹配需要把SDIO频率上限限制到50MHz左右比如在DTS里加max-frequency 50000000。还有一种非常容易被忽略的情况wlan0在insmod的时候没出现但在rmmod再insmod一次后就出现了。这大概率是上电时序问题芯片没能在第一次枚举窗口内准备好。此时不是反复重启驱动而是应该调整硬件上电时序或者让WiFi芯片的上电早于主控SDIO控制器初始化。5.3 连接不稳定、频繁掉线驱动能起来也能扫描到AP但连接上之后过一会就掉或者传大文件就断流。这种情况首先排查的还是省电模式把模块参数里的rtw_power_mgnt调成0大部分都稳定住了。如果调完还掉线再看硬件信号质量。RTL8189FS是单天线芯片天线匹配不好时RSSI会很低驱动出于保护机制主动断开连接。用iw dev wlan0 link或者iwinfo命令看信号强度如果信号低于-70dBm硬件层面的问题大于软件层面的问题得回去改天线设计或换模组位置。我把这几个高频问题整理成一张速查表方便对照排查现象可能原因处理办法编译报错函数或字段找不到内核API不兼容查对应内核版本的struct定义改驱动适配层insmod成功但无wlan0固件缺失或SDIO未枚举成功检查/粘贴固件位置检查设备树SDIO节点和GPIOdmesg提示mmc errorSDIO信号/时钟频率问题检查电压、IO电平、max-frequency参数连接后频繁掉线省电模式或信号弱设置rtw_power_mgnt0检查天线匹配吞吐量只有协商速率四分之一SDIO未跑4-bit模式修改设备树bus-width46. 实操验收编译完成后如何全面验证无线性能6.1 先用基础工具确认无线网卡状态模块加载并创建wlan0后先做基础确认ip link set wlan0 up iw dev wlan0 scan | head -n 30能看到扫描结果说明射频收发链路基本是好的。ip link set wlan0 up这一步如果报错优先看dmesg有没有RF初始化失败的日志。扫描出来的AP列表里信号强度普遍偏低那就要回到硬件信号通路查天线和匹配网络。连接AP前确认WPA配置工具存在常见的做法是用wpa_supplicantwpa_passphrase MyAP mypassword /etc/wpa_supplicant.conf wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf udhcpc -i wlan0这里有个细节wpa_supplicant能成功连接并不代表驱动完全正常它只说明802.11关联成功了。真正的稳定性测试要到下一步。6.2 吞吐量和丢包测试RTL8189FS的物理层协商速率最高是72.2MbpsTCP实际吞吐量通常能跑到40Mbps左右就算正常。用iperf3测试时建议先把省电模式关掉否则结果会波动很大iperf3 -c 192.168.1.100 -i 1 -t 30另外一项快速测试是Ping大包加连续Pingping -s 1400 -c 200 192.168.1.100重点看丢包率和时延抖动。如果Ping小包(64字节)没问题大包丢包严重有可能是MTU协商问题检查AP端和Linux端的MTU设置是否一致。我测试时还会测弱信号场景人拿着板子往远处走看信号到多少dBm开始丢包这个数据直接决定产品实际使用距离。如果RSSI降到-65dBm就开始大量丢包说明灵敏度不行硬件上还要调。7. 说点项目上拿命换来的经验RTL8189FS这套驱动我前后用了好几年说没有心理阴影是假的但摸透之后它其实是个非常稳定的低成本方案。现在接手新项目只要看到WiFi模组用的是RTL8189FS第一件事就是去厂商BSP里翻有没有对应补丁而不是直接拿官方原始包硬编。厂商BSP往往已经解决了内核适配和平台设备树的问题比自己啃makefile和源码省一天时间。另外我强烈建议源码包解压后第一时间复制一份带版本号的备份目录不要直接在原目录上改。因为这类专有驱动不像主线内核会有人持续维护今天改完能编译三个月后换新内核可能又要重新改。如果没有原始干净版本做对照你会被自己之前改过的东西坑到怀疑人生。在项目验收阶段务必保留“驱动版本 内核版本 工具链版本 设备树文件”这四个信息。我见过太多项目半年后无人能维护就是因为当初代码编过了但没人记录是怎么编过的。这四样信息凑齐换任何一个人来都能在一天内复现编译环境。RTL8189FS不是性能猛兽但它用极低的成本解决了大量设备的联网问题。只要掌握交叉编译、固件加载、设备树配置这三板斧这个芯片在Linux下的开发并没有想象中那么可怕。本文还有配套的精品资源点击获取