4. 镜像升级
本章介绍如何使用HMDML工具升级后摩设备镜像。
4.1. 固件升级与回退机制
HMDML 固件升级接口支持基于A/B双分区的固件升级与回退机制，用于提升系统升级的可靠性与容错能力。该功能由后摩设备eFuse配置决定，仅在1.4.0或更高版本固件镜像中支持。
在启用该功能后，系统维护A与B两个分区。HMDML 固件升级接口根据内部策略仅对一个分区进行固件升级更新。
在升级过程中，若发生掉电或异常重启等情况，当前正在运行的系统不受影响，后摩设备仍可从另一可用分区启动。当新版本分区因镜像损坏、校验失败或启动异常导致无法正常启动时，后摩设备启动失败时自动回退至另一可启动分区继续启动，从而保障系统可恢复能力，降低升级失败导致设备不可用的风险。
在未启用双分区能力时，系统仅存在单一启动分区，不具备双分区交替升级与回退机制。
4.2. 升级镜像
下面以Android系统为例介绍如何升级镜像。
在Android主机端，通过HMDML后摩设备管理库C接口升级固件镜像。
4.2.1. 升级前操作
在主机端创建目录，用于存放固件升级示例程序、构建脚本、编译脚本，以及升级程序编译所需的接口头文件和 HAL 库文件。其中，接口头文件和 HAL 库文件需从已安装的驱动目录中获取。下面以 upgrade_firmware 为目录名，介绍如何完成固件升级前准备。
创建
upgrade_firmware文件夹：mkdir -p upgrade_firmware
复制固件升级示例源码到
upgrade_firmware目录下。固件升级可直接使用后摩提供的hm_fw_upgrade_example.c示例代码。cd /path/to/houmo-drv-xh2/hal/export/samples scp hm_fw_upgrade_example.c /path/to/upgrade_firmware/
构建脚本：参见 创建构建脚本。
编译脚本：参见 创建编译脚本。
从系统软件包的
/path/to/houmo-drv-xh2/hal/export/include目录复制hm_sys.h和hm_api.h到upgrade_firmware目录下：cd /path/to/houmo-drv-xh2/hal/export/include scp hm_api.h hm_sys.h ../../../../upgrade_firmware/
从系统软件包的
/path/to/houmo-drv-xh2/hal/lib目录复制libhal_xh2a.a和libhal_xh2a.so到upgrade_firmware目录下：cd /path/to/houmo-drv-xh2/hal/lib scp libhal_xh2a.a libhal_xh2a.so ../../../upgrade_firmware/
4.2.1.1. 创建构建脚本
镜像升级前，用户需在 upgrade_firmware 目录下创建一个CMake构建脚本，用于在主机端编译生成可执行文件。示例文件名为 CMakeLists.txt，主要操作如下：
设置 CMake 工程信息与 C++ 标准。
指定 CMake 最低版本和工具链文件。
设置 C++ 标准为 C++17，并开启调试信息。
配置 Android 平台信息。
ANDROID_NDK：替换为主机端实际 NDK 安装路径。ANDROID_PLATFORM：指定 Android API 版本，例如 android-24。ANDROID_ABI：指定目标架构，例如 arm64-v8a。设置 Android STL 为共享库
c++_shared。
设置 HAL 库及头文件路径：
HAL_LIBRARY：替换为主机端驱动动态库libhal_xh2a.so的路径。该库位于驱动安装包中houmo-drv-xh2_<release>_android_$arch/houmo-drv-xh2/hal/lib下。通过
include_directories指定头文件路径，例如工程通用头文件${CMAKE_BINARY_DIR}/../../common和 Android 系统头文件${ANDROID_NDK}/sysroot/usr/include。
添加可执行文件并链接库。
通过
add_executable设置输出可执行文件名。通过
target_link_libraries链接 HAL 动态库，实现驱动接口调用。
完整示例如下，示例展示关键步骤代码，仅供参考，不可以直接拷贝运行。
cmake_minimum_required(VERSION 3.16)
set(CMAKE_TOOLCHAIN_FILE ${ANDROID_NDK}/build/cmake/android.toolchain.cmake)
project(IpuTest)
# 设置C++标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g")
# Android特定配置 - 需通过命令行传入ANDROID_NDK路径
if(NOT ANDROID_NDK)
message(FATAL_ERROR "请通过-DANDROID_NDK=指定NDK路径")
endif()
# 设置Android平台和架构
if(NOT ANDROID_PLATFORM)
set(ANDROID_PLATFORM android-24) # 最低支持Android 7.0
endif()
if(NOT ANDROID_ABI)
set(ANDROID_ABI arm64-v8a) # 默认编译ARM64架构
endif()
# Android平台配置
set(ANDROID_STL c++_shared) # 使用共享STL
set(ANDROID_USE_LEGACY_TOOLCHAIN_FILE FALSE)
# 设置库文件名称和搜索路径（Android平台）
set(HAL_LIBRARY_NAMES hal_xh2a)
set(LIB_SEARCH_PATHS
${CMAKE_CURRENT_SOURCE_DIR}/../lib/android/${ANDROID_ABI}/ # 按架构区分的库路径
${CMAKE_CURRENT_SOURCE_DIR}/../lib/android/ # 通用Android库路径
)
set(CMAKE_FIND_LIBRARY_SUFFIXES .so .a) # Android常用库后缀
# 直接指定库文件绝对路径，替换所有 find_library 相关代码
set(HAL_LIBRARY /path/to/houmo-drv-xh2/hal/lib/libhal_xh2a.so)
if(NOT EXISTS ${HAL_LIBRARY})
message(FATAL_ERROR "HAL库不存在：${HAL_LIBRARY}")
endif()
message(STATUS "找到HAL库: ${HAL_LIBRARY}")
# 包含头文件目录
include_directories(${CMAKE_CURRENT_SOURCE_DIR})
# 添加可执行文件
add_executable(upgrade_firmware hm_fw_upgrade_example.c)
# 链接库文件
target_link_libraries(upgrade_firmware PRIVATE ${HAL_LIBRARY})
4.2.1.2. 创建编译脚本
在主机端，需在 upgrade_firmware 目录下，创建一个用于编译固件升级示例程序的 shell 脚本，并保存为 .sh 文件，例如 compile.sh。主要内容如下：
设置编译目录。在示例中，将编译产物输出到
build_android目录。示例中用户需根据实际环境修改变量值：
NDK_PATH：主机端 Android NDK 的实际安装路径。HOUMO_SDK_PATH：主机端后摩驱动路径，通常位于驱动安装包中houmo-drv-xh2_<release>_android_$arch/houmo-drv-xh2目录下。ANDROID_ABI：目标架构，如arm64-v8a。ANDROID_PLATFORM：Android平台版本，如android-27。
执行 CMake 生成 Makefile，并通过 Make 编译生成可执行文件。
完整示例如下，示例展示关键步骤代码，仅供参考，不可以直接拷贝运行。
#!/bin/bash
# 配置编译目录
BUILD_DIR=build_android
rm -rf $BUILD_DIR
mkdir -p $BUILD_DIR
cd $BUILD_DIR
# 关键：指定 NDK 路径（替换为你的实际 NDK 路径）
NDK_PATH="/path/to/android-ndk-r27c" # 例如：~/Android/Sdk/ndk/r27d
HOUMO_SDK_PATH="/path/to/houmo_drv_xh2"
ANDROID_ABI="arm64-v8a"
ANDROID_PLATFORM="android-27"
# 执行 cmake 生成 Makefile（参数必须写在同一行，用空格分隔）
cmake --fresh .. \
-DANDROID_NDK=$NDK_PATH \
-DANDROID_PLATFORM=android-27 \
-DANDROID_ABI=arm64-v8a
# 编译（-j4 表示使用 4 线程加速）
make -j4
# 回到原目录
cd ..
4.2.2. 升级操作
4.2.2.1. 升级前准备
镜像升级前，完成镜像升级前准备：
确保符合 环境依赖。
安装驱动。详情参看《软件平台驱动安装指南》。
4.2.2.2. 升级步骤
镜像升级主要步骤如下：
固件镜像位于系统软件tar包内，用户需要下载系统软件tar包来获取固件镜像。在主机端，执行下面步骤下载固件镜像：
登录后摩开发者社区 。
在 请先选择板级类别 下拉列表中选择使用的后摩板级产品。
在版本列表中选择下载的版本号，再在 AI模型类别筛选器 、平台架构筛选器 、操作系统筛选器 下拉菜单中分别选择AI模型类型、平台架构和操作系统，找到资源名为芯片固件的下载资源，选中该资源左边复选框。
点击 直接下载、wget链接、批量直接下载 或 wget批量下载 按钮。
解压缩系统软件tar包。镜像位于解压后文件夹下。
解压缩固件镜像：
tar -xf M50_DM2_fw-xh2_<release>.tar.gz
解压后，固件镜像存放在
M50_DM2_fw-xh2目录下。完成 升级前操作。
编译生成可执行文件。在主机端执行以下命令，生成可执行文件：
cd upgrade_firmware chmod +x compile.sh ./compile.sh
编译成功后，会在编译脚本中指定的输出目录中生成可执行文件。示例中，该目录为
build_android，可执行文件名称为upgrade_firmware。传输文件至 Android 端。
将主机端的
upgrade_firmware文件夹推送至 Android 端的/data/houmo目录：adb push upgrade_firmware /data/houmo
传输下载的镜像文件到 Android 端指定目录：
adb push M50_DM2_fw-xh2/images /data/houmo/upgrade_firmware
启动Android开发板并进入 shell 模式：
adb shell su
配置环境变量。在 Android 端设置驱动库路径：
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/houmo/houmo-drv-xh2/hal/lib
升级镜像。在 Android 端，进入
upgrade_firmware目录，执行以下命令升级。仅需升级firmware.img镜像。示例如下：cd /data/houmo/upgrade_firmware/build_android ./upgrade_firmware -f ../images/firmware.img -d all
固件升级以逻辑设备（即单颗 M50 芯片）为基本单元。对于多颗芯片的产品（如 LQ50 Duo M.2卡），须确保完成卡内所有逻辑设备的升级，建议一次完成所有逻辑设备升级。
重启Android端。升级完成后，在 Android 端执行以下命令重启系统，使新固件生效：
reboot
镜像升级后，需完成 设备检测与升级验证，确保镜像升级成功。
4.2.3. 设备检测与升级验证
本节用于在完成设备升级后，通过示例程序验证设备驱动与固件是否正常加载，并获取设备基础信息与运行状态。
执行以下步骤进行设备检查：
在主机端创建
device_check文件夹：mkdir -p device_check
复制设备信息获取示例源码到
device_check目录下。设备信息获取可直接使用后摩提供的hm_sys_info_examples.c示例代码。cd /path/to/houmo-drv-xh2/hal/export/samples scp hm_sys_info_examples.c /path/to/device_check/
在
device_check目录下创建一个CMake构建脚本，用于在主机端编译生成可执行文件。示例文件名为 CMakeLists.txt。参数设置及说明，参看 创建构建脚本。需在
add_executable中设置目标可执行文件名称为device_check，并且绑定本示例源码文件hm_sys_info_examples.c。需在
target_link_libraries中设置目标可执行文件名称为device_check。cmake_minimum_required(VERSION 3.16) set(CMAKE_TOOLCHAIN_FILE ${ANDROID_NDK}/build/cmake/android.toolchain.cmake) project(IpuTest) # 设置C++标准 set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -g") # Android特定配置 - 需通过命令行传入ANDROID_NDK路径 if(NOT ANDROID_NDK) message(FATAL_ERROR "请通过-DANDROID_NDK=指定NDK路径") endif() # 设置Android平台和架构 if(NOT ANDROID_PLATFORM) set(ANDROID_PLATFORM android-24) # 最低支持Android 7.0 endif() if(NOT ANDROID_ABI) set(ANDROID_ABI arm64-v8a) # 默认编译ARM64架构 endif() # Android平台配置 set(ANDROID_STL c++_shared) # 使用共享STL set(ANDROID_USE_LEGACY_TOOLCHAIN_FILE FALSE) # 设置库文件名称和搜索路径（Android平台） set(HAL_LIBRARY_NAMES hal_xh2a) set(LIB_SEARCH_PATHS ${CMAKE_CURRENT_SOURCE_DIR}/../lib/android/${ANDROID_ABI}/ # 按架构区分的库路径 ${CMAKE_CURRENT_SOURCE_DIR}/../lib/android/ # 通用Android库路径 ) set(CMAKE_FIND_LIBRARY_SUFFIXES .so .a) # Android常用库后缀 # 直接指定库文件绝对路径，替换所有 find_library 相关代码 set(HAL_LIBRARY /path/to/houmo-drv-xh2/hal/lib/libhal_xh2a.so) if(NOT EXISTS ${HAL_LIBRARY}) message(FATAL_ERROR "HAL库不存在：${HAL_LIBRARY}") endif() message(STATUS "找到HAL库: ${HAL_LIBRARY}") # 包含头文件目录 include_directories(${CMAKE_CURRENT_SOURCE_DIR}) # 添加可执行文件 add_executable(device_check hm_sys_info_examples.c) # 链接库文件 target_link_libraries(device_check PRIVATE ${HAL_LIBRARY})在
device_check目录下创建编译脚本，如compile.sh。用于执行交叉编译流程。建议直接复用镜像升级流程中的编译脚本。从系统软件包的
/path/to/houmo-drv-xh2/hal/export/include目录复制hm_sys.h和hm_api.h到device_check目录下：cd /path/to/houmo-drv-xh2/hal/export/include scp hm_api.h hm_sys.h ../../../../device_check/
从系统软件包的
/path/to/houmo-drv-xh2/hal/lib目录复制libhal_xh2a.a和libhal_xh2a.so到device_check目录下：cd /path/to/houmo-drv-xh2/hal/lib scp libhal_xh2a.a libhal_xh2a.so ../../../device_check/
编译生成可执行文件。在主机端执行以下命令，生成可执行文件：
cd device_check chmod +x compile.sh ./compile.sh
编译成功后，会在编译脚本中指定的输出目录中生成可执行文件。示例中，该目录为
build_android，可执行文件名称为device_check。传输文件至 Android 端。
将主机端的
device_check文件夹推送至 Android 端的/data/houmo目录：adb push device_check /data/houmo
启动Android开发板并进入 shell 模式：
adb shell su
配置环境变量。在Android端设置驱动库路径：
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/data/houmo/houmo-drv-xh2/hal/lib
获得设备信息。在Android端，进入
device_check目录，执行以下命令获取设备信息。cd /data/houmo/device_check/build_android ./device_check
设备信息输出示例如下：
===== Device 0 ===== [dev 0] Basic Properties: vendor id: 0x1f6b serial: 0206020100002025004800000019 name: LQ50 DUO-36GB computing power: 100 TFLOPS core count: 2 [dev 0] Runtime Metrics: core util rate: 0.00 core[0] util: 0.00 core[1] util: 0.00 avg ipu frequency: 1400000000 Hz ipu voltage: 750.00 mV memory: total 18304 MB, used 0 MB, avail 18304 MB temperature: 26.59 C [dev 0] PCIe / Board Info: PCIe BDF: 0001:11:00.00 PCIe bandwidth: 8.0 GT/s PCIe -2lane board power: 12.59 W [dev 0] SDK and Firmware Info: SDK build time: May 19 2026 00:37:11 SDK version: v1.3.0 driver version: v1.3.0 device firmware version: 1.3.0 DDR size: 19327352832 bytes DVFS mode: 0 ===== Device 1 ===== [dev 1] Basic Properties: vendor id: 0x1f6b serial: 0206020100002025004800000019 name: LQ50 DUO-36GB computing power: 100 TFLOPS core count: 2 [dev 1] Runtime Metrics: core util rate: 0.00 core[0] util: 0.00 core[1] util: 0.00 avg ipu frequency: 1400000000 Hz ipu voltage: 750.00 mV memory: total 18304 MB, used 0 MB, avail 18304 MB temperature: 26.88 C [dev 1] PCIe / Board Info: PCIe BDF: 0000:01:00.00 PCIe bandwidth: 8.0 GT/s PCIe -2lane board power: 0.00 W [dev 1] SDK and Firmware Info: SDK build time: May 19 2026 00:37:11 SDK version: v1.3.0 driver version: v1.3.0 device firmware version: 1.3.0 DDR size: 19327352832 bytes DVFS mode: 0