常见错误解析
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 uninstall 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. [卸载驱动](/houmo-m50/software-manual/system-installation-device-management/environment-deployment/system_software_installation_guide/linux/ubuntu/#uninstall)。
2. 重新扫描后摩设备，指令示例如下：
4
其中，
<pcie_bdf>为上级PCI设备的BDF，如0000\:00\:07.0。
3. 重启主机。
原因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：将[附件](https://houmo-llm.oss-cn-shanghai.aliyuncs.com/developer-files/MFGLNX.zip)拷贝到目标主机，解压附件后进入目录，使用root权限执行下面命令：
./mfgdone.sh -clr
重启系统，按 F1 进BIOS Setup，进入 高级 菜单，按 Ctrl+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.log for more information.
原因：
* 当前系统缺少与内核版本匹配的 GCC 编译器。
* 驱动模块通过 DKMS 编译时，需要使用系统默认 GCC 版本与内核编译器版本一致，否则会导致编译失败。
解决方法：
1. 安装 GCC 12（确保与内核版本兼容）：
sudo apt update
sudo apt install gcc-12 g++-12
2. 验证GCC版本：
gcc --version
3. 将 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++
4. [安装驱动](/houmo-m50/software-manual/system-installation-device-management/environment-deployment/system_software_installation_guide/linux/ubuntu/#driverinstall)。
- Linux ARM环境安装驱动时depmod长时间卡住
在Linux ARM 环境下安装驱动时，驱动模块已完成编译并安装到内核模块目录，但安装过程可能长时间停留在 depmod 阶段，无法继续完成。示例日志如下：
sudo ./houmo-drv-xh2_v1.3.0_linux_aarch64.run install all --build-host false
[INFO] 2026-06-03 16:19:35 houmo-drv-xh2_v1.3.0_linux_aarch64.run: --------------init release env---------------------
[INFO] 2026-06-03 16:19:35 houmo-drv-xh2_v1.3.0_linux_aarch64.run: release user is sky, and user bashrc path is /home/sky
[INFO] 2026-06-03 16:19:35 houmo-drv-xh2_v1.3.0_linux_aarch64.run: gcc is already installed, version: 11
[INFO] 2026-06-03 16:19:35 houmo-drv-xh2_v1.3.0_linux_aarch64.run: dependencies_kernel_module is
[INFO] 2026-06-03 16:19:48 houmo-drv-xh2_v1.3.0_linux_aarch64.run: extract release path is /usr/local/houmo-sdk
[INFO] 2026-06-03 16:19:48 houmo-drv-xh2_v1.3.0_linux_aarch64.run: Installing /etc/profile.d/houmo-sdk.sh
[INFO] 2026-06-03 16:19:59 houmo-drv-xh2_v1.3.0_linux_aarch64.run: installing xh2a driver
[INFO] 2026-06-03 16:19:59 houmo-drv-xh2_v1.3.0_linux_aarch64.run: No xh2_driver installed.
/tmp/houmo-drv-xh2_v1.3.0/driver /home/sky/houmo
Creating symlink /var/lib/dkms/xh2_driver/v1.3.0/source -> /usr/src/xh2_driver-v1.3.0
Kernel preparation unnecessary for this kernel. Skipping...
Building module:
cleaning build area....
make -j8 KERNELRELEASE=5.10.226 -C /lib/modules/5.10.226/build M=/var/lib/dkms/xh2_driver/v1.3.0/build......
cleaning build area....
xh2a_drv.ko:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/5.10.226/updates/dkms/
depmod....................
原因：
该问题通常发生在 depmod 更新内核模块依赖关系阶段。此时驱动模块可能已经完成编译，但系统在扫描内核模块目录、生成模块依赖信息时异常卡住，导致安装流程无法结束。
depmod 长时间卡住通常与当前系统内核模块环境或文件系统状态异常有关，常见原因包括：
* `modules.dep` 等内核模块依赖文件损坏或异常过大。
* 内核模块目录中存在符号链接循环引用。
* 磁盘I/O异常或文件系统错误。
* 某个内核模块文件损坏，导致 `depmod` 解析依赖关系时无法正常完成。
* 当前系统镜像或内核模块目录状态异常。
解决方法：
请按以下步骤处理：
1. 终止卡住的 `depmod` 进程。
如果安装过程长时间停留在 depmod 阶段，可执行以下命令终止 depmod 进程：
sudo killall -9 depmod
2. 重新执行驱动安装。
终止 depmod 后，重新执行驱动安装命令，确认安装流程是否可以正常完成：
sudo ./houmo-drv-xh2_<release>_linux_aarch64.run install all --build-host false
3. 手动加载驱动模块。
如果重新安装后仍卡在 depmod 阶段，但驱动模块 xh2a_drv.ko 已经生成，可尝试手动加载该模块：
sudo insmod /var/lib/dkms/xh2_driver/kernel-5.10.226-aarch64/module/xh2a_drv.ko
注意
上述路径仅为示例。请根据实际内核版本和DKMS输出目录确认 xh2a_drv.ko 的实际路径。如果该路径不存在，请检查 /var/lib/dkms/xh2_driver/ 目录下生成的模块文件位置。
4. 检查系统环境。
如果 depmod 多次卡住，建议检查系统内核模块目录、磁盘I/O和文件系统状态，确认是否存在文件损坏、符号链接异常或系统镜像异常等问题。
如果确认系统镜像或内核模块环境异常，建议重新刷写系统镜像后再安装驱动。
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 驱动升级时执行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
解决方法：
1. 卸载驱动：
sudo yum remove houmo-drv-xh2.x86_64
2. 根据日志安装内核开发包，示例如下：
sudo dnf install kernel-devel-6.6.0-72.0.0.76.oe2403sp1.x86_64
3. 安装驱动：
sudo yum install houmo-drv-<target_hw>-<release>-1.$arch.rpm
- openEuler 驱动安装失败并提示网络连接中断
在openEuler 22.03 LTS环境下安装驱动过程中，可能出现下面错误：
ConnectionResetError: [Errno 104] Connection reset 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. [安装驱动](/houmo-m50/software-manual/system-installation-device-management/environment-deployment/system_software_installation_guide/linux/openeuler/#install-openeuler)。