簡介面向移遠(yuǎn)QuectelGobi系列無線網(wǎng)卡模塊的Linux/Android GobiNet驅(qū)動程序V1.6.2.9用于在Linux系統(tǒng)中識別并驅(qū)動Gobi蜂窩模塊從而建立3G/4G/LTE移動數(shù)據(jù)通信鏈路主要面向嵌入式開發(fā)者、系統(tǒng)運維人員和硬件集成商。壓縮包共9個文件包括3個C源文件、3個頭文件、1個makefile構(gòu)建腳本以及Readme和ReleaseNote兩個txt說明文檔整體僅61KB結(jié)構(gòu)緊湊源碼頭文件是編譯驅(qū)動的基礎(chǔ)makefile可自動構(gòu)建Gobinet.ko內(nèi)核模塊說明文檔涵蓋環(huán)境配置、編譯加載與測試要點。該驅(qū)動已在海思平臺上實測可用目前已有893人瀏覽學(xué)習(xí)。借助此驅(qū)動源碼開發(fā)者無需從零編寫蜂窩模塊驅(qū)動便可在Linux或Android環(huán)境中快速完成移遠(yuǎn)Gobi模塊適配對工業(yè)路由器、車載信息終端、物聯(lián)網(wǎng)網(wǎng)關(guān)等場景有直接實用價值有效縮短移動網(wǎng)絡(luò)功能的開發(fā)周期。1. 從“內(nèi)核不認(rèn)識這個上網(wǎng)卡”說起GobiNet 驅(qū)動到底是拿來干嘛的做嵌入式 Linux 或 Android 系統(tǒng)開發(fā)的人大概率都遇到過這樣一幕把 USB 4G/5G 模塊插到板子上dmesg里能看到枚舉信息但/sys/class/net/下就是不出wwan0。這不是模塊壞了而是內(nèi)核里缺了一個關(guān)鍵的網(wǎng)絡(luò)驅(qū)動層。Quectel_LinuxAndroid_GobiNet_Driver_V1.6.2.9.zip 這份 linux 驅(qū)動程序源碼包解決的就是這個“內(nèi)核不認(rèn)識上網(wǎng)卡”的問題。GobiNet 是高通平臺模塊常用的網(wǎng)絡(luò)驅(qū)動框架Linux 內(nèi)核主線里雖然有qmi_wwan和cdc_ether但很多時候模塊廠商會基于自己的固件實現(xiàn)額外功能比如聚合、多 PDN、信號查詢內(nèi)核自帶驅(qū)動反而容易踩坑。這份驅(qū)動源碼走的是“內(nèi)核模塊 QMI 通道”的路線專為嵌入式平臺交叉編譯設(shè)計的。適合三類人一是做車機(jī)、工控機(jī)、路由器方案的系統(tǒng)工程師二是做 Android 板卡 BSP 的人三是想搞懂 USB 網(wǎng)卡數(shù)據(jù)通路的驅(qū)動學(xué)習(xí)者。2. 驅(qū)動框架拆解GobiNet、QMI 與 USB 數(shù)據(jù)通路的三個關(guān)鍵層次2.1 拿到驅(qū)動源碼先看什么目錄結(jié)構(gòu)與核心文件解壓 V1.6.2.9 這個包之后你不會看到一堆花哨的東西展開也就是GobiNet.c、GobiUSBNet.c、QMI.c、QMI.h、Makefile這幾個文件外加一份 README 和 Android 相關(guān)的 mk 文件。別嫌文件少驅(qū)動這種東西文件數(shù)越少說明邏輯越集中。GobiNet.c是整個驅(qū)動的骨架負(fù)責(zé) USB 設(shè)備的 probe 和 disconnect也就是模塊插入和拔出時內(nèi)核回調(diào)的入口。GobiUSBNet.c管數(shù)據(jù)面URB 的提交、接收、skb 的上拋都在這層你可以把它理解成“USB 數(shù)據(jù)收發(fā)的中轉(zhuǎn)站”。QMI.c是控制面負(fù)責(zé)封裝和解析 QMIQualcomm MSM Interface消息——撥號、獲取信號強(qiáng)度、設(shè)置 APN 都是通過它和模塊內(nèi)部通信。三者的關(guān)系是控制面走 QMI 通道數(shù)據(jù)面走 USB 批量傳輸端點兩者并行互不阻塞。常用做法是把這些文件直接放到內(nèi)核源碼樹的drivers/net/usb/目錄下編譯或者像很多廠商那樣做成獨立模塊用obj-m的方式在樹外編譯。我一般傾向于樹外編譯因為不用動內(nèi)核源碼換內(nèi)核版本時只需要保留好對應(yīng)的 build 目錄就行。V1.6.2.9 這個版本在 Makefile 里默認(rèn)就支持obj-m拿到手不用大改。2.2 數(shù)據(jù)通路到底怎么走從 /dev/qcqmi 到 /sys/class/net/wwan0有時候你看著/dev下出現(xiàn)了qcqmi0或qmi0節(jié)點但wwan0卻遲遲不出現(xiàn)就會開始懷疑驅(qū)動是不是沒加載對。其實這兩者是先后關(guān)系模塊插入后驅(qū)動先注冊 QMI 控制通道生成/dev/qcqmi0字符設(shè)備這是控制面數(shù)據(jù)面要等你通過 QMI 消息發(fā)起撥號模塊返回 PDP context 激活成功后驅(qū)動才會動態(tài)創(chuàng)建wwan0網(wǎng)絡(luò)接口。整條數(shù)據(jù)通路是這樣的應(yīng)用層發(fā) IP 報文 → 交給wwan0網(wǎng)絡(luò)接口 → GobiNet 驅(qū)動把報文封裝成 USB 批量傳輸數(shù)據(jù) → 經(jīng) USB 控制器發(fā)給模塊 → 模塊內(nèi)部走 LTE/5G NR 協(xié)議棧發(fā)到基站。收包方向反過來模塊收到下行數(shù)據(jù)通過 USB 端點中斷或批量傳輸把數(shù)據(jù)拋給驅(qū)動驅(qū)動組 skb 后調(diào)用netif_rx把包送到內(nèi)核協(xié)議棧。值得注意的細(xì)節(jié)是wwan0的創(chuàng)建時機(jī)。如果你用qmicli -p --wds-start-network這類工具撥號撥號成功對應(yīng)的是 WDS 層的連接建立此時驅(qū)動會收到一個 QMI 事件然后觸發(fā)網(wǎng)絡(luò)接口的上線。所以排查問題時先確認(rèn) QMI 通道通不通再確認(rèn)是否已經(jīng)撥號不要一上來就以為是 USB 驅(qū)動問題。2.3 選型邊界GobiNet 與 qmi_wwan/CDC ECM 差在哪很多人會問內(nèi)核主線里不是有qmi_wwan嗎為什么還要用廠商的 GobiNet這個問題的答案不在“能不能用”而在“夠不夠用”。qmi_wwan走的是標(biāo)準(zhǔn) QMI 協(xié)議適合那些只做標(biāo)準(zhǔn)撥號的場景但它對多 PDN、APN 快速切換、固件私有 QMI 消息的支持很弱。GobiNet 的優(yōu)勢在于它是模塊廠商按自家固件調(diào)過的哪些 QMI 消息需要聚合、哪些需要拆分、USB 端點用幾個、緩沖區(qū)怎么規(guī)劃都是對著實測結(jié)果寫的。代價就是閉源 SDK 的味道比較重編譯方式更“手工”不像主線驅(qū)動那樣make menuconfig勾選就行。V1.6.2.9 這個版本在 Linux 3.x~5.x 上編譯兼容性還算好到了 5.15 之后的內(nèi)核需要留意usb_alloc_coherent、sg_page等 API 的變化下文避坑章節(jié)會展開講。如果你不想碰廠商驅(qū)動直接用qmi_wwan也能跑但在用到雙卡雙待、雙 PDN 并發(fā)、或者某些私有 AT 指令擴(kuò)展時表現(xiàn)就會差一些。我見過的多數(shù)量產(chǎn)項目最后還是回到了廠商驅(qū)動上因為出了問題可以拿源碼一層層查不用去猜協(xié)議。3. 交叉編譯 GobiNet 驅(qū)動從 Makefile 到 .ko 的完整流程3.1 編譯環(huán)境準(zhǔn)備與內(nèi)核源碼版本對齊編譯內(nèi)核模塊頭號原則是你用的內(nèi)核源碼版本必須和板子上實際運行的內(nèi)核版本完全一致連小版本號都不能差。GobiNet 這類驅(qū)動大量使用內(nèi)核內(nèi)部符號如skb_copy_to_linear_data、usb_submit_urb、netdev_notify_peers這些函數(shù)的實現(xiàn)頭文件在不同小版本間可能有出入版本不一致輕則編譯警告重則加載時直接報Unknown symbol。先確認(rèn)板子內(nèi)核版本# 板子上執(zhí)行 uname -r # 輸出示例 5.10.110然后準(zhǔn)備交叉編譯工具鏈。以 ARM 平臺為例我常用的組合是arm-linux-gnueabihf-gcc或廠商提供的獨立工具鏈# 設(shè)置交叉編譯環(huán)境變量具體前綴按你的工具鏈來 export CROSS_COMPILEarm-linux-gnueabihf- export ARCHarm接著需要內(nèi)核源碼樹和編譯產(chǎn)物。如果你做過內(nèi)核編譯vermagic里的版本字符串是關(guān)鍵驅(qū)動模塊的 vermagic 必須和內(nèi)核匹配否則insmod時會報version magic錯誤。一般做法是用和板子同分支的內(nèi)核源碼先編譯一次內(nèi)核不用完整編make modules_prepare即可生成Module.symvers和頭文件依賴。# 進(jìn)入內(nèi)核源碼目錄執(zhí)行 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- modules_prepare這一步會生成編譯模塊所需的module.h依賴和Module.symvers文件。之后編譯其他樹外模塊就不會報找不到頭文件的問題了。3.2 修改 Makefile 與執(zhí)行交叉編譯GobiNet 的 Makefile 默認(rèn)寫的是 x86 路徑指向/lib/modules/$(shell uname -r)/build交叉編譯時必須改成指向你的內(nèi)核源碼目錄。打開 Makefile關(guān)鍵變量是KDIR和PWD# 將 KDIR 指向你的內(nèi)核源碼路徑 KDIR : /home/developer/kernel/linux-5.10.110 PWD : $(shell pwd) ARCH : arm CROSS_COMPILE : arm-linux-gnueabihf- obj-m GobiNet.o GobiNet-objs : GobiNet.o GobiUSBNet.o QMI.o all: $(MAKE) ARCH$(ARCH) CROSS_COMPILE$(CROSS_COMPILE) -C $(KDIR) M$(PWD) modules clean: $(MAKE) ARCH$(ARCH) CROSS_COMPILE$(CROSS_COMPILE) -C $(KDIR) M$(PWD) clean這里GobiNet-objs的寫法是內(nèi)核模塊編譯的標(biāo)準(zhǔn)做法表示最終生成一個名為GobiNet.ko的模塊由三個目標(biāo)文件鏈接而成。obj-m GobiNet.o與GobiNet-objs配合使用是為了解決“模塊名和源文件名不一致”的問題。把三個.c文件合到一個.ko里是因為 GobiNet 內(nèi)部函數(shù)相互引用拆成多個模塊會讓符號導(dǎo)出變得復(fù)雜。執(zhí)行編譯make編譯完成后當(dāng)前目錄下會生成GobiNet.ko可以通過file命令確認(rèn)架構(gòu)file GobiNet.ko # 期望輸出 ARM, EABI5, relocatable如果你看到x86-64或ELF 32-bit LSB relocatable, ARM之外的提示說明交叉編譯環(huán)境沒生效檢查 Makefile 里的ARCH和CROSS_COMPILE是否被正確讀取。3.3 常見編譯報錯頭文件路徑與 KBUILD 變量排查編譯報錯最多的是fatal error: linux/xxx.h: No such file or directory。這類問題的原因基本是KDIR指向的目錄里缺少include/generated或arch/arm/include/generated目錄沒有執(zhí)行過make modules_prepare。完整的準(zhǔn)備步驟如下cd /home/developer/kernel/linux-5.10.110 make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- defconfig # 使用板載 defconfig 或供應(yīng)商 config make ARCHarm CROSS_COMPILEarm-linux-gnueabihf- modules_prepare另一個常見報錯是error: implicit declaration of function sg_page或usb_alloc_coherent相關(guān)的警告。這屬于內(nèi)核 API 升級問題5.15 之后sg_page宏定義變了需要增加#include linux/scatterlist.h或者改用sg_page_safe。看到這類報錯先不要慌搜索一下內(nèi)核源碼里這個函數(shù)的定義按新簽名改就行。還有一類坑是Makefile里寫死了編譯器路徑比如寫成了/opt/gcc-linaro-7.5.0/bin/arm-linux-gnueabihf-gcc換了開發(fā)機(jī)后路徑不存在報錯是No such file or directory。建議 Makefile 里只寫CROSS_COMPILE : arm-linux-gnueabihf-把工具鏈路徑加到 PATH 環(huán)境變量里這樣遷移環(huán)境不容易翻車。4. 驅(qū)動加載與上網(wǎng)配置modprobe 之后還要做的事4.1 加載 GobiNet 驅(qū)動并確認(rèn)設(shè)備節(jié)點把編譯好的GobiNet.ko和模塊對應(yīng)的.ko文件拷貝到板子上常見路徑是/lib/modules/$(uname -r)/extra/或直接放/root/加載時用絕對路徑。推薦先用insmod因為它不做依賴解析報錯更直接insmod /root/GobiNet.ko dmesg | tail -20正常情況驅(qū)動的 probe 日志會打印出類似這樣的信息說明 USB 接口匹配成功[ 123.456] GobiNet: probe: VID_2C7C PID_0125 [ 123.458] GobiNet: netdev wwan0 registered注意不同模塊的 VID/PID 不同如果 dmesg 里只有 USB 枚舉日志但沒有 GobiNet 的 probe 日志可以查看/sys/bus/usb/drivers/GobiNet/目錄下是否有設(shè)備綁定記錄ls /sys/bus/usb/drivers/GobiNet/ # 產(chǎn)生類似輸出 0-1:1.0 0-1:1.1 0-1:1.2 bind module unbind有0-1:1.x這樣的設(shè)備節(jié)點說明驅(qū)動綁定成功。如果目錄為空說明驅(qū)動沒匹配上此時要先確認(rèn)模塊的 VID/PID 是否在GobiNet.c的usb_device_id表里。這份驅(qū)動源碼在GobiNet.c里維護(hù)了一張支持列表老版本通常通過MODULE_DEVICE_TABLE導(dǎo)出給內(nèi)核如果新模塊沒被識別就需要手動加一個新的USB_DEVICE條目再重新編譯這個操作比較常規(guī)改完編譯即可。4.2 配置數(shù)據(jù)通道從 QMI 撥號到 wwan0 獲 IP驅(qū)動加載完成后wwan0未必會出現(xiàn)。V1.6.2.9 版本的 GobiNet 驅(qū)動里網(wǎng)絡(luò)接口默認(rèn)是延遲創(chuàng)建的等到 QMI 撥號成功后才上線。撥號這塊常見的工具是libqmi提供的qmicli也可以直接用廠商私有的撥號程序。先確認(rèn) QMI 設(shè)備節(jié)點存在ls /dev/qcqmi* # 常見輸出 /dev/qcqmi0然后發(fā)起數(shù)據(jù)連接。以 libqmi 為例一條標(biāo)準(zhǔn)的撥號命令是這樣qmicli -p -d /dev/qcqmi0 \ --device-open-netnet-raw-ip \ --wds-start-networkapncmnet,ipv4 \ --client-no-release-cid執(zhí)行之后模塊會通過 QMI WDS 協(xié)議建立 PDN 連接GobiNet 驅(qū)動收到事件后創(chuàng)建wwan0。然后設(shè)置 IP 地址和路由# 如果模塊是 raw-ip 模式需要先設(shè)置 echo Y /sys/class/net/wwan0/qmi/raw_ip # 用工具或 dhcp 獲取地址 qmi-network /dev/qcqmi0 start dhclient wwan0很多調(diào)試案例里wwan0拿到了 IP 但 ping 不通網(wǎng)關(guān)多半是 raw-ip 模式和 802.3 模式搞混了。7 系列及之后的模塊默認(rèn)走 raw-ip此時wwan0的報文不帶以太網(wǎng)頭驅(qū)動需要在GobiUSBNet.c里做配置。如果/sys/class/net/wwan0/qmi/raw_ip里的值與你撥號時的--device-open-net參數(shù)不一致就會出現(xiàn)能撥號但數(shù)據(jù)不通的詭異現(xiàn)象排查時一定要先檢查這個值。4.3 開機(jī)自啟與熱插拔處理驅(qū)動加載完不等于大功告成還要考慮重啟后怎么辦。量產(chǎn)環(huán)境建議把 GobiNet 編成內(nèi)核模塊后用modprobe管理放在/etc/modules-load.d/gobinet.conf里寫模塊名并確保模塊依賴沒問題。另外嵌入式設(shè)備經(jīng)常涉及熱插拔usb_autosuspend有時會造成模塊喚醒失敗。繞開方法是在驅(qū)動加載后用echo -1 /sys/module/usbcore/parameters/autosuspend關(guān)閉自動掛起或者在設(shè)備樹里對 USB 控制器做禁用自動掛起的配置。# 關(guān)閉 USB 自動掛起 echo -1 /sys/module/usbcore/parameters/autosuspend撥號過程里出現(xiàn)Timeout錯誤時先確認(rèn) SIM 卡是否識別、信號是否正常再考慮撥號參數(shù)。有些運營商 APN 是 IPv6 或雙棧qmicli參數(shù)里要加ipv4v6否則會撥號失敗。這里最容易踩的坑是 APN 不區(qū)分大小寫但部分運營商的鑒權(quán)方式對用戶名密碼敏感調(diào)試時先把用戶名密碼留空只設(shè)置 APN排除鑒權(quán)環(huán)節(jié)的影響。5. 避坑手冊GobiNet 驅(qū)動在嵌入式設(shè)備上的 5 個常見翻車點5.1 現(xiàn)象wwan0 MAC 地址每次重啟都變有些板子每次開機(jī)wwan0的 MAC 地址都不一樣導(dǎo)致上層應(yīng)用綁定的白名單失效。原因在于 GobiNet 驅(qū)動讀取 MAC 地址的時機(jī)太早模塊固件還沒準(zhǔn)備好讀到一串無效值內(nèi)核就用了隨機(jī) MAC。解決方法是找到GobiUSBNet.c里讀取 MAC 的代碼加一個重試機(jī)制。常見做法是驅(qū)動里加一個延時和次數(shù)限制比如最多重試 5 次每次間隔 200ms直到讀到合法 MACfor (i 0; i 5; i) { ret usb_control_msg(...); // 讀取 MAC 地址的 QMI 請求 if (ret 0 mac[0] ! 0) break; msleep(200); }改完重新編譯加載MAC 就穩(wěn)定了。5.2 現(xiàn)象insmod 報Unknown symbol錯誤加載時內(nèi)核報Unknown symbol in module通常是模塊依賴的內(nèi)核符號未導(dǎo)出或版本不匹配。先看具體是哪個符號缺失cat /proc/kallsyms里搜不到對應(yīng)的導(dǎo)出符號大概率是內(nèi)核 config 沒打開相關(guān)選項。GobiNet 依賴CONFIG_USB_NET_DRIVERS、CONFIG_USB_USBNET這些基礎(chǔ)選項如果板子的內(nèi)核裁剪過需要重新配置內(nèi)核打開這些選項。5.3 現(xiàn)象Android 8 之后高版本內(nèi)核上編譯不過Android 內(nèi)核從 4.9 升到 4.14、4.19 時不少驅(qū)動代碼會碰到 API 變化。kernel_read從 3 個參數(shù)變成 4 個參數(shù)access_ok的檢查方式也變了GobiNet 驅(qū)動里如果有這類調(diào)用就需要適配。確認(rèn)你的 Android 內(nèi)核版本打開驅(qū)動源碼搜索這些 API逐個修改參數(shù)即可。grep -n kernel_read\|access_ok GobiNet.c GobiUSBNet.c QMI.c修改之后建議先用scripts/checkpatch.pl跑一遍或者直接對照內(nèi)核源碼樹里的類似驅(qū)動看新 API 的用法避免編譯通過但運行時報Oops。5.4 現(xiàn)象下行數(shù)據(jù)通但上行阻塞或者反過來這種“半通”狀態(tài)非常折磨人。上行通、下行不通優(yōu)先查wwan0的 MTU 設(shè)置和 USB 端點的maxpacket。GobiNet 的GobiUSBNet.c里寫死了發(fā)送緩沖區(qū)和聚合的閾值MTU 設(shè)得過大容易導(dǎo)致 URB 緩沖溢出。我一般把wwan0的 MTU 設(shè)為 1420 或 1500 小一點的值避免 PPP 或隧道場景下的分片問題。同時檢查模塊是否開了 USB 聚合聚合模式下延遲和吞吐量會有變化。5.5 現(xiàn)象內(nèi)核版本升級后驅(qū)動“帶著跑不動”5.10 升 5.15 是很多項目的坎。GobiNet 這類廠商驅(qū)動對內(nèi)核 API 的適配存在滯后升級內(nèi)核不能只替換鏡像必須同步把驅(qū)動源碼里的alloc_etherdev、ndo_stop、netif_rx等回調(diào)函數(shù)簽名核對一遍。最保險的做法是先在新內(nèi)核上編譯一遍看 warnings再在所有TODO或FIXME注釋處按新寫法改。別直接拿舊.ko加載新內(nèi)核那種做法 99% 會在insmod時掛掉。6. 拿到驅(qū)動后的驗證清單從吞吐測試到信號查詢的完整閉環(huán)拿到 V1.6.2.9 驅(qū)動源碼并編譯好后建議按以下清單做一輪完整驗證確認(rèn)驅(qū)動“能用”而不是“看起來能用”。第一步是確認(rèn)基礎(chǔ)狀態(tài)。加載驅(qū)動后依次檢查設(shè)備節(jié)點、wwan0是否出現(xiàn)、IP 是否獲取成功、ping網(wǎng)關(guān)是否通。第二步是吞吐測試。推薦用iperf3測服務(wù)器放在公網(wǎng)或局域網(wǎng)服務(wù)器上客戶端在板子上跑iperf3 -c 192.168.1.100 -t 30 -i 5 -u -b 50M看 UDP 是否掉包TCP 是否有重傳。如果掉包嚴(yán)重先把 MTU 調(diào)小到 1400再看模塊側(cè)的信號強(qiáng)度。信號查詢可以用 QMI 命令qmicli -p -d /dev/qcqmi0 --dms-get-signal-strength # 輸出示例 [Signal Strength] RSSI: -65 dBmRSSI 低于 -100 dBm 時數(shù)據(jù)面性能差是正常的不是驅(qū)動問題。RSSI 正常但吞吐上不去再排查 USB 是否跑在 HS 模式lsusb -t看速率。還想驗證驅(qū)動的穩(wěn)定性可以寫一個簡單的循環(huán)腳本反復(fù)ifconfig wwan0 down/up或者反復(fù)拔插模塊再撥號觀察驅(qū)動是否每次都正確釋放和重新申請資源。這類熱插拔循環(huán)測試最容易暴露內(nèi)存泄漏跑上幾百次后用cat /proc/slabinfo看 skb 緩存是否持續(xù)增長。驅(qū)動調(diào)優(yōu)方面GobiNet 的模塊參數(shù)GobiNet_max_netdev控制最大網(wǎng)絡(luò)接口數(shù)GobiNet_eth_mode控制以太網(wǎng)模式默認(rèn)值通常是編譯前在GobiNet.c里設(shè)好的不需要全部改。只有做多 PDN 并發(fā)時才需要調(diào)高max_netdev。從那以后我每次拿到一份沒接觸過的驅(qū)動源碼都會強(qiáng)制走一遍“先看 Makefile、再查 API 適配、然后 insmod 看 dmesg、最后跑吞吐和熱插拔”的流程把驗證做在前面后面量產(chǎn)才能少熬夜救火。希望這份拆解能幫你少走一段彎路。本文還有配套的精品資源點擊獲取