6. 常见错误解析

6.1. Ubuntu环境下安装驱动时报错

Ubuntu 驱动安装失败并提示 DKMS 记录缺失

Ubuntu系统驱动安装过程中出现下面错误信息：
```
Error! The module/version combo: xh2_driver-0.3.0:added is not located in the DKMS tree.
```
原因：

系统中残留了旧版本驱动或 DKMS 缓存，导致当前驱动版本无法正确注册。

解决方法：

请按以下步骤卸载旧驱动并清除 DKMS 记录，再重新安装驱动：
```
sudo ./houmo_drv_<target_hw>_<release>__${distro}_$arch.run unstall all
sudo dkms remove xh2_driver/<release>
sudo ./houmo_drv_<target_hw>_<release>__${distro}_$arch.run install all --path <PATH>
```
其中：
- <target_hw> 表示后摩芯片类型。
- <release> 表示系统软件包版本号。
- ${distro} 表示ubuntu2004或ubuntu2404。
- $arch 表示x86_64或aarch64。
- PATH 应替换为驱动安装路径。如果不指定 --path <PATH>，则驱动默认安装在 /usr/local/houmo-sdk 目录下。
Ubuntu 驱动安装失败并提示 pci_alloc_irq_vectors failed

Ubuntu系统驱动安装过程中，dmesg 报错 pci_alloc_irq_vectors failed -28。

原因1：

后摩设备已经下线，但内核未及时更新 PCI 设备信息，导致驱动在分配中断向量时失败。

判断方法：

检查后摩设备状态：
```
lspci -s BB:DD.F -vvv
```
其中，BB:DD.F 为后摩设备PCIe BDF信息。如果返回下面信息，说明后摩设备信息未更新。
```
03:00.0 Memory controller: Device 1f6b:0c00 (rev ff) (prog-if ff)
        !!! Unknown header type 7f
        Kernel modules: xh2a_drv
```
解决方法：

执行下面步骤：
1. 卸载驱动。
2. 重新扫描后摩设备，指令示例如下：
echo 1 | sudo tee /sys/bus/pci/devices/<pcie_bdf>/remove echo 1 | sudo tee /sys/bus/pci/rescan
其中，<pcie_bdf> 为上级PCI设备的BDF，如 0000\:00\:07.0。
1. 重启主机。
原因2：

若上述原因已排除，但问题仍然存在，则可能是当前主机配置不支持分配多个MSI中断，请检查主机BIOS设置。

解决方法：
- X86_64平台：
  
  检查BIOS/UEFI 配置，确保平台 IOMMU 功能已启用。不同厂商命名可能为 VT-d、AMD VT、IO Virtualization 或 IOMMU等名称呈现。
  
  常见平台配置示例：
  - 部分海光平台主机：IOMMU 的配置项位于 Chipset -> NBIO -> IOMMU，请将其设置为启用。
  - 另一类海光平台主机：IOMMU的配置可能位于 Hygon CBS 菜单下，请确认相关选项已启用。
  - AMD和海光处理器：可通过检查系统中是否存在 ACPI IVRS 表来辅助判断 IOMMU 是否启用：
    ls /sys/firmware/acpi/tables/IVRS
    若该文件存在，通常表示 BIOS 中已正确开启 IOMMU；若不存在，则可能未在 BIOS 中启用 IOMMU。
  - 百敖通用BIOS：在 BIOS 菜单中查找 IO Virtualization 或 IOV Support 相关选项，将该选项设置为启用。
  - 百敖开天专用BIOS：将附件拷贝到目标主机，解压附件后进入目录，使用root权限执行下面命令：
    ./mfgdone.sh -clr
    重启系统，按 F1 进BIOS Setup，进入高级菜单，按 Ctr+Z 调出 CRB 菜单，设置 IOV Support 选项为启用。
- ARM平台：
  
  请根据实际平台确认GIC/ITS或中断重映射功能已启用。

Ubuntu 22.04 驱动安装失败并提示 DKMS 编译失败

在Ubuntu 22.04 x86_64平台上安装驱动过程中，可能出现下面错误信息：

ERROR (dkms apport): binary package for xh2_driver: v1.1.0 not found
Error! Bad return status for module build on kernel: 6.8.0-101-generic (x86_64)
Consult /var/lib/dkms/xh2 driver/v1.1.0/build/make.logformore information.

原因：

当前系统缺少与内核版本匹配的 GCC 编译器。
驱动模块通过 DKMS 编译时，需要使用系统默认 GCC 版本与内核编译器版本一致，否则会导致编译失败。

解决方法：

安装 GCC 12（确保与内核版本兼容）：
```
sudo apt update
sudo apt install gcc-12 g++-12
```
验证GCC版本：
```
gcc --version
```

将 GCC 12设置为默认编译器：

sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 100
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-12 100
sudo update-alternatives --config gcc
sudo update-alternatives --config g++

安装驱动。

6.2. Windows环境下卸载驱动时报错

Windows 卸载驱动失败并提示 remove driver fail

Windows环境下卸载驱动过程中出现下面错误信息：
```
checking Xh2aHostDriver with class Houmo AI Device
removing 1/1: oem3.inf
remove driver fail, error: 5
```
原因：

未使用管理员身份运行指令。

解决方法：

使用管理员身份运行命令提示符窗口。
Windows远程桌面安装驱动后设备识别异常

在 Windows 系统中，如果通过远程桌面方式安装驱动，例如使用 Windows Remote Desktop或其他第三方远程控制软件，即使驱动显示安装成功，后摩设备仍可能无法正常识别，如下图所示：

图 6.1 Windows环境下设备显示异常

解决方法：

请使用本地物理登录方式安装驱动和管理后摩设备，避免通过远程桌面连接执行相关操作。
Windows 驱动安装后运行 SMI 工具导致系统卡死

Windows环境下安装完驱动后，如果在运行后摩 SMI 工具时出现系统卡死或死机现象。

解决方法：

驱动升级完成后请暂不要运行 SMI 工具。需先将固件升级到与当前驱动一致的版本，待固件与驱动版本匹配后再使用 SMI 工具。
Windows 驱动加载失败并提示签名完整性校验异常

在 Windows 环境下安装驱动后，操作系统无法识别当前驱动程序。系统日志中出现如下信息：
- 错误码： 0x27，表示驱动加载失败。
- 状态码： 0xc0e90002 STATUS_SYSTEM_INTEGRITY_POLICY_VIOLATION，表示Windows 在执行驱动签名完整性检查时触发策略违规，由 Windows CI机制判定当前驱动签名不满足完整性要求，从而阻止驱动加载。
原因：

部分 Windows 版本在执行系统补丁回退后，其签名验证策略可能出现异常，导致系统无法正确验证第三方驱动签名，从而阻止驱动加载。

解决方法：

需要关闭 Secure Boot，并在系统启动阶段禁用驱动程序强制签名验证。操作步骤如下：

注意

以下操作仅适用于已通过 Microsoft WHQL 或 Microsoft Attestation 签名验证的驱动程序。对于未获得微软官方签名的驱动，不应关闭 Secure Boot 或禁用强制签名校验，否则可能带来系统安全风险。
1. 关闭Secure Boot。
  1. 重启系统并进入 BIOS/UEFI 设置界面。
  2. 查找 Secure Boot 配置项，具体位置可能因主板或主机型号不同而有所差异，通常位于 Security、Boot 或 Authentication 菜单中。
  3. 将 Secure Boot 设置为 Disabled。
  4. 保存配置并重启系统。
2. 禁用驱动程序强制签名验证：
  1. 打开 设置 -> 更新和安全 -> 恢复。
  2. 在 高级启动 区域点击 立即重启。
  3. 重启进入高级启动菜单后，选择 疑难解答 -> 高级选项 -> 启动设置。
  4. 点击重启，在启动设置界面选择 7) 禁用驱动程序强制签名。
完成上述配置后，系统能够正常加载驱动，设备可正常使用。

6.3. Kylin V11环境报错

Kylin V11 升级固件后 SMI 工具通信失败

在Kylin V11环境下成功安装驱动，并升级固件镜像后，使用后摩SMI工具监控设备时，出现下面错误信息：

E/         [2025-10-13 20:08:42 pid:54883 tid:54883] (53 hm_errcodee)last error: Broken pipe
E/HMRPMSG  [2025-10-13 20:08:42 pid:54883 tid:54883] (269 xh2a_rpmsg_lite_send)fd 4 ioctl SEND failed
E/HMCLIENT [2025-10-13 20:08:42 pid:54883 tid:54883] (49 xh2a_rpmsg_packet-send)Failed to send rpmsg packet
E/HMSHELL  [2025-10-13 20:08:42 pid:54883 tid:54883] (45 xh2a_shell_run)Failed to send shell command
[HM_SMI] [cmd]: cat /sys/class/devfreq/ipu/governor Erron: devo cann't get message from device! ret:-1

解决方法：

可通过以下任意一种方法恢复设备通信：

重启主机后再运行后摩SMI工具。
对上级PCI设备进行rescan操作，指令示例如下：
```
echo 1 | sudo tee /sys/bus/pci/devices/<pcie_bdf>/remove
echo 1 | sudo tee /sys/bus/pci/rescan
```
其中，<pcie_bdf> 为上级PCI设备的BDF，如 0000\:00\:07.0。

Kylin V11 驱动升级时 insmod 安装失败

在 Kylin V11 环境下，驱动升级时安装 insmod 失败。

解决方法：

升级驱动前需按以下步骤操作：

注意

用户必须具备root权限。
1. 执行 getstatus 命令，检查安全机制状态。
2. 执行 setstatus disable 命令，关闭安全机制。

6.4. openEuler环境报错

openEuler 驱动安装失败并提示内核头文件缺失

在openEuler 22.03 LTS或openEuler 24.03 LTS环境下安装驱动过程中，可能出现下面错误：

CRITICAL: Kernel headers for 5.10.0-216.0.0.115.oe2203sp4.x86_64 are missing!
The driver cannot be compiled.
Please run the provided 'install.sh' script to fix dependencies
Or manually run: dnf install kernel-devel-5.10.0-216.0.0.115.oe2203sp4.x86_64

解决方法：

卸载驱动：
```
sudo yum remove houmo-drv-xh2.x86_64
```

根据日志安装内核开发包，示例如下：

sudo dnf install kernel-devel-6.6.0-72.0.0.76.oe2403sp1.x86_64

安装驱动：

sudo yum install houmo-drv-<target_hw>-<release>.${distro}.rpm

openEuler 驱动安装失败并提示网络连接中断

在openEuler 22.03 LTS环境下安装驱动过程中，可能出现下面错误：
```
ConnectionResetError: [Errno 104] Connection resset by peer
```
解决方法：
1. 配置国内 PyPI 镜像源，加速并保证下载稳定性，示例如下：
```
pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip3 config set global.trusted-host pypi.tuna.tsinghua.edu.cn
pip3 config set global.timeout 600
```
2. 安装驱动。