2.1.读者对象

本文档主要适用于以下工程师：

• 驱动安装及维护工程师

• 市场销售人员

• 研发工程师

2.2.软件包说明

M50 软件平台提供的系统软件发布包中，包含驱动安装包，用于安装主机端驱动程序。

系统软件发布包包括：

• 系统驱动包（芯片驱动包），用于驱动、SMI工具、HmUpdateTool工具的安装：

  • Linux（Ubuntu, Kylin V11）： drv-<target_hw>_<release>_${distro}_$arch.run

  • Linux（openEuler, Kylin V10）： drv-<target_hw>-<release>-1.$arch.rpm

  • Windows： drv-<target_hw>_<release>.exe

• 系统软件tar包（芯片固件包），主要包含固件镜像：

  M50_<product_name>_fw-<target_hw>_<release>.tar.gz

软件包命名说明：

• <target_hw> 表示芯片类型：

  • xh2 代表 M50。

• <release> 表示系统软件包版本号。

• ${distro} 表示linux或windows11。

• $arch 表示x86_64或aarch64。

• <product_name> 表示产品名称：

  • M2：LQ50 M.2卡。

  • DM2：LQ50 Duo M.2卡。

  • PCIE_F：LM5070智能加速卡。

  • PCIE_H：LM5050智能加速卡。

  • PCIE_S：LM5030智能加速卡。

注：Kylin V11 系统使用 Ubuntu2004 AArch64 架构的驱动安装包。

3.2.1.安装前准备

驱动升级前需要完成下面操作：

1. 下载驱动安装包。

   请从本网站「驱动下载」页面下载对应操作系统和架构的驱动安装包：https://llm.bee-link.cn/drivers.php

2. 检测环境依赖。

3. 非首次安装：卸载老版本驱动。

4. Python依赖安装。支持Python 3.9+，推荐Python 3.9。

   安装和配置步骤如下：

   1. 执行下面指令安装 Python 3、开发包及 pip 包管理工具：

      sudo apt-get install python3 python3-dev python3-pip -y

   2. 配置 pip 镜像源：

      sudo pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

   3. （可选）升级pip至最新版本。

   4. 运行以下命令确认 pip 镜像源已正确设置：

      sudo pip3 config list

      输出中应包含 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple' 。

   5. 运行以下命令检查 pip 版本及其关联的 Python 环境：

      sudo pip3 --version

      预期输出示例：pip 25.0.1 from /usr/local/lib/python3.9/dist-packages/pip (python 3.9)。返回信息与用户实际安装的Python版本相关。

5. （可选）如果使用GUI方式升级驱动，需安装图形化依赖库：

   sudo apt install libxcb-util1 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 libxcb-cursor0

3.2.2.安装驱动

驱动安装流程如下：

图 3.1驱动安装流程

详细步骤如下：

1. 完成 安装前准备。

2. 在软件包路径下，运行下面指令增加安装包的可执行权限，并安装驱动和依赖库：

   警告

   • 安装过程中，请勿对主机和设备进行复位或下电操作，否则会导致安装失败。

   • 安装过程中，禁止使用Ctrl+C中断安装进程，否则再次安装驱动时可能会失败。如果因此导致安装失败，请联系设备厂商工程师。

   • 需要使用sudo或以root用户身份安装驱动。

   • 建议安装指令中使用 install all 参数，以确保同时安装 HmUpdateTool镜像升级工具等依赖库，否则可能导致无法完成后续固件镜像升级。

   chmod a+x drv-<target_hw>_<release>_${distro}_$arch.run
   sudo bash ./drv-<target_hw>_<release>_${distro}_$arch.run install all --path <PATH>

   PATH 应替换为驱动安装路径。如果不指定 --path <PATH>， 则驱动默认安装在 /usr/local/-sdk 目录下。

3. 安装过程中，可能会提示是否清空之前驱动目录，示例如下：

   the /usr/local/drv-xh2_<release> directory is not empty, do you want to clean the files in this directory

   输入 yes。

4. 安装过程中如出现要求执行提示指令设置SDK环境，例如：

   please input source /etc/profile.d/-sdk.sh command to enable sdk environment

   需根据提示执行对应命令，使环境变量生效：

   source /etc/profile.d/-sdk.sh

5. 检测驱动是否安装成功。SMI工具随驱动一同安装。

   在任意路径下，执行下面SMI工具命令查看驱动是否安装成功：

   hm_smi -a

   返回信息示例如下：

   -------------------------------------------------------------------------------- sdk build infos
   -------------------------------------------------------------------------------- Build_Time : 2026-07-15 09:54:29 HMSW_Version : V1.4.0 HM_SMI_Version : V1.0.0
   -------------------------------------------------------------------------------- Wed Jul 15 13:58:28 CST 2026
   -------------------------------------------------------------------------------- device0 detail infos
   -------------------------------------------------------------------------------- Driver_Version : V1.4.0 Vendor : BDF : 0000:01:00.0 Dev : 0 Cur_BandWidth : 8.0 GT/s x 4lane Power_Management : DVFS_Mode : performance Cur_Ipu_Freq : 1300.0 Mhz Lock_Ipu_Pll_Rate : 1300.0 Mhz IPU_Load : 0.0 % Firmware_Version : V1.4.0 IPU_Infos : Core_Num : 2 Core_Freq : 1300.0 Mhz Voltage : 750.0 mV Core0_Util : 0.0 % Core1_Util : 0.0 % Average_Util : 0.0 % Group_Id : 0 Chip_Id : 0 SN : 0102020100002025003800000059 PN : 100C2010 Model : LQ50-12GB DDR_Memory_Infos : DDR_Memory_Free : 12160.0MB DDR_Memory_Total : 12160.0MB Temperature : DDR0 : 25.9 C DDR2 : 26.6 C DDR4 : 23.6 C DDR5 : 24.8 C Core0 : 27.2 C Core1 : 26.0 C Board_Power : 5.26 W
   --------------------------------------------------------------------------------

   如果未返回AI 设备信息，则需重启AI 设备，再次使用该命令查看设备状态。

3.2.3.卸载驱动

执行下面指令在主机端卸载驱动：

3.3.1.安装前准备

驱动升级前需要完成下面操作：

1. 下载驱动安装包。

   请从本网站「驱动下载」页面下载对应操作系统和架构的驱动安装包：https://llm.bee-link.cn/drivers.php

2. 检测环境依赖。

3. 非首次安装：卸载老版本驱动。

4. 使用系统主机，需要确保以下依赖已安装：

   1. 安装依赖工具。

      sudo dnf update -y && sudo dnf install -y \ python3 \ python3-libs \ python3-devel \ gcc \ gcc-c++ \ curl

   2. 安装并初始化 pip。

      curl -sSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py \
      && python3 /tmp/get-pip.py -i https://pypi.tuna.tsinghua.edu.cn/simple \
      && rm /tmp/get-pip.py

   3. 配置镜像源并安装核心依赖。

      sudo pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple \ && sudo pip3 install \ "setuptools>=45.0" \ "cython>=0.29.0" \ pyyaml \ pyserial \ && sudo pip3 install --no-cache-dir PySide6

3.3.2.安装驱动

详细步骤如下：

1. 完成 安装前准备。

2. 在驱动软件包所在路径下，运行下面指令安装驱动：

   警告

   • 安装过程中，请勿对主机和设备进行复位或下电操作，否则会导致安装失败。

   • 安装过程中，禁止使用Ctrl+C中断安装进程，否则再次安装驱动时可能会失败。如果因此导致安装失败，请联系设备厂商工程师。

   • 需要使用sudo或以root用户身份安装驱动。

   sudo yum install drv-<target_hw>-<release>-1.$arch.rpm

3. （可选）如果安装过程中提示缺少内核头文件，可根据日志安装内核开发包，示例如下：

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

   然后重新执行驱动安装：

   sudo yum install drv-<target_hw>-<release>-1.$arch.rpm

4. 检测驱动是否安装成功。SMI工具随驱动一同安装。

   在任意路径下，执行下面SMI工具命令查看驱动是否安装成功：

   hm_smi -a

   返回信息示例如下：

   -------------------------------------------------------------------------------- sdk build infos
   -------------------------------------------------------------------------------- Build_Time : 2026-07-15 09:54:29 HMSW_Version : V1.4.0 HM_SMI_Version : V1.0.0
   -------------------------------------------------------------------------------- Wed Jul 15 13:58:28 CST 2026
   -------------------------------------------------------------------------------- device0 detail infos
   -------------------------------------------------------------------------------- Driver_Version : V1.4.0 Vendor : BDF : 0000:01:00.0 Dev : 0 Cur_BandWidth : 8.0 GT/s x 4lane Power_Management : DVFS_Mode : performance Cur_Ipu_Freq : 1300.0 Mhz Lock_Ipu_Pll_Rate : 1300.0 Mhz IPU_Load : 0.0 % Firmware_Version : V1.4.0 IPU_Infos : Core_Num : 2 Core_Freq : 1300.0 Mhz Voltage : 750.0 mV Core0_Util : 0.0 % Core1_Util : 0.0 % Average_Util : 0.0 % Group_Id : 0 Chip_Id : 0 SN : 0102020100002025003800000059 PN : 100C2010 Model : LQ50-12GB DDR_Memory_Infos : DDR_Memory_Free : 12160.0MB DDR_Memory_Total : 12160.0MB Temperature : DDR0 : 25.9 C DDR2 : 26.6 C DDR4 : 23.6 C DDR5 : 24.8 C Core0 : 27.2 C Core1 : 26.0 C Board_Power : 5.26 W
   --------------------------------------------------------------------------------

   如果未返回AI 设备信息，则需重启AI 设备，再次使用该命令查看设备状态。

3.3.3.卸载驱动

执行下面指令在主机端卸载驱动：

4.1.环境依赖

Windows系统主机端，支持在下面环境下安装驱动：

• Windows 11

4.2.安装前准备

驱动升级前需要完成下面操作：

1. 下载驱动安装包。

   请从本网站「驱动下载」页面下载对应操作系统和架构的驱动安装包：https://llm.bee-link.cn/drivers.php

2. 检测环境依赖。

3. 非首次安装：卸载老版本驱动。

4. MinGW-w64依赖安装：

   1. 下载MinGW-w64 安装程序。

   2. 双击运行下载得到的 w64devkit-x64-2.4.0.7z.exe，并选择解压路径，如 D:。

   3. 配置系统环境变量。在系统的 Path 环境变量中添加MinGW-w64提取的 bin 路径，如：D:\w64devkit\bin。

5. Python依赖安装：

   • 支持Python 3.9至3.13版本，推荐Python 3.12版本（Python 3.12安装程序）。

     注意

     不同 Windows 版本对 Python 的支持范围不同。在安装 Python 前，请确认当前操作系统版本满足目标 Python 版本的官方支持要求。

   • 配置系统环境变量。在系统的 Path 环境变量中添加Python路径。不同 Python 版本及安装方式生成的目录结构可能存在差异，请以实际安装结果为准。通常情况下，建议至少包含以下目录（若存在）：

     • %python_path%\Scripts\

     • %python_path%\

     %python_path% 需替换为本机 Python 实际安装路径，如：C:\Program Files\Python312\。

     注意：

     • 并非所有 Python 安装都会生成 Scripts 目录。例如，精简安装或仅用于运行嵌入式解释器的场景中可能不存在该目录。

     • 如安装了 Python Launcher（py.exe），可额外添加以下目录（若存在）：

       %python_path%\Launcher\

     用户也可在Python安装时勾选 Add python.exe to PATH 复选框自动设置环境变量，示例如下：

     图 4.1Windows主机端Python环境变量设置

6. pip源配置与更新：

   以下配置仅适用于无法稳定访问官方 PyPI 的网络环境。

   1. 以管理员身份打开 命令提示符 （Command Prompt）窗口。

   2. 执行下面指令安装pip，如果系统已安装，请忽略该步骤：

      python -m ensurepip --upgrade

      安装完成后，可执行 pip --version 检查是否安装成功。

   3. 配置系统环境变量。在系统的 Path 环境变量中添加pip安装路径，如：C:\Program Files\Python312\Scripts\。

   4. 执行以下命令配置 pip：

      pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

   5. 更新本地 pip 到最新版本：

      pip install --upgrade pip

4.3.安装驱动

支持一键安装驱动。目前一台主机上仅支持安装单个AI 设备。

执行下面步骤一键安装驱动：

1. 完成 安装前准备。

2. 右击 drv-<target_hw>_<release>.exe，在弹出菜单中选择 以管理员身份运行(A)。Setup 窗口弹出，如下图所示：

   图 4.2驱动安装窗口

3. 在 Setup 窗口，点击 Install。

4. 如果驱动安装成功，弹出窗口如下图所示。点击 OK 重启主机。

   图 4.3Windows主机重启窗口

5. 检测驱动是否安装成功。在任务栏上的搜索框中，键入设备管理器，然后从菜单中选择设备管理器，弹出设备管理器窗口。

   如果存在AI Device节点则说明安装成功，示例如下图所示：

   图 4.4驱动安装：设备管理器中含有AI 设备节点

6. 关闭动态功耗管理。

4.4.卸载驱动

如果卸载v0.6.0或更高版本驱动，可通过系统设置卸载已安装的驱动包，操作步骤如下：

1. 打开 设置 -> 应用 -> 已安装的应用。

2. 在应用列表中查找 drv-xh2 <release>。如下图所示：

   图 4.5通过Windows系统设置卸载驱动

3. 单击应用右侧的 更多选项 （三个点），选择 卸载，并按提示完成卸载。

如果卸载v0.5.0或更低版本驱动，执行下面指令在主机端卸载驱动：

1. 以管理员身份打开Windows命令提示符窗口。

   警告

   必须以管理员身份运行命令提示符窗口。

2. 在命令提示符窗口中，进入驱动安装包所在目录。

3. 输入下面指令卸载驱动：

   .\drv-<target_hw>_<release>.exe /SILENT command=uninstall

4. 弹出的窗口中，点击 Yes，卸载驱动。

5. 在任务栏上的搜索框中，键入设备管理器，然后从菜单中选择设备管理器，弹出设备管理器窗口。如果 AI Device 节点已不存在，则说明卸载成功。

5.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 ./drv-<target_hw>_<release>_${distro}_$arch.run uninstall all
  sudo dkms remove xh2_driver/<release>
  sudo ./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/-sdk 目录下。

• Ubuntu 驱动安装失败并提示 pci_alloc_irq_vectors failed

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

  原因1：

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

  判断方法：

  检查AI 设备状态：

  lspci -s BB:DD.F -vvv

  其中，BB:DD.F 为AI 设备PCIe BDF信息。如果返回下面信息，说明AI 设备信息未更新。

  03:00.0 Memory controller: Device 1f6b:0c00 (rev ff) (prog-if ff) !!! Unknown header type 7f Kernel modules: xh2a_drv

  解决方法：

  执行下面步骤：

  1. 卸载驱动。

  2. 重新扫描AI 设备，指令示例如下：

  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，进入 高级 菜单，按 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++

• Linux ARM环境安装驱动时depmod长时间卡住

  在Linux ARM 环境下安装驱动时，驱动模块已完成编译并安装到内核模块目录，但安装过程可能长时间停留在 depmod 阶段，无法继续完成。示例日志如下：

  sudo ./drv-xh2_v1.3.0_linux_aarch64.run install all --build-host false
  [INFO] 2026-06-03 16:19:35 drv-xh2_v1.3.0_linux_aarch64.run: --------------init release env---------------------
  [INFO] 2026-06-03 16:19:35 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 drv-xh2_v1.3.0_linux_aarch64.run: gcc is already installed, version: 11
  [INFO] 2026-06-03 16:19:35 drv-xh2_v1.3.0_linux_aarch64.run: dependencies_kernel_module is
  [INFO] 2026-06-03 16:19:48 drv-xh2_v1.3.0_linux_aarch64.run: extract release path is /usr/local/-sdk
  [INFO] 2026-06-03 16:19:48 drv-xh2_v1.3.0_linux_aarch64.run: Installing /etc/profile.d/-sdk.sh
  [INFO] 2026-06-03 16:19:59 drv-xh2_v1.3.0_linux_aarch64.run: installing xh2a driver
  [INFO] 2026-06-03 16:19:59 drv-xh2_v1.3.0_linux_aarch64.run: No xh2_driver installed.
  /tmp/drv-xh2_v1.3.0/driver /home/sky/
  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 ./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和文件系统状态，确认是否存在文件损坏、符号链接异常或系统镜像异常等问题。

     如果确认系统镜像或内核模块环境异常，建议重新刷写系统镜像后再安装驱动。

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

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

  Windows环境下卸载驱动过程中出现下面错误信息：

  checking Xh2aHostDriver with class AI Device
  removing 1/1: oem3.inf
  remove driver fail, error: 5

  原因：

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

  解决方法：

  使用管理员身份运行命令提示符窗口。

• Windows远程桌面安装驱动后设备识别异常

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

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

  解决方法：

  请使用本地物理登录方式安装驱动和管理AI 设备，避免通过远程桌面连接执行相关操作。

• 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) 禁用驱动程序强制签名。

  完成上述配置后，系统能够正常加载驱动，设备可正常使用。

5.3.Kylin V11环境报错

• Kylin V11 驱动升级时执行insmod加载驱动模块失败

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

  解决方法：

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

  注意

  用户必须具备root权限。

  1. 执行 getstatus 命令，检查安全机制状态。

  2. 执行 setstatus disable 命令，关闭安全机制。

5.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 drv-xh2.x86_64

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

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

  3. 安装驱动：

     sudo yum install 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. 安装驱动：

     sudo yum install drv-<target_hw>-<release>-1.$arch.rpm