简介本资源是移远通信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能看到设备 ID05c6:90b7 / 05c6:90b8但ifconfig -a死活不出现wwan0modprobe gobi_net直接报错FATAL: Module gobi_net not found in directory /lib/modules/...或者好不容易编译出.ko文件insmod gobi_net.ko却弹出invalid module formatdmesg | 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_LinuxAndroid_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_FORCEy”。如果你的系统启用了强制模块签名常见于 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_SIGy允许签名、CONFIG_MODULE_SIG_FORCEy强制签名必须处理 # 检查调试信息是否开启影响符号表完整性 grep CONFIG_DEBUG_INFO /boot/config-$(uname -r) # 若为 CONFIG_DEBUG_INFOy则 modinfo gobi_net.ko 会显示 srcversion若为 n则可能缺失符号如果CONFIG_MODULE_SIG_FORCEy你有两个选择① 临时禁用签名重启进 GRUB编辑启动项加module.sig_unenforce参数② 后续手动用sign-file工具签名模块本篇第 4 章详述。如果CONFIG_DEBUG_INFOn虽然不影响编译但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_COMPILEaarch64 必做打开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-*列出的真实目录。ARCHx86_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:应包含usbcoreUSB 核心模块这是 GobiNet 的基础依赖。license:应为GPL否则dmesg会警告taints kernel但不影响功能。如果vermagic不匹配立刻停止insmod回去检查KDIR。4.2 处理模块签名当 CONFIG_MODULE_SIG_FORCEy 时的两种救法如果之前查到CONFIG_MODULE_SIG_FORCEyinsmod gobi_net.ko会直接报insmod: ERROR: could not insert module gobi_net.ko: Required key not available这时有两个成熟方案方案一临时禁用签名验证适合测试/开发重启系统在 GRUB 启动菜单按e编辑启动项在linux行末尾添加module.sig_unenforce然后CtrlX启动。启动后执行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 加载模块并检查 dmesgusbcore和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_UNLOADn禁止卸载模块但不影响加载。解决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为02CDC ACM或ffVendor Specific若为08Mass Storage需用 AT 命令ATQCFGusbnet,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 第三步配置网络接口并获取 IPPPP/ECM 模式GobiNet 驱动支持多种网络模式最常用的是 ECMEthernet 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/016.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必对齐。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/17 7:49:20 · 阅读 1.2k Quectel模块GobiNet驱动编译加载全指南：解决unknown symbol与invalid module format
简介本资源是移远通信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能看到设备 ID05c6:90b7 / 05c6:90b8但ifconfig -a死活不出现wwan0modprobe gobi_net直接报错FATAL: Module gobi_net not found in directory /lib/modules/...或者好不容易编译出.ko文件insmod gobi_net.ko却弹出invalid module formatdmesg | 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_LinuxAndroid_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_FORCEy”。如果你的系统启用了强制模块签名常见于 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_SIGy允许签名、CONFIG_MODULE_SIG_FORCEy强制签名必须处理 # 检查调试信息是否开启影响符号表完整性 grep CONFIG_DEBUG_INFO /boot/config-$(uname -r) # 若为 CONFIG_DEBUG_INFOy则 modinfo gobi_net.ko 会显示 srcversion若为 n则可能缺失符号如果CONFIG_MODULE_SIG_FORCEy你有两个选择① 临时禁用签名重启进 GRUB编辑启动项加module.sig_unenforce参数② 后续手动用sign-file工具签名模块本篇第 4 章详述。如果CONFIG_DEBUG_INFOn虽然不影响编译但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_COMPILEaarch64 必做打开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-*列出的真实目录。ARCHx86_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:应包含usbcoreUSB 核心模块这是 GobiNet 的基础依赖。license:应为GPL否则dmesg会警告taints kernel但不影响功能。如果vermagic不匹配立刻停止insmod回去检查KDIR。4.2 处理模块签名当 CONFIG_MODULE_SIG_FORCEy 时的两种救法如果之前查到CONFIG_MODULE_SIG_FORCEyinsmod gobi_net.ko会直接报insmod: ERROR: could not insert module gobi_net.ko: Required key not available这时有两个成熟方案方案一临时禁用签名验证适合测试/开发重启系统在 GRUB 启动菜单按e编辑启动项在linux行末尾添加module.sig_unenforce然后CtrlX启动。启动后执行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 加载模块并检查 dmesgusbcore和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_UNLOADn禁止卸载模块但不影响加载。解决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为02CDC ACM或ffVendor Specific若为08Mass Storage需用 AT 命令ATQCFGusbnet,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 第三步配置网络接口并获取 IPPPP/ECM 模式GobiNet 驱动支持多种网络模式最常用的是 ECMEthernet 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/016.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必对齐。希望帮到你。本文还有配套的精品资源点击获取