# RM520N-GL 5G 模块在 iStoreOS(虚拟化直通)下 MBIM 拨号成功路线

> 日期：2026-08-19
> 环境：宿主飞牛(Fnos) 将移远 RM520N-GL 5G 模块通过 PCIe(vfio-pci) 直通给 iStoreOS 虚拟机
> 目标：让 iStoreOS 能够拨号上网，5G 模块作为宽带备用(wan2)
> 状态：✅ 5G 拨号成功、稳定上网、已固化开机自启

---

## 一、最终成果一句话

在 iStoreOS 里，用 **移远官方 Quectel-CM V1.6.8（musl 静态编译）** 通过 **MBIM 模式** 拨号，模块成功拿到运营商内网 IP 并上网（`ping 223.5.5.5` 通）。

**关键结论：RM520N-GL 在 PCIe 直通 + pcie_mhi 驱动下，QMI 模式是死路（模块不响应 QMI），必须用 MBIM 模式。**

---

## 二、环境与拓扑

| 项 | 值 |
|---|---|
| 5G 模块 | 移远 RM520N-GL，固件 `RM520NGLAAR03A04M4G`，IMEI 868371050275649 |
| 模块宿主位置 | 飞牛 `06:00.0 17cb:0308` |
| 直通方式 | vfio-pci 直通给 istoreos 虚拟机 |
| 虚拟机内位置 | `00:0a.0 Qualcomm SDX62` |
| iStoreOS IP | 192.168.110.135 |
| iStoreOS 登录 | root / SSH 已开启 |
| 数据通道 | PCIe/RMNET + qmap vlan（MBIM 模式走 `rmnet_mhi0.1`） |
| AT 通道 | `/dev/mhi_DUN` |

### 关键驱动
- **pcie_mhi 驱动** V1.3.8（移远私有 MHI 驱动）
- 加载参数：`mhi_mbim_enabled=1`（**MBIM 模式**）
- MBIM 模式设备节点：`/dev/mhi_MBIM`（QMI 模式是 `/dev/mhi_QMI0`）

---

## 三、为什么是这样（决策记录）

### 走过的弯路
1. **ModemManager 识别不了**：移远 pcie_mhi 驱动把控制通道暴露为私有 `/dev/mhi_QMI0`，不是标准 cdc-wdm，mmcli 扫不到。
2. **luci-app-modem 界面管不到**：修好 `at_port=/dev/mhi_DUN` + `manufacturer=quectel` 后，界面能读到信息但不拨号。
3. **QMI 拨号失败（V1.6.7）**：系统自带 quectel-CM 1.6.7 只支持 ECM 分支，报 `unsupport software_interface 1`。
4. **升级 V1.6.8 仍失败（QMI）**：V1.6.8 支持 QMI 分支，但 **模块对 QMI 请求从不响应**——手动发 QMI SYNC 能写入但读不到任何响应；换 `qmap_mode`、软重启都不行。判定是 **RM520N-GL + pcie_mhi v1.3.8 的 QMI 硬伤**。
5. **✅ 切 MBIM 成功**：驱动 `mhi_mbim_enabled=1` → `/dev/mhi_MBIM` 出现 → quectel-CM 直接拨号成功。完全复现移远官方日志 `pcie_mhi_mbim.txt` 的流程。

### 核心经验
- **RM520N-GL 在 PCIe/MHI 下能用 MBIM，QMI 通道是死的**（至少 pcie_mhi v1.3.8 + 此固件下如此）。
- MBIM 模式**不需要 proxy**，`quectel-CM -s <apn>` 直接拨号即可。
- iStoreOS 是 **musl libc**，必须用 **musl-gcc 静态编译** quectel-CM（glibc 静态编译的 qmi-proxy 在 musl 上闪退/卡死）。

---

## 四、完整复现步骤

### 步骤 1：确认模块拓扑与直通
```bash
# 宿主(飞牛)
lspci | grep 17cb          # 找到 06:00.0 17cb:0308
# 直通给 istoreos VM 后，guest 内
lspci | grep -i qualcomm   # 00:0a.0 Qualcomm SDX62
ls /sys/bus/mhi_q/devices/ # 应看到 0308_00.00.0a_DIAG/DUN/EFS/QMI0 等
ls /dev/mhi_DUN /dev/mhi_QMI0   # AT 通道在
```

### 步骤 2：切到 MBIM 模式（关键！）
```bash
# 备份当前配置
cp /etc/modules.d/90-pcie_mhi /etc/modules.d/90-pcie_mhi.bak
# 卸载驱动
rmmod pcie_mhi
# 以 MBIM 模式重新加载
insmod /lib/modules/$(uname -r)/pcie_mhi.ko mhi_mbim_enabled=1
# 验证：/dev/mhi_MBIM 出现，/dev/mhi_QMI0 消失
ls /dev/mhi_MBIM
# 固化（重启自动 MBIM）
echo "pcie_mhi mhi_mbim_enabled=1" > /etc/modules.d/90-pcie_mhi
```

### 步骤 3：部署 musl 版 quectel-CM V1.6.8
```bash
# 二进制在 文件/binaries/quectel-CM（musl 静态编译 V1.6.8）
# 备份旧版 V1.6.7
cp /usr/bin/quectel-CM /usr/bin/quectel-CM.bak-20260819-167
# 替换
cp quectel-CM /usr/bin/quectel-CM
chmod 755 /usr/bin/quectel-CM
/usr/bin/quectel-CM 2>&1 | head -1   # 应显示 QConnectManager_Linux_V1.6.8
```

### 步骤 4：MBIM 拨号（核心命令）
```bash
# 直接拨号，不需要 proxy
/usr/bin/quectel-CM -s wonet -f /tmp/quectel_cm.log
# 注意：MBIM 模式不要加 -i rmnet_mhi0（会异常）；APN 用 wonet（联通卡）
```
成功标志：日志出现 `ActivationState Deactivated -> Activated`，`rmnet_mhi0.1` 拿到 `inet` IP，`ping -I rmnet_mhi0.1 223.5.5.5` 通。

### 步骤 5：开机自启
```bash
# 使用 文件/configs/init.d_modem5g
cp 文件/configs/init.d_modem5g /etc/init.d/modem5g
chmod 755 /etc/init.d/modem5g
/etc/init.d/modem5g enable     # 建立 S95modem5g
# 手动测试
/etc/init.d/modem5g start
/etc/init.d/modem5g stop
```

### 步骤 6：开机绑定修复（已确认非必需，默认跳过）
```bash
# 说明 (2026-08-20 更新):
# 原生流程即可自启拨号: 90-pcie_mhi(驱动) -> S95modem5g(拨号) -> S96wan5g-route(策略路由)
# rc.local **不需要**手动 bind mhi_q。
# 教训: 手动强绑`echo 0000:00:0a.0 > /sys/bus/pci/drivers/mhi_q/bind`可能抢设备致 SYS_ERR。
# 若模块失联(无/dev/mhi_DUN)，先断电重启飞牛，仍无效才可手动 bind 临时唤醒。
```

---

## 五、已验证的关键事实

### 拨号成功日志（节选，完整见 文件/logs/）
```
[08-19_13:00:xx] Quectel_QConnectManager_Linux_V1.6.8
[08-19_13:00:xx] Modem works in MBIM mode
[08-19_13:00:xx] cdc_wdm_fd = 8                    # 成功打开 /dev/mhi_MBIM
[08-19_13:00:xx] mbim_device_caps_query()
[08-19_13:00:xx] DeviceId:     868371050275649
[08-19_13:00:xx] FirmwareInfo: RM520NGLAAR03A04M4G
[08-19_13:00:xx] mbim_subscriber_status_query()
[08-19_13:00:xx] SimIccId:     89860125801671811893
[08-19_13:00:xx] RegisterState Unknown -> Home     # 已注册
[08-19_13:00:xx] PacketServiceState Unknown -> Attached
[08-19_13:00:xx] mbim_set_connect(onoff=1, sessionID=0)
[08-19_13:00:xx] ActivationState Deactivated -> Activated   # ← 拨号成功!
[08-19_13:00:xx] mbim_ip_config(sessionID=0)
[08-19_13:00:xx] IPv4 = 10.98.xxx.xxx/30            # 拿到内网 IP
```
接口验证：
```
ip addr show rmnet_mhi0.1   # inet 10.98.xxx.xxx/30 ... state UP
ping -c 3 -W 2 -I rmnet_mhi0.1 223.5.5.5   # 2/2 received
```

### 界面管理（MBIM 下 luci 正常）
```
sh /usr/share/modem/modem_info.sh /dev/mhi_DUN quectel quectel 1
# 返回 manufacturer=Quectel, temperature, SIM ready, IMEI/IMSI 正常
```
luci 界面（网络→Modem）可作**状态监控**；但 luci 自动拨号(AT激活)不适用于 PCIe MBIM（数据通道由 quectel-CM 控制）。

---

## 六、目录文件清单

```
RM520N-5G-成功路线/
├── 文档/
│   └── RM520N-MBIM拨号成功路线.md        # 本文档
├── 文件/
│   ├── binaries/                         # musl 静态编译的 V1.6.8 二进制
│   │   ├── quectel-CM                    # ★ 拨号主程序（部署到 /usr/bin）
│   │   ├── quectel-qmi-proxy             # (备用，QMI 模式才需要)
│   │   ├── quectel-mbim-proxy
│   │   └── quectel-atc-proxy
│   ├── source/                           # V1.6.8 完整源码(21 .c + 头文件 + PDF文档)
│   │   └── Quectel_QConnectManager_Linux_User_Guide_V1.0.pdf
│   ├── configs/                          # istoreos 配置文件(可直接复用)
│   │   ├── modem_config.txt              # /etc/config/modem
│   │   ├── 90-pcie_mhi.txt               # /etc/modules.d/90-pcie_mhi (mhi_mbim_enabled=1)
│   │   ├── rc.local                      # /etc/rc.local (默认无需绑定, 见故障排查文档)
│   │   └── init.d_modem5g                # /etc/init.d/modem5g (开机自启拨号)
│   └── logs/
│       ├── quectel_cm_success_log.txt    # 本次成功拨号日志(真实)
│       └── 官方参考_pcie_mhi_mbim.txt    # 移远官方 MBIM 成功日志(参考)
```

---

## 七、编译说明（如需重编）

iStoreOS 是 musl libc，必须 musl 静态编译：

```bash
# 在 WSL(Ubuntu) 或其他 x86_64 glibc 环境
sudo apt install musl-tools
# musl-gcc 需要 linux 头文件，复制到 musl include
sudo cp -r /usr/include/linux /usr/include/x86_64-linux-musl/
sudo cp -r /usr/include/x86_64-linux-gnu/asm /usr/include/x86_64-linux-musl/
sudo cp -r /usr/include/asm-generic /usr/include/x86_64-linux-musl/

# 编译 quectel-CM（V1.6.8，QMI 分支）
cd 文件/source
musl-gcc -O1 -static -pthread -o quectel-CM \
  QmiWwanCM.c GobiNetCM.c main.c QCQMUX.c QMIThread.c util.c \
  qmap_bridge_mode.c mbim-cm.c device.c atc.c atchannel.c at_tok.c udhcpc.c
```

---

## 八、遗留 / 建议

1. **wan2 备份（最终目标）**：5G 已能上网，还差把 `rmnet_mhi0.1` 配成 wan2 备份（wan1 宽带优先）。推荐 mwan3 或 OpenWrt 策略路由。
2. **luci 界面**：目前可作状态监控。如需界面控制拨号(启停 modem5g)，可在 luci-app-modem 加轻量入口。
3. **QMI 死路提醒**：不要再尝试 QMI 拨号，此模块此驱动下不通，MBIM 是正解。
4. **APN**：本次用 `wonet`(联通)。换卡需改 `/etc/init.d/modem5g` 里的 `-s` 参数。