常见错误处理
驱动安装
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解决方法：
执行下面步骤：
卸载驱动。
重新扫描后摩设备，指令示例如下：
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。重启主机。
原因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，进入 高级 菜单，按 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 版本与内核编译器版本一致，否则会导致编译失败。
解决方法：
安装 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++
安装驱动。
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解析依赖关系时无法正常完成。当前系统镜像或内核模块目录状态异常。
解决方法：
请按以下步骤处理：
终止卡住的
depmod进程。如果安装过程长时间停留在
depmod阶段，可执行以下命令终止depmod进程：sudo killall -9 depmod
重新执行驱动安装。
终止
depmod后，重新执行驱动安装命令，确认安装流程是否可以正常完成：sudo ./houmo-drv-xh2_<release>_linux_aarch64.run install all --build-host false
手动加载驱动模块。
如果重新安装后仍卡在
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/目录下生成的模块文件位置。检查系统环境。
如果
depmod多次卡住，建议检查系统内核模块目录、磁盘I/O和文件系统状态，确认是否存在文件损坏、符号链接异常或系统镜像异常等问题。如果确认系统镜像或内核模块环境异常，建议重新刷写系统镜像后再安装驱动。
固件镜像升级
Linux 升级固件镜像失败并提示 Qt xcb 插件加载失败
在 Linux 主机端升级固件镜像时，出现下面错误信息：
From 6.5.0, xcb-cursor0 or libxcb-cursore is needed to load the Qt xcb platform plugin. Could not load the Qt platform plugin"xcb" in ""even though it was found.
原因
主机环境缺少依赖库 libxcb-cursor0，导致 Qt 无法正确加载 xcb 平台插件。
解决方法：
在主机端执行以下命令安装依赖库：
sudo apt-get install libxcb-cursor0
重新升级固件镜像。
GUI 升级固件镜像失败并提示inspect模块缺失
使用GUI界面方式升级固件镜像时，如果出现以下错误：
No module named 'inspect'
原因
运行环境中的 GNU C Library 版本过低，导致 GUI 程序依赖的 Python 模块无法正常加载。
解决方法：
系统的 GNU C Library 版本不低于 2.28。
命令行升级固件镜像失败并提示设备节点打开失败
使用命令行方式升级固件镜像时，如果出现以下错误：
(53 hm_errcode)last error: No such file or directory (55 xh2a_sys_opeen)/dev/xh2a_system_device0 open failed dev 0xh2a_sys_openfailed can not read device 0 dual backup status, default disabled device 0 start to upgrade fsbl, address:0x00042000, length:0x0003e000 bytes (53 hm_errcode)last error: No such file or directory (776 xh2a_memory_allocator_open)/dev/xh2a_memory_allocator_deviceo_ddr open fail
原因：
可能是当前主机配置不支持分配多个MSI中断，请检查主机BIOS设置。
解决方法：
X86_64平台：
检查BIOS/UEFI 配置，确保平台 IOMMU 功能已开启。不同厂商命名可能为 VT-d、AMD VT、IO Virtualization 或 IOMMU等名称呈现。
例如，在部分 海光平台主机中，IOMMU 的配置项位于 Chipset -> NBIO -> IOMMU，而另一类海光平台主机中，IOMMU的配置可能位于 Hygon CBS 菜单下。对于AMD和海光处理器，还可以在 Linux 中检查是否存在 IVRS 表项，用于辅助判断 IOMMU 是否正确启用。如果系统中不存在
/sys/firmware/acpi/tables/IVRS文件，则表明BIOS中未正确开启IOMMU。ARM平台：
请根据实际平台确认GIC/ITS或中断重映射功能已启用。
智能加速卡重启设备失败并提示Cannot reset dev
如果使用LM5070或LM5050智能加速卡执行
sudo hm_smi -rd 0指令或GUI界面按钮重启后摩设备时，可能返回如下错误信息：Can not reset dev0 !!!
原因：
LM5070和LM5050智能加速卡不支持通过软件方式执行设备复位操作，因此在执行重启指令时会返回失败。
解决方法：
用户需关闭主机并重新启动主机，以完成设备重启。
SMI工具
多芯片场景下SMI查询设备信息时提示I2C read failed
如果当前后摩设备上有多颗后摩M50芯片，即有多个后摩逻辑设备，当执行
hm_smi -a查看所有后摩设备信息时，返回下面错误：E/ [2025-09-24 04:09:53 pid:6502 tid:6504] (53 hm_errcode)last error: Invalid argument E/HMI2C [2025-09-24 04:09:53 pid:6502 tid:6504] (163 xh2a_i2c_read)I2C read failed on fd 5, bus 2
解决方法：
忽略错误信息。
Linux运行SMI工具失败并提示command not found
在Linux系统环境下，运行SMI指令返回下面错误信息：
bash: hm_smi: command not found
原因：
可能是驱动安装过程中，由于其他用户意外修改了
~/.bashrc文件，导致当前终端中的PATH环境变量中SMI工具所在路径不对。解决方法：
在
~/.bashrc文件末尾添加 SMI 工具路径，示例如下：export PATH=/usr/local/houmo-sdk/tools:${PATH}重新加载 ~/.bashrc 文件：
source ~/.bashrc
智能加速卡重启设备失败并提示Cannot reset dev
如果使用LM5070或LM5050智能加速卡执行下面指令重启后摩设备：
sudo hm_smi -rd 0
可能返回如下错误信息：
Can not reset dev0 !!!
原因：
LM5070和LM5050智能加速卡不支持通过软件方式执行设备复位操作，因此在执行重启指令时会返回失败。
解决方法：
用户需关闭主机并重新启动主机，以完成设备重启。
模型推理
在多线程推理场景下，模型推理可能失败，返回
Interrupted system call或Bad file descriptor等错误信息。原因：
当主机进入系统级睡眠或休眠状态时，后摩设备相关操作会受到影响。在多线程推理过程中，如果系统发生睡眠或从睡眠状态唤醒，推理相关的设备访问可能中断，从而导致推理失败。
解决方法：
请确保运行推理任务的主机关闭自动睡眠或休眠功能，避免在推理过程中进入睡眠状态。
Windows系统
在 设置 -> 系统 -> 电源和电池 -> 屏幕和睡眠 中，将 睡眠 相关选项设置为 从不，确保系统在推理过程中不会自动进入睡眠状态。
Linux系统
禁用系统休眠：
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target恢复系统休眠：
sudo systemctl unmask sleep.target suspend.target hibernate.target hybrid-sleep.target查看当前状态：
systemctl status sleep.target suspend.target hibernate.target hybrid-sleep.target