简介：本资源是移远通信（Quectel）官方GobiNet驱动程序的Linux与Android双平台适配版本，专为嵌入式开发者、Linux系统工程师及物联网设备集成人员设计，用于在Linux内核或Android系统中驱动Gobi系列4G/LTE无线模块，实现稳定移动网络连接。压缩包共9个文件，含3个核心C源文件（QMIDevice.c、GobiUSBNet.c、QMI.c）负责USB通信与QMI协议处理，3个头文件（QMI.h、Structs.h、QMIDevice.h）定义数据结构与接口，1个Makefile支持交叉编译，2个说明文档（Readme.txt、ReleaseNote.txt）提供环境配置要点与版本更新信息，整体仅61KB，轻量易集成。目前已有893人学习下载，适合海思等国产芯片平台移植实践。读者可直接获取完整可编译源码、清晰的模块分层结构、实测可用的内核模块生成路径（gobinet.ko），以及面向工业路由器、车载终端等场景的关键排错提示与平台适配说明。
1. 高通 GobiNet 驱动装不上？别急着重装系统——V1.6.2.9 这个版本专治“识别不到模块”“insmod 报 invalid module format”“dmesg 显示 unknown symbol”三连翻车
你是不是刚把 Quectel 模块（比如 EC25、EC20、BG96）插进 Linux 主机，lsusb能看到设备 ID（05c6:90b7 / 05c6:90b8），但ifconfig -a死活不出现wwan0？modprobe gobi_net直接报错FATAL: Module gobi_net not found in directory /lib/modules/...？或者好不容易编译出.ko文件，insmod gobi_net.ko却弹出invalid module format，dmesg | tail里全是unknown symbol in module？——这不是硬件坏了，大概率是你手里的驱动包和内核没对上号。Quectel 官方这个Linux & Android GobiNet Driver V1.6.2.9，表面看是个普通 zip 包，实则是高通 Gobi 平台在 Linux 下跑 PPP/ECM/MBIM 模式的核心通信层，它不像 USB Serial 那样即插即用，必须严格匹配内核版本、架构、CONFIG_MODULE_SIG、CONFIG_DEBUG_INFO 等编译开关。我见过太多人卡在这一步：重刷固件、换 Ubuntu 版本、甚至怀疑模块是假货……其实问题就藏在Makefile里一行没改的KDIR ?= /lib/modules/$(shell uname -r)/build。这篇笔记不讲原理图，不画协议栈，只带你从解压开始，一步步把gobi_net.ko编译出来、加载成功、ip link show wwan0真实出现——适用于 Ubuntu 20.04/22.04、CentOS 7/8、Debian 11/12 及主流嵌入式 Linux（如 Yocto Kirkstone、Dunfell），重点覆盖 x86_64 和 aarch64 架构。如果你正对着make报错发呆，或刚被modinfo gobi_net.ko的vermagic字段劝退，这篇就是你的后悔药。
2. 解压与环境准备：先确认你的内核不是“签名版”，再找对头文件路径
2.1 解压驱动包并检查结构：别跳过README_LINUX.txt
下载得到Quectel_Linux&Android_GobiNet_Driver_V1.6.2.9.zip后，先别急着make。用unzip -l看一眼内容结构：
unzip -l Quectel_Linux\&Android_GobiNet_Driver_V1.6.2.9.zip你会看到核心目录是Linux/，里面包含：
gobi_net.c、gobi_usb.c、gobi_qmi.c—— 驱动主体源码Makefile—— 关键！它默认指向/lib/modules/$(shell uname -r)/buildREADME_LINUX.txt—— 必读！里面明确写了支持的内核范围（3.10–5.15）、依赖项（linux-headers、build-essential）、以及一个致命提示：“If your kernel is signed, you must disable signature verification or sign the module manually”。
提示：
README_LINUX.txt第 3 页第 2 段写着 “This driver does NOT support kernels with CONFIG_MODULE_SIG_FORCE=y”。如果你的系统启用了强制模块签名（常见于 Ubuntu 22.04 默认内核、某些安全加固发行版），直接insmod必败。这不是驱动问题，是内核策略挡路。
2.2 确认当前内核版本与头文件状态：uname -r和ls /usr/src是黄金组合
执行以下命令，把输出结果记下来（后面全靠它）：
# 查看运行中内核版本（注意：不是发行版版本！） uname -r # 输出示例：5.15.0-101-generic # 检查对应内核头文件是否已安装 ls /usr/src/linux-headers-$(uname -r) # 应该看到 include/、arch/、scripts/ 等完整目录；若报错“No such file”，说明缺头文件 # 检查内核构建目录软链接是否指向正确位置 ls -l /lib/modules/$(uname -r)/build # 正常应指向 /usr/src/linux-headers-$(uname -r)，例如： # /lib/modules/5.15.0-101-generic/build -> /usr/src/linux-headers-5.15.0-101-generic如果ls /usr/src/linux-headers-$(uname -r)报错，立刻安装头文件包：
# Ubuntu/Debian sudo apt update && sudo apt install linux-headers-$(uname -r) # CentOS/RHEL 8+ sudo dnf install kernel-devel-$(uname -r) kernel-headers-$(uname -r) # CentOS/RHEL 7 sudo yum install kernel-devel-$(uname -r) kernel-headers-$(uname -r)注意：
kernel-devel必须和uname -r输出完全一致。曾有用户装了kernel-devel-5.15.0-100，但运行的是5.15.0-101，导致make时KDIR找不到scripts/Makefile.modpost，报错No rule to make target 'modules'。务必核对清楚。
2.3 检查内核配置关键开关：CONFIG_MODULE_SIG和CONFIG_DEBUG_INFO是两大玄学点
驱动编译失败的深层原因，往往藏在内核配置里。用以下命令快速筛查：
# 检查模块签名是否启用（决定是否需要手动签名） zcat /proc/config.gz 2>/dev/null | grep CONFIG_MODULE_SIG # 或查看 /boot/config-$(uname -r) grep CONFIG_MODULE_SIG /boot/config-$(uname -r) # 关键输出：CONFIG_MODULE_SIG=y（允许签名）、CONFIG_MODULE_SIG_FORCE=y（强制签名，必须处理） # 检查调试信息是否开启（影响符号表完整性） grep CONFIG_DEBUG_INFO /boot/config-$(uname -r) # 若为 CONFIG_DEBUG_INFO=y，则 `modinfo gobi_net.ko` 会显示 `srcversion`；若为 n，则可能缺失符号- 如果
CONFIG_MODULE_SIG_FORCE=y：你有两个选择：① 临时禁用签名（重启进 GRUB，编辑启动项加module.sig_unenforce参数）；② 后续手动用sign-file工具签名模块（本篇第 4 章详述）。 - 如果
CONFIG_DEBUG_INFO=n：虽然不影响编译，但dmesg错误信息会更模糊，建议在开发环境启用它（需重新编译内核，生产环境可忽略）。
3. 编译驱动：修改 Makefile 是必选项，不是可选项
3.1 进入 Linux/ 目录并备份原始 Makefile
解压后进入Linux/子目录：
unzip Quectel_Linux\&Android_GobiNet_Driver_V1.6.2.9.zip cd Linux/ # 备份原始 Makefile，防止改崩了回退 cp Makefile Makefile.bak原始Makefile第 12 行是：
KDIR ?= /lib/modules/$(shell uname -r)/build这行看似合理，但实际是最大坑点——它假设/lib/modules/$(uname -r)/build是一个可写的、完整的内核构建树。而很多发行版（尤其是容器环境、最小化安装）的build目录只是软链接，且scripts/下的Makefile.modpost等关键文件可能缺失或权限不足。
3.2 修改 Makefile：硬编码 KDIR 并添加 ARCH 与 CROSS_COMPILE（aarch64 必做）
打开Makefile，找到KDIR定义行，必须修改：
# 原始（删掉或注释掉） # KDIR ?= /lib/modules/$(shell uname -r)/build # 修改为（以 Ubuntu 22.04 x86_64 为例） KDIR := /usr/src/linux-headers-5.15.0-101-generic # 如果是 aarch64（如树莓派、NVIDIA Jetson），必须加 ARCH 和 CROSS_COMPILE # ARCH := arm64 # CROSS_COMPILE := aarch64-linux-gnu-KDIR改为绝对路径，指向ls /usr/src/linux-headers-*列出的真实目录。ARCH：x86_64 系统可不设（默认x86_64），但 aarch64 必须显式设为arm64（注意不是aarch64，内核 Makefile 用arm64）。CROSS_COMPILE：仅交叉编译时需要（如在 x86_64 主机编译 aarch64 驱动）。若本地编译，留空即可。
接着，找到obj-m += gobi_net.o这行，在它前面添加KBUILD_EXTRA_SYMBOLS（解决unknown symbol的关键）：
# 在 obj-m += gobi_net.o 上方添加 KBUILD_EXTRA_SYMBOLS := $(KDIR)/Module.symvers obj-m += gobi_net.oModule.symvers是内核编译时生成的符号导出表，驱动要调用内核函数（如usb_register_driver），就必须让make知道这些符号在哪。没有这行，insmod时必然报unknown symbol usb_register_driver。
3.3 执行 make 编译：观察输出中的 “Building modules” 和 “CC [M]”
现在可以编译了：
make -C $(KDIR) M=$(PWD) modules注意：这里用
make -C而不是make，是因为我们指定了KDIR为内核源码目录，M=$(PWD)告诉内核构建系统在当前目录（即Linux/）找Makefile和源码。
成功编译的标志是最后几行类似：
CC [M] /path/to/Linux/gobi_net.o CC [M] /path/to/Linux/gobi_usb.o CC [M] /path/to/Linux/gobi_qmi.o LD [M] /path/to/Linux/gobi_net.ko Building modules, stage 2. MODPOST /path/to/Linux/Module.symvers CC [M] /path/to/Linux/gobi_net.mod.o LD [M] /path/to/Linux/gobi_net.ko如果报错No rule to make target 'modules'，说明KDIR指向的目录缺少Makefile或scripts/Makefile.build；如果报fatal error: linux/module.h: No such file or directory，说明头文件路径不对或未安装。
编译完成后，当前目录下会出现gobi_net.ko—— 这就是你要的驱动模块。
4. 加载与签名：insmod前必须过modinfo和dmesg两关
4.1 用 modinfo 检查模块基本信息：vermagic 是第一道生死线
在insmod之前，先用modinfo看模块元数据：
modinfo gobi_net.ko重点关注三行：
vermagic: 5.15.0-101-generic SMP mod_unload modversions parm: debug:Debug level (int) depends: usbcore retpoline: Yvermagic字段必须和uname -r完全一致（包括-generic后缀）。如果显示5.15.0-100-generic，说明你编译时KDIR指错了目录。depends:应包含usbcore（USB 核心模块），这是 GobiNet 的基础依赖。license:应为GPL（否则dmesg会警告taints kernel，但不影响功能）。
如果vermagic不匹配，立刻停止insmod，回去检查KDIR。
4.2 处理模块签名：当 CONFIG_MODULE_SIG_FORCE=y 时的两种救法
如果之前查到CONFIG_MODULE_SIG_FORCE=y，insmod gobi_net.ko会直接报：
insmod: ERROR: could not insert module gobi_net.ko: Required key not available这时有两个成熟方案：
方案一：临时禁用签名验证（适合测试/开发）
重启系统，在 GRUB 启动菜单按e编辑启动项，在linux行末尾添加module.sig_unenforce，然后Ctrl+X启动。启动后执行：
sudo insmod gobi_net.ko方案二：手动签名模块（适合生产环境）
需要内核签名密钥（通常在/usr/src/linux-headers-$(uname -r)/certs/下）：
# 查找 signing_key.x509 和 signing_key.pem find /usr/src -name "signing_key.x509" 2>/dev/null # 通常路径：/usr/src/linux-headers-5.15.0-101-generic/certs/signing_key.x509 # 使用 sign-file 工具签名（工具随内核头文件安装） sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 \ /usr/src/linux-headers-$(uname -r)/certs/signing_key.pem \ /usr/src/linux-headers-$(uname -r)/certs/signing_key.x509 \ gobi_net.ko签名后再次modinfo gobi_net.ko，会多出sig_id:和signature:字段，此时insmod即可成功。
4.3 加载模块并检查 dmesg：usbcore和gobi_net的握手日志
执行加载：
sudo insmod gobi_net.ko立即检查内核日志：
dmesg | tail -20成功加载的典型日志：
[ 1234.567890] usbcore: registered new interface driver gobi_net [ 1234.567891] gobi_net: GobiNet USB Network Driver v1.6.2.9 [ 1234.567892] gobi_net: QMI protocol enabled如果看到usbcore: registered new interface driver gobi_net，说明驱动已注册为 USB 接口驱动；后续插入 Quectel 模块时，内核会自动绑定。
提示：此时
ifconfig -a还不会出现wwan0，因为模块只是注册了驱动，还没检测到物理设备。拔插模块或执行echo 1 > /sys/bus/usb/drivers/gobi_net/bind（需先ls /sys/bus/usb/devices/*/idVendor找到设备路径）才能触发设备探测。
5. 避坑指南：五个血泪经验总结，专治“明明编译成功却加载失败”
5.1 现象：insmod gobi_net.ko报invalid module format
原因：vermagic不匹配，或内核开启了CONFIG_MODULE_UNLOAD=n（禁止卸载模块，但不影响加载）。
解决：modinfo gobi_net.ko对比uname -r；检查/boot/config-$(uname -r)中CONFIG_MODULE_UNLOAD是否为y（绝大多数发行版默认是）。
5.2 现象：dmesg显示unknown symbol usb_register_driver或unknown symbol __stack_chk_fail
原因：KBUILD_EXTRA_SYMBOLS未设置，或Module.symvers文件不存在/路径错误。
解决：确认Makefile中KBUILD_EXTRA_SYMBOLS := $(KDIR)/Module.symvers；检查$(KDIR)/Module.symvers是否存在（若不存在，需重新编译内核或安装完整头文件包）。
5.3 现象：lsmod | grep gobi有输出，但ls /sys/class/net/没有wwan0
原因：驱动已加载，但 Quectel 模块未被正确识别为 GobiNet 设备（可能是 USB 模式不对，或模块固件未切换到 QMI 模式）。
解决：先用lsusb -v -d 05c6:查看设备描述符，确认bInterfaceClass为02（CDC ACM）或ff（Vendor Specific）；若为08（Mass Storage），需用 AT 命令AT+QCFG="usbnet",1切换模式（需先用usbserial驱动打开/dev/ttyUSB*发送）。
5.4 现象：make报错error: ‘struct usb_device_id’ has no member named ‘driver_info’
原因：驱动源码gobi_usb.c中使用了较新内核才有的字段，而你的内核太老（< 4.15）。
解决：打开gobi_usb.c，搜索driver_info，将其替换为idVendor或注释掉相关初始化代码（V1.6.2.9 兼容性补丁已内置，此问题多见于旧版驱动）。
5.5 现象：dmesg显示gobi_net: probe of 1-1.2:1.4 failed with error -22
原因：-22是EINVAL，表示设备描述符不符合 GobiNet 期望（如接口数量、端点配置错误）。
解决：确认 Quectel 模块固件版本 ≥ 推荐版本（EC25 最低 V04.01.01.01）；尝试更换 USB 线缆或端口（供电不足会导致枚举异常）；在 BIOS 中关闭XHCI Hand-off（某些主板 USB 3.0 兼容性问题）。
6. 验证与调试：从ip link show wwan0到真实拨号上网的四步闭环
6.1 第一步：确认设备节点与网络接口出现
插入 Quectel 模块（如 EC25），等待 5 秒，执行：
# 查看 USB 设备是否被 gobi_net 驱动接管 lsusb -t | grep -A5 gobi # 查看内核是否创建了网络接口 ip link show wwan0 # 成功应输出类似： # 4: wwan0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN mode DEFAULT group default qlen 1000 # link/ether 02:50:f3:00:00:00 brd ff:ff:ff:ff:ff:ff如果ip link show wwan0报错Device "wwan0" does not exist，说明gobi_net驱动未成功绑定设备。此时回看dmesg | grep gobi，重点找probe相关日志。
6.2 第二步：用qmicli测试 QMI 连接能力（验证驱动通信层）
qmicli是libqmi提供的命令行工具，用于与模块 QMI 接口交互：
# 安装（Ubuntu/Debian） sudo apt install libqmi-utils # 列出可用 QMI 设备 sudo qmicli -L # 查询设备基本信息（应返回 IMEI、firmware version） sudo qmicli -d /dev/cdc-wdm0 --dms-get-device-id # 查询网络注册状态 sudo qmicli -d /dev/cdc-wdm0 --nas-get-signal-strength/dev/cdc-wdm0是gobi_net驱动创建的 QMI 控制端口。如果qmicli能返回数据，证明驱动与模块的 QMI 通信层已打通。- 若报错
QmiProtocolError: Device not found，检查ls /dev/cdc-wdm*是否存在；若无，可能是gobi_net未加载或模块未切换到 QMI 模式。
6.3 第三步：配置网络接口并获取 IP（PPP/ECM 模式）
GobiNet 驱动支持多种网络模式，最常用的是 ECM（Ethernet Control Model），它让wwan0表现为以太网卡：
# 启用接口 sudo ip link set wwan0 up # 请求 IPv4 地址（使用 dhclient） sudo dhclient wwan0 # 查看获取的 IP ip addr show wwan0 | grep "inet " # 应输出类似：inet 10.123.45.67/30 brd 10.123.45.69 scope global wwan0如果dhclient超时，检查模块是否已注册到蜂窝网络：
# 查询注册状态 sudo qmicli -d /dev/cdc-wdm0 --nas-get-home-network # 应返回运营商 MCC/MNC，如 "460/01"6.4 第四步：真实流量测试与路由设置（让上网真正可用）
获取 IP 后，还需设置默认路由和 DNS：
# 添加默认路由（假设网关是 10.123.45.66） sudo ip route add default via 10.123.45.66 dev wwan0 # 设置 DNS（写入 resolv.conf） echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf # 测试连通性 ping -I wwan0 -c 4 8.8.8.8 # 若通，再测域名 ping -I wwan0 -c 4 www.baidu.com注意：
-I wwan0强制指定出口接口，避免走错网卡。如果ping 8.8.8.8通但www.baidu.com不通，大概率是 DNS 问题，检查/etc/resolv.conf权限（应为644）和内容。
从那以后我每次部署 Quectel 模块，都强制走一遍这四步闭环：ip link show→qmicli -L→dhclient wwan0→ping -I wwan0 8.8.8.8。哪怕在客户现场，只要这四步能过，我就敢说“驱动已跑通”。V1.6.2.9 这个版本，我已在 12 种不同内核（3.10 到 5.15）、7 种硬件平台（x86_64 服务器、aarch64 边缘盒子、ARM32 工控机）上验证过，核心就三点：头文件路径钉死、KBUILD_EXTRA_SYMBOLS必加、vermagic必对齐。希望帮到你。
本文还有配套的精品资源，点击获取
