高通X105 5G-Advanced模组实战(1): Linux驱动移植与USB枚举的踩坑经验

本文基于实际项目经验详细记录高通X105SDX755G-Advanced模组在Linux系统下的驱动移植全流程。不同于X62平台X105引入了MHI新架构USB枚举顺序有变化PID也有更新笔者在项目中踩了7个坑才彻底跑通特此记录供同行参考。一、高通X105 5G-A Modem-RF系统新架构高通X105是高通2026年MWC发布的最新R19-ready 5G-A平台相比X62 5G模组硬件架构有较大变化驱动也完全不同图1X105 5G-Advanced Modem-RF系统架构图X105相比X62的关键架构升级特性X62X105对驱动的影响工艺4nm4nm基带6nm RF新增RF控制通道峰值速率4.4Gbps/900Mbps14.8Gbps/4.2Gbps需要PCIe/MHI高速通道USB接口USB 3.1USB 3.2 Gen2 MHIMHI协议栈是新坑PCIe可选PCIe Gen3 x2 标配需要MHI Bus驱动数据通道QMI/PPP/GobiNetMHI net qmi_wwanGobiNet彻底废弃AI处理器无第五代AI处理器新增AI通道InterfaceVID/PID05c6:90xx05c6:9078/9079/907a老驱动认不出新PID实战提醒千万别直接用X62的驱动配置套X105PID变了Interface分配也变了直接用会出现lsusb能看到但没ttyUSB的问题。二、Linux USB复合设备枚举架构X105枚举为USB复合设备Interface分配相比老平台有变化架构图如下图2X105 USB复合设备枚举架构图X105的USB Interface分配笔者实测Interface号类型驱动设备节点备注0DIAGoptionttyUSB0诊断口1ATCoptionttyUSB1AT命令口主用2NMEAoptionttyUSB2GNSS定位数据3ModemoptionttyUSB3PPP备用4QMI/MBIMcdc_mbim/qmi_wwanwdm0 wwan0控制数据5MHI Datamhi_netmhi0_net0高速数据口10Gbps6DBGoptionttyUSB4调试日志口新增7AI Channelqcom_ai/dev/qai0AI通道新增踩坑点#1PID不在option驱动列表中内核5.15及更早版本的option_ids[]里没有X105的PID0x9078直接插上只能看到Qualcomm, Inc.但没有任何ttyUSB设备。三、驱动移植全流程Kernel 5.15实测3.1 内核配置make menuconfig必须启用的配置项笔者一开始漏了CONFIG_MHI_BUS调了两天# 基础USB SerialCONFIG_USB_SERIALyCONFIG_USB_SERIAL_OPTIONyCONFIG_USB_SERIAL_WWANyCONFIG_USB_SERIAL_QCAUXy# 新增X105需要qcauxCONFIG_USB_SERIAL_QCOMQCy# 新增高通QC串口# MHI子系统关键X105必备CONFIG_MHI_BUSyCONFIG_MHI_BUS_PCI_GENERICyCONFIG_MHI_NETy# MHI网络驱动CONFIG_WWANyCONFIG_WWAN_QCOM_MHIy# 高通MHI WWAN驱动# QMI/MBIM网络CONFIG_USB_NET_QMI_WWANyCONFIG_USB_NET_CDC_MBIMyCONFIG_USB_USBNETyCONFIG_USB_NET_CDCETHERy# PCIe如果用PCIe接口CONFIG_PCIyCONFIG_PCIEPORTBUSy3.2 给option驱动添加X105 PID修改drivers/usb/serial/option.c在option_ids[]数组中添加staticconststructusb_device_idoption_ids[]{// ... 原有设备保持不变 ...// 高通X105 (SDX75) 新增{USB_DEVICE(0x05C6,0x9078)},// X105 default composition{USB_DEVICE(0x05C6,0x9079)},// X105 MBIM composition{USB_DEVICE(0x05C6,0x907A)},// X105 PCIeUSB composition{USB_DEVICE_INTERFACE_CLASS(0x05C6,0x9078,0xFF)},{}/* Terminating entry */};MODULE_DEVICE_TABLE(usb,option_ids);另外还需要在option_probe()中保留QMI和MHI接口不被option接管否则会冲突staticintoption_probe(structusb_serial*serial,conststructusb_device_id*id){// ... 原有代码 .../* X105: skip QMI/MBIM and MHI data interfaces */if(serial-dev-descriptor.idVendorcpu_to_le16(0x05C6)serial-dev-descriptor.idProductcpu_to_le16(0x9078)){if(iface_desc-bInterfaceNumber4||// QMI/MBIMiface_desc-bInterfaceNumber5||// MHI dataiface_desc-bInterfaceNumber7){// AI channelreturn-ENODEV;}}// ...}踩坑点#2option驱动劫持了QMI接口如果不跳过interface 4option会把QMI口也当成串口导致cdc_mbim/qmi_wwan无法绑定表现为没有wdm0设备QMI拨号失败。3.3 动态添加ID不想重编内核的临时方案如果不想编译内核可以启动后通过sysfs动态添加# 先看模组的PIDlsusb# Bus 002 Device 003: ID 05c6:9078 Qualcomm, Inc.# 添加到option驱动echo05c69078/sys/bus/usb-serial/drivers/option1/new_id# 添加到qcauxecho05c69078/sys/bus/usb-serial/drivers/qcaux/new_id# 等2秒再看设备sleep2ls/dev/ttyUSB*踩坑点#3添加new_id后仍然没有ttyUSBx原因是模组可能启动在USB模式但需要先发送AT$QCPWRDN或ATCFUN1才完整枚举。如果是刚上电需要等待15~20秒让模组内部启动完成期间dmesg会有多次断开重连。四、驱动移植完整调试流程含真实dmesg日志分析下面是笔者项目中真实的调试流程图包含每一步的验证命令和常见失败现象看不到能看到无有数量不对是无响应不是是OK无有模组上电等待20秒模组启动lsusb能看到设备?检查VBAT供电/USB线/dmesg报错dmesg看枚举日志有ttyUSB创建?检查PID是否加入option_ids重新加载option驱动或添加new_idls /dev/ttyUSB* 确认数量有4到5个ttyUSB?检查option_probe白名单/黑名单microcom打开ttyUSB1发送AT测试返回OK?检查波特率/串口是否被占用/RTS引脚AT口是ttyUSB1?逐个试ttyUSB0-4检查模组固件/复位模组检查wwan/mhi网卡ip link有wwan0?检查MHI/MBIM/QMI驱动是否加载modprobe mhi_wwan ctrl驱动移植成功图3X105驱动移植与USB枚举调试流程图4.1 正常枚举的dmesg参考成功案例以下是笔者平台上正常枚举的dmesg对比自己的日志看卡在哪一步[ 123.456789] usb 2-1: new SuperSpeed USB device number 3 using xhci_hcd [ 123.483210] usb 2-1: New USB device found, idVendor05c6, idProduct0x9078, bcdDevice 5.10 [ 123.483234] usb 2-1: New USB device strings: Mfr1, Product2, SerialNumber3 [ 123.483240] usb 2-1: Product: Qualcomm X105 5G Modem [ 123.483245] usb 2-1: Manufacturer: Qualcomm, Incorporated [ 123.483249] usb 2-1: SerialNumber: 0123456789ABCDEF [ 123.501234] option 2-1:1.0: Qualcomm USB modem converter detected [ 123.501456] usb 2-1: GSM modem (1-port) converter now attached to ttyUSB0 [ 123.503456] option 2-1:1.1: Qualcomm USB modem converter detected [ 123.503678] usb 2-1: GSM modem (1-port) converter now attached to ttyUSB1 [ 123.505678] option 2-1:1.2: Qualcomm USB modem converter detected [ 123.505890] usb 2-1: GSM modem (1-port) converter now attached to ttyUSB2 [ 123.507890] option 2-1:1.3: Qualcomm USB modem converter detected [ 123.508123] usb 2-1: GSM modem (1-port) converter now attached to ttyUSB3 [ 123.510123] cdc_mbim 2-1:1.4: setting rx_max 16384 [ 123.512345] cdc_mbim 2-1:1.4: cdc-wdm0: USB WDM device [ 123.514567] cdc_mbim 2-1:1.4 wwan0: register cdc_mbim at usb-xhci-hcd.2.auto-1, CDC MBIM, xx:xx:xx:xx:xx:xx [ 123.523456] mhi_net 2-1:1.5: MHI net device mhi0_net0 registered [ 123.525678] option 2-1:1.6: Qualcomm USB modem converter detected [ 123.525890] usb 2-1: GSM modem (1-port) converter now attached to ttyUSB44.2 常见错误日志分析错误场景Aoption驱动加载但只出3个ttyUSB缺ttyUSB4# 原因内核版本老option驱动对新interface数量支持不足 # 解决检查option.c里是否有USB_INTERFACE_PROBE_INFO限制错误场景Bcdc_mbim报错probe failed[ 123.567890] cdc_mbim 2-1:1.4: probing failed, error -16 # 原因option驱动已经把interface 4抢走了 # 解决在option_probe()里加iface4返回-ENODEV错误场景CMHI超时无法ready[ 130.123456] mhi mhi0: Wait for PM state to transition to M0 failed [ 130.123457] mhi mhi0: MHI NOT ready! # 原因USB3信号质量差/供电不足 # 解决换短USB线加粗VBAT和VBUS电源线量测VBUS纹波100mV踩坑点#4USB3.0信号完整性问题X105是USB 3.2 Gen210Gbps对走线阻抗要求很高。笔者第一次用普通飞线连接MHI始终无法进入M0状态降为USB2也只能到High-Speed。后来改用阻抗控制的PCB板问题解决。调试阶段可以强制模组工作在USB2模式排除信号问题ATQUSBCFGusb2,1 // 强制USB2模式调试 ATCFUN1,1 // 重启生效五、AT串口通信验证驱动枚举成功后第一件事是验证AT口能正常通信这里也有坑5.1 打开AT口# 安装minicom或microcomapt-getinstallminicom-y# 打开ttyUSB1X105的AT口通常是ttyUSB1但最好逐个试microcom-s115200/dev/ttyUSB1# 或 minicom -D /dev/ttyUSB1 -b 115200打开后输入AT正常应该返回AT OK踩坑点#5AT口有输出但输入AT没反应这是硬件流控问题X105的AT口默认开启RTS/CTS硬件流控如果你的串口线没接RTS/CTS引脚就只能看到开机日志但发不了AT。临时解决# 方法1: minicom里关闭硬件流控 (CtrlA O → Serial port setup → F)# 方法2: 用stty关闭流控stty-F/dev/ttyUSB1-crtscts永久解决需要AT命令关闭硬件流控ATIFC0,0 // 关闭流控重启生效 ATCFUN1,15.2 基础信息查询命令ATI // 查型号应该返回Qualcomm X105 ATCGMR // 查固件版本 ATCGSN // 查IMEI ATCCID // 查SIM卡CCID ATCPIN? // 查SIM状态应返回CPIN: READY ATCFUN? // 查射频功能应返回CFUN: 1如果ATCPIN?返回CPIN: NOT READY检查SIM卡是否插反SIM_VDD是否有电1.8V或3VSIM_IO/SIM_CLK波形是否正常SIM卡是否损坏六、高速MHI数据通路验证X105最核心的升级是MHI数据通道比传统QMI快5倍以上这也是最容易出问题的地方图4X105 MHI/PCIe高速数据通路架构图6.1 验证MHI设备是否ready# 查看MHI设备状态cat/sys/bus/mhi/devices/mhi0/status# 应输出: M0 (ready状态)# 查看MHI网络接口iplinkshow# 应看到: mhi0_net0: BROADCAST,MULTICAST ...# 查看MHI通道ls/sys/bus/mhi/devices/mhi0/channels/# 应看到多个channel包括DIAG、AT、DATA0~DATA3等6.2 MHI常见问题问题/sys/bus/mhi下没有设备检查CONFIG_MHI_BUS和CONFIG_MHI_NET是否编入内核或模块手动加载模块modprobe mhi_net mhi_wwan_ctrl问题mhi0状态是SYS_ERR或DISABLE通常是模组固件异常或USB连接不稳定复位模组echo0/sys/bus/usb/devices/2-1/authorizedsleep2echo1/sys/bus/usb/devices/2-1/authorized踩坑点#6MHI通道ready但ping不通MHI网卡加载成功只是通道通了还需要通过QMI/MBIM拨号配置IP。MHI本身只是二层传输通道不是配置完就自动能上网的这点很多人搞错。拨号方法在下一篇文章详细讲。问题PCIe模式识别不到MHIX105支持PCIe Gen3 x2直连速度比USB更快但需要模组固件配置为PCIe模式ATQPCIECFGpcie_en,1 // 使能PCIe ATQPOWD1 // 重启主机侧需要加载mhi_pci_generic驱动lspci应看到Qualcomm device。七、驱动移植Checklist交付前必查最后总结一个交付前的检查清单笔者就是因为漏了#4项导致客户验收卡了一周lsusb能看到05c6:9078设备/dev/下有ttyUSB0~ttyUSB4共5个串口ttyUSB1发AT能返回OK波特率115200ATCPIN?返回READYSIM卡识别正常有wwan0和mhi0_net0两个网络接口/dev/cdc-wdm0设备存在QMI/MBIM控制大流量传输1小时无断连dd if/dev/zero of/dev/tcp/$host/$port bs1M模组休眠唤醒正常echo mem /sys/power/state后唤醒ttyUSB不丢dmesg无连续报错dmesg | grep -i error无异常八、总结本文是X105 Linux驱动移植的实战记录核心踩坑点总结PID变更新PID 0x9078必须加入option_ids否则无ttyUSB接口冲突option必须跳过QMI/MHI/AI接口否则网络驱动无法绑定MHI新驱动必须启用CONFIG_MHI_BUS系列配置这是老平台没有的USB3信号10Gbps对走线要求高飞线不行请强制USB2模式调试硬件流控AT口默认开RTS/CTS飞线调试需临时关闭MHI≠自动上网MHI只是数据通道仍需QMI拨号配置IP耐心等待X105上电到完整枚举需要15~20秒期间多次重连是正常的驱动通了只是第一步下一篇《高通X105 5G-Advanced模组的多PDN拨号与网络切片配置》将讲解如何配置QMI拨号、多个PDN同时上网、网络切片URSP规则配置等实战内容包括如何做到工业控制走URLLC切片、视频走eMBB切片、语音走IMS切片同时工作。欢迎在评论区交流驱动移植中遇到的问题我会一一回复