GobiNet驱动V1.6.2.9：嵌入式Linux下4G模组拨号联网实践

简介：移远通信Linux/Android平台GobiNet驱动V1.6.2.9，是为移远Gobi系列3G/4G/LTE模块适配的Linux内核驱动源码包，适合嵌入式开发、物联网设备及工业路由等场景，解决系统识别无线模组并建立数据通道的问题。压缩包共9个文件，包含3个C源文件、3个头文件、2个说明文档与1个Makefile，整体仅61KB，结构精简，便于开发者快速阅读、修改并编译生成Gobinet.ko内核模块。已有893人学习下载，实测可稳定运行于海思平台，兼容性经过验证。通过该驱动源码，读者能掌握QMI设备注册、USB网络适配、内核模块编译等关键逻辑，可直接用于自研硬件系统集成或驱动二次开发，对基于移远模组的Linux项目具有明确参考价值。

1. 嵌入式Linux连蜂窝网：为何GobiNet是绕不开的一环

做工业路由器、车载终端或者便携式网关的工程师，大概率都经历过这种场景：4G模组插上USB，系统里多出了三个ttyUSB设备，却没有一块网卡，拨号脚本也总是卡在找不到QMI接口那一步。标题里这份某模组厂商发布的GobiNet驱动V1.6.2.9，就是专门解决“内核认不出USB复合设备、协议栈没有数据入口”这类linux驱动问题的底层程序包。它的核心作用是把模组的数据通道映射成一块虚拟网卡，同时留出控制通道给拨号工具下发连接请求。适合正在做模组适配、RIL移植或USB网卡调试的开发者，新手也能照步骤编译加载。

2. 驱动包内部：GobiNet与qmi_wwan的三处关键差异

拿到压缩包先别急着make，先把驱动选型和源码结构搞清楚，后面编译和排错会省很多时间。GobiNet不是Linux内核自带的驱动，它和内核通用的qmi_wwan驱动之间有几个关键差异，理解这些差异，你就知道为什么模组厂商还要单独维护一个驱动版本。

2.1 为什么Linux内核已有qmi_wwan，还要单独编译GobiNet

Linux内核主线一直保留着qmi_wwan这个通用QMI网卡驱动，很多发行版默认就能识别标准QMI接口。但它解决的是“标准情形”：设备遵循通用的CDC/QMI描述，枚举出来的接口类别和端点都符合内核预期。而实际模组设备通常是一个USB复合设备，一个物理USB接口下同时有AT端口、QMI控制端口和数据端口，不同固件版本的接口排列顺序、端点数量、甚至CDC管理功能子类都可能不一样。qmi_wwan一旦遇到非标准描述符，要么枚举失败，要么把数据通道绑定到错误的接口。

GobiNet则是模组厂商基于自家模组的USB描述符和协议行为维护的专用驱动。它把QMI层的控制消息封装得更细，对自家模组特有的QMI命令（比如查询信号、设置网络偏好）支持更完整。此外，GobiNet在Android系统里还配套了RIL侧的桥接代码，这在qmi_wwan里是没有的。所以如果你的Linux发行版只做简单拨号，qmi_wwan够用；但如果做整机产品、要对接Android RIL，或者需要厂商私有AT与QMI配合，就得用这套专用驱动。

总结下来三处差异：一是绑定策略，qmi_wwan按内核通用id_table匹配，GobiNet针对厂商设备描述符做适配；二是QMI私有命令支持，GobiNet能处理厂商扩展消息；三是Android配套，GobiNet压缩包里直接带RIL桥接代码。后面编译和排错时的很多选择，都由这三处差异决定。

还有一个容易忽略的问题：qmi_wwan和GobiNet不能同时绑定同一个USB接口。两者都注册了QMI接口的匹配表，谁先加载谁绑定。如果你之前因为好奇加载过qmi_wwan，再insmod gobinet模块就会看到类似“device already claimed”的提示，后面避坑部分会讲怎么清理。

2.2 压缩包里的源码布局：从Makefile到模块入口

gobinet_driver/ ├── gobinet/ │ ├── src/ │ │ ├── qmi.c # QMI控制消息的组包与解包 │ │ ├── qmi.h # QMI协议头文件，定义消息类型 │ │ ├── usbnet.c # 数据通道的SKB收发与URB处理 │ │ └── gobinet_main.c # 模块入口，注册USB驱动和net_device │ ├── Makefile │ ├── Kbuild │ └── README ├── QMI_WWAN/ # 通用QMI驱动的wrapper层，便于对比 ├── Android/ # RIL HAL侧的桥接源码与so工程 ├── udhcpc/ # 拨号后获取IP的脚本示例 └── tools/ # QMI拨号测试工具

这是根据这类驱动包的常见布局梳理出来的，不同版本目录名略有出入。重点关注两个文件：qmi.c和gobinet_main.c。qmi.c里定义了QMI控制消息的组装和解析，比如无线数据服务(WDS)的Start Network请求、Get Settings请求；gobinet_main.c则负责在USB驱动探测到设备时，分配一个net_device实例并注册到内核协议栈。usbnet.c处理的是USB请求块URB的提交和回调，数据包从这里进协议栈。

如果你下载的版本里没有QMI_WWAN目录，也不用担心，它只是把内核已有qmi_wwan的源码包装了一份，方便对比两者的行为差异。实际编译时，驱动目录下生成的是gobinet.ko这一个模块，QMI_WWAN里的东西通常不会一起编进内核。

2.3 控制通道与数据通道的分工：QMI接口和wwan网卡

QMI是一套基于消息的调制解调器控制协议，一个GobiNet驱动实例通常维护两条通道：

控制通道走的是USB CDC的语法——控制设备口和数据口有严格的接口顺序，消息在USB的BULK端点传输。数据通道则在网卡注册完成后，由内核通过net_device的open回调启动URB队列，每个URB对应一个USB数据端点。两者物理上在同一根USB线上，逻辑上完全隔离。

调驱动的时候，心里要有这张表：当看到/dev/cdc-wdm0存在但wwan0没出现，说明是驱动注册或枚举的问题；当两个节点都在但拨不上网，问题大概率在QMI协议交互或上层网络配置。这能帮你快速缩小排查范围，不用每次都把dmesg翻到底。

3. 编译与加载：V1.6.2.9从源码到wwan0

这一章按实际动手顺序来：先把编译环境准备齐全，再修改Makefile里三个关键参数，最后编译安装并验证模块是否加载成功。在x86主机上交叉编译arm64目标板是最常见的场景，如果你是在本机编译，跳过CROSS_COMPILE那行即可。

3.1 编译环境准备：内核版本、头文件和交叉工具链

GobiNet是内核模块，最终要insmod到目标内核里，所以编译环境必须和目标内核保持“版本一致”。这里的版本一致不是指Linux内核大版本相同就行，而是指vermagic字符串完全一致，包括版本号、SMP/PREEMPT配置、编译器版本。稍微错一点，insmod时会直接报错。

# 在目标板上执行，确认运行内核版本 uname -r # 例如 5.15.0-91-generic # 在开发机上确认是否有对应头文件包 ls /lib/modules/$(uname -r)/build # 如果是交叉编译，把目标板的/lib/modules目录拷到工具链sysroot

如果ls命令报目录不存在，说明缺linux-headers，需要先用系统包管理器安装。对于嵌入式目标板，通常厂商已经提供了内核源码，你需要先完成内核的编译配置，让源码目录下生成Module.symvers后再来编外部模块。GobiNet编译时会读取内核源码目录下的Module.symvers来解析依赖符号，这个文件缺失会导致编译报错，比如找不到usb_register_driver等符号定义。

参数说明：KERNELDIR指向的内核源码目录，编译系统需要里面有配置过的include目录和Module.symvers；ARCH指定目标架构；CROSS_COMPILE指定交叉工具链前缀。这三个参数在Makefile里写死，也可以在命令行覆盖，后面会逐一展开。

3.2 修改Makefile并编译：三个必配参数

打开gobinet目录下的Makefile，重点看开头的CONFIG部分：

# gobinet/Makefile KERNELDIR ?= /lib/modules/$(shell uname -r)/build ARCH ?= arm64 CROSS_COMPILE ?= aarch64-linux-gnu-

如果你在x86开发机上给arm64目标板编译，把KERNELDIR改成目标内核源码的路径，ARCH设为arm64，CROSS_COMPILE设成你的工具链前缀。如果本机编译，删掉ARCH和CROSS_COMPILE两行即可。接着执行：

cd gobinet make clean make -j$(nproc)

编译完会在当前目录生成gobinet.ko。如果没有报错但没生成.ko，多半是make进入了错误的子目录，检查Makefile里的obj-m变量是否指向了src目录，例如：

obj-m := gobinet.o gobinet-objs := src/qmi.o src/usbnet.o src/gobinet_main.o

Kbuild系统会读取obj-m来链接成模块，如果源码文件在src子目录，需要在Kbuild里用相对路径指明每个.o。很多新手直接make，却不知道Makefile只是入口，真正的规则由Kbuild解析。

编译完成后，要么把gobinet.ko拷到目标板手动insmod，要么用make modules_install装到rootfs：

make modules_install INSTALL_MOD_PATH=/path/to/rootfs

INSTALL_MOD_PATH指定的是目标文件系统的根目录，模块会被安装到对应内核版本的extra目录下，配合depmod生成依赖关系。如果你只是调试，手动insmod更直接，省的踩rootfs路径不对的坑。

3.3 加载模块与udev自动绑定：插入即联网

手动加载时先确认没有其他驱动占用QMI接口：

# 查看当前哪些驱动绑定了USB接口 lsusb -t # 如果看到qmi_wwan已经绑定，先卸载 sudo rmmod qmi_wwan sudo insmod gobinet.ko

加载成功后，dmesg能看到驱动探测到设备并注册网卡的日志。此时重新插拔USB设备，GobiNet会绑定对应的接口，生成wwan0。

要在产品里做到插入即用，写udev规则是最常见的做法。新建/etc/udev/rules.d/99-gobinet.rules：

SUBSYSTEM=="usb", ACTION=="add", ATTR{idVendor}=="你的VID", ATTR{idProduct}=="你的PID", RUN+="/sbin/modprobe gobinet"

参数说明：SUBSYSTEM用usb是因为GobiNet是USB驱动；idVendor和idProduct替换成你lsusb实际抓到的值，不要照抄网上的；RUN里执行的modprobe会自动加载模块，省去手动insmod。注意udev规则里不能用shell的管道和重定向，这点和命令行不一样，很多人在规则里写echo到文件去切USB模式，结果是规则不生效。

注意：udev规则修改后，用udevadm control --reload重新加载规则，否则新规则要等下次系统启动才生效。

另外，加载顺序要保证：模块先加载，设备后插入，这时udev触发modprobe只是确认模块已经就位；如果设备先插入、模块后加载，USB总线的重新探测需要手动触发。可以这样强制绑定：

echo "1-1:1.0" > /sys/bus/usb/drivers/gobinet/bind

bind文件接受的是USB接口的bus id。这属于手工干预手段，一般调试时用，产品里还是要靠udev和init脚本配合。

4. 拨号联网与Android接入：从QMI请求到网络配置

驱动加载成功只是第一步，真正让设备上网，还要经过QMI拨号、IP配置、路由设置这几道工序。这一章讲清楚数据链路怎么从模组走到你的应用层，以及Android系统与标准Linux在处理上的差别。

4.1 用QMI拨号脚本下发连接请求：APN与鉴权参数

GobiNet驱动的控制通道暴露为/dev/cdc-wdm0，QMI拨号的本质是往这个节点写入一条WDS Start Network消息，模组收到后向运营商网络发起PDN连接，成功后返回给拨号端一组IP配置信息。实际开发中很少有人从零拼字节，最常用的是libqmi库里的qmicli工具：

qmicli -d /dev/cdc-wdm0 --wds-start-network \ --apn="你的APN" \ --username="你的用户名" \ --password="你的密码" \ --ip-type=ipv4

这条命令的逻辑是：指定QMI设备节点、发起网络连接、携带APN和鉴权参数。APN由运营商提供，通常在模组调试文档里有示例表格，比如很多公共APN只有一个名称。username和password大多数公共APN为空。ip-type根据你的业务选，现在运营商普遍支持双栈，但车机或物联网卡经常只要IPv4，保持默认即可。

命令执行成功后，终端会打印一个IP地址、网关和DNS列表。这时千万别急着关终端，qmicli默认是会话型的，进程退出后连接可能自动释放。产品代码里要用libqmi的API循环保持连接，或者写成daemon脚本。我一般会先用qmicli -d /dev/cdc-wdm0 --wds-get-current-settings确认连接还在，再进入下一步网络配置。

4.2 手动配置wwan0：IP、路由与DNS三件套

拨号拿到的IP不会自动配到wwan0上，需要自己动手。两种方式都可行：

# 方式一：动态获取，适用于模组侧已做DHCP代理 ip link set wwan0 up udhcpc -i wwan0 -q # 方式二：手动配置，IP来自拨号返回 ip link set wwan0 up ip addr add 192.168.25.2/24 dev wwan0 ip route add default via 192.168.25.1 dev wwan0

方式一里的udhcpc发DHCP请求，模组侧如果有DHCP代理就分配地址，最简单。但有些模组的GobiNet数据通道不做DHCP代理，必须用方式二。注意方式二里IP、网关要用qmicli返回的实际值，不是照抄示例。很多工程师在拨号工具里看到了IP，却忘了把IP绑到wwan0，导致网卡一直处于DOWN状态，这就是典型的“拨号成功但不出网”。

DNS配置容易被忽略。在Linux桌面环境，NetworkManager接管后会自动读取链路DNS；但在嵌入式init脚本里，通常需要手动写/etc/resolv.conf：

echo "nameserver 8.8.8.8" > /etc/resolv.conf echo "nameserver 114.114.114.114" >> /etc/resolv.conf

DNS服务器最好从QMI返回信息里提取，不要写死。部分物联网卡对特定DNS有解析优化，写死反而会有兼容问题。配置完成后，先用ping网关验证链路通不通，再用ping外网域名验证路由和DNS是否都正常。

提示：调通后记得把wwan0的IP配置和DNS都固化到你的网络管理脚本里，不要依赖qmicli的终端会话，否则模组一重启，连接就全丢了。

4.3 Android下的对接差异：netd、SELinux与权限

Android和标准Linux的区别在于，网络配置权限不直接放开给应用或shell，而是由netd统一管理，RIL层则通过HAL接口和驱动通信。GobiNet驱动在Android下的加载方式和Linux没有本质区别，但上层对接多出几个关键点。

首先是RIL。Android的rild进程在初始化时打开/dev/cdc-wdm0，通过QMI协议查询SIM状态、信号、注册状态。驱动包里的Android目录下通常有对应HAL层的桥接代码，编译成so库后放进vendor分区。系统服务经由TelephonyFramework走到RIL，最终落到QMI。如果你的HAL库和驱动版本不配套，rild会在日志里报消息类型解析失败，这个问题在避坑章还会展开。

其次是netd权限。Android 8以上版本对网络设备的管理有严格的SELinux策略，wwan0必须能被netd控制，否则会出现设备节点存在、RIL也正常，但调用NetworkAgent接口时直接报Permission denied。调试时用adb shell dmesg查看avc denied日志：

adb shell dmesg | grep avc # 常见输出：avc: denied { read } for pid=1234 comm="rild" name="cdc-wdm0"

看到这类日志，先不要怀疑驱动，去sepolicy的te文件给对应domain添加allow规则。还有一个容易忽略的点：Android系统会把wwan0当通用网络设备处理，需要在ConnectivityService里把它的TransportType配为TRANSPORT_CELLULAR，否则系统不知道这块网卡是蜂窝数据，会把它和WiFi混为一谈，出现“有网卡但设置里显示无流量”的情况。

5. 避坑手册：GobiNet最常见的四个翻车现场

这一章是血泪经验合集。四个问题几乎覆盖了GobiNet从编译到拨号的绝大多数故障场景，每条按“现象、原因、解决”三个步骤展开，方便你照着排查。

5.1 加载报错：version magic不匹配

现象：insmod gobinet.ko时终端打印类似“version magic '5.15.0 SMP mod_unload' should be '5.15.0-91-generic'”的提示，模块加载失败。

原因：编译这个.ko时使用的内核源码版本，与你当前运行内核的vermagic不一致。vermagic由内核config里的CONFIG_SMP、CONFIG_PREEMPT、CONFIG_MODULE_UNLOAD等宏决定，升级内核或换了发行版后，旧模块几乎都会出现这个错。

解决：用与目标板完全一致的内核源码重新编译，编译前确认KERNELDIR指向正确。一个取巧的办法是在模块源码里加MODULE_INFO(vermagic, "你的vermagic字符串")强制绕过检查，但这样加载后极大概率出现符号找不到或内存踩踏，不推荐产品里用。我一般会在编译机上保留一份和线上完全相同的源码目录，并且先跑一遍make modules_prepare再编外部模块。

5.2 有ttyUSB但没wwan0：USB模式卡在RNDIS

现象：插入模组后，/dev/ttyUSB0和ttyUSB1正常出现，但lsusb输出显示接口列表里全是CDC ECM/RNDIS类型，wwan0始终不出现。

原因：模组当前的工作模式不是“AT+QMI”模式，而是被配置成了USB网卡直通模式。很多模组固件出厂默认是RNDIS或ECM，为了插上电脑直接被识别成网卡，不需要额外装驱动。但GobiNet要绑定的是QMI接口，二者互斥。

解决：先通过AT串口把模组切到QMI模式。在ttyUSB的AT口执行切换命令，典型指令是AT+QCFG="usbnet",0，部分固件用其他参数名，具体以模组厂商手册为准。发送后重启模组或重新插拔USB，让设备重新枚举。

注意：切换模式后，部分模组的VID或PID会跟着改变，udev规则里的ID也要同步更新，否则会因为匹配不到而无法自动加载驱动。

5.3 拨号成功但Ping不通：路由、MTU和防火墙

现象：qmicli返回连接成功，wwan0也配了IP，但ping运营商网关都超时，或者小包通、大包断。

原因：多数是路由缺失或MTU过大，其次是防火墙策略拦截ICMP。GobiNet数据通道走USB，USB的BULK端点传输链路开销往往比千兆网卡大，默认MTU 1500在包分片时容易出问题。

解决：先看ip route是否有默认路由，没有就手动加上。再看MTU：

# 先ping 1400字节载荷，如果能通，再把载荷调大 ping -s 1400 -M do 网关IP # 如果1400字节通而1472字节不通，基本就是MTU问题 ip link set wwan0 mtu 1400

ping的参数说明：-s指定ICMP载荷大小，-M do表示禁止分片。通过调整载荷大小能找到链路允许的最大包，再把wwan0的MTU设成对应值。防火墙方面，systemd环境跑一下iptables -P FORWARD ACCEPT排除策略问题。还有一点容易被忽略：模组信号差时，重传也会表现为ping不通，先查信号强度再怀疑协议栈配置。

5.4 Android下RIL不断重启：HAL版本与驱动版本错位

现象：Android设备开机后，/proc/modules里看到gobinet已加载，cdc-wdm节点也出现，但rild进程反复崩溃，Logcat里出现QMI connect failed或者unsupported message错误。

原因：驱动包里的QMI消息定义和RIL侧HAL库使用的QMI消息版本不一致。GobiNet V1.6.2.9对应的协议消息集，应与配套的HAL库一起升级。单独升级驱动而旧HAL还在发送旧格式消息，会导致解析失败。

解决：升级驱动时，把压缩包Android目录下对应的HAL库源码也同步编译进镜像。检查rild链接的库版本：

adb shell ldd /system/bin/rild | grep qmi # 确认库路径和版本与驱动包配套

另外，在高版本Android上还要确认SELinux策略允许rild访问QMI节点，avc denied的问题在4.3已经提到。这类问题表现为不稳定复现，日志和版本对照是唯一靠谱的排查手段。

6. 验证驱动是否真正生效：一条命令看穿模组状态

驱动加载完，别急着联调上层，先用下面这条命令把链路状态看全：

lsusb -t | grep -i gobionet && dmesg | grep -i gobionet && ip link show wwan0

lsusb -t的输出能看到USB接口被哪个驱动接管，如果显示driver=gobionet，说明绑定成功。dmesg会打印驱动名称、设备地址、分配的net_device名称。ip link确认wwan0存在且状态为UP，如果状态是DOWN，先执行ip link set wwan0 up再继续。

网络侧验证，先ping运营商网关确认物理链路，再ping外网域名确认整条数据通路。要查模组自身驻网和信号，走AT口：

AT+QENG="servingcell"

这条指令查询当前服务小区，重点关注4G Band、RSRP、RSRQ三项。如果RSRP低于-110dBm，很多物联网卡会出现频繁重建PDN连接的现象，表现就是GobiNet日志正常但网络时断时续，这类问题必须从射频层找原因，驱动层看不出来。

从那以后，我每次拿到新固件或者新模组型号，都强制把“AT查模式、lsusb看绑定、dmesg看驱动、ping测MTU”这四步完整走一遍，再进入上层联调。这套流程帮我避开过不少看起来像驱动bug、其实是配置遗漏的玄学问题。如果你手头正卡在某一步，把这份V1.6.2.9驱动包下载下来，对着Makefile和udev规则逐个核对，会比找任何现成教程都管用。希望帮到你。

本文还有配套的精品资源，点击获取