5. Functions

5.1. Device Management

5.1.1. hm_sys_check_device_index

int hm_sys_check_device_index(int dev_index)

Checks if the specified Houmo logical device is valid.

This function verifies that the given device index exists in the list of detected Houmo devices.

See also

hm_sys_check_device_index

Parameters: dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns 0 if the device index is valid; returns -1 if the device index is invalid.

5.1.2. hm_sys_fullchip_reset

int hm_sys_fullchip_reset(int dev_id)

Resets the specified Houmo logical device.

After invoking this API, the PCIe device must be reinitialized via bus rescan. Example procedure for dev_id = 0 (BDF = 0000:01:00.0):

Confirm device BDF. For example:

cat /sys/class/misc/xh2a_ipu0/device_dbdf
Call hm_sys_fullchip_reset(dev_id).
As root (or via sudo), remove and rescan the PCIe device. For example:

echo 1 > /sys/bus/pci/drivers/houmo,xh2a/0000\:01\:00.0/remove

echo 1 > /sys/bus/pci/rescan

where /sys/bus/pci/drivers/houmo,xh2a is the sysfs directory for the Houmo PCI driver, and 0000\:01\:00.0 is the PCIe BDF of the logical device.

Parameters: dev_id -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns 0 on success; returns a negative value on failure.

Note

This API is not supported on LM5070 and LM5050 Acceleration Cards. To reset these products, you need to shut down the host system and then power it on again.

5.1.3. hm_sys_get_available_core_id

int hm_sys_get_available_core_id(int dev_index, uint32_t *mask)

Retrieves the bitmask of the available IPU cores for a specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
mask -- [out] Pointer to a uint32_t variable to store the IPU core status bitmask.
- 0x01: IPU core 0 is available.
- 0x10: IPU core 1 is available.
- 0x11: Both IPU core 0 and core 1 are available.

Returns

Returns 0 on success; returns -1 on failure (e.g., invalid device index or unprogrammed eFuse).

Note

This function requires valid data in the Houmo device eFuse. The core availability mask can be retrieved only if the eFuse has been programmed.

5.1.4. hm_sys_get_bandwidth

int hm_sys_get_bandwidth(int dev_index, char *bandwidth, size_t len)

Retrieves the real-time PCIe link bandwidth of the specified Houmo logical device.

This function retrieves the current data transfer capability of the PCIe interface connecting the device to the host system.

The bandwidth is returned in the format <link_rate>-<lane_count>, for example, 5.0 GT/s-4lane:

link_rate: Data transfer rate per lane in gigatransfers per second (GT/s).
lane_count: Number of active PCIe lanes.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
bandwidth -- [out] A pointer to a buffer for storing the PCIe link bandwidth string.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns a negative value on failure.

Note

This function is supported only on Linux and Android systems. It is not supported on Windows.

5.1.5. hm_sys_get_bdf

int hm_sys_get_bdf(int dev_index, char *bdf, size_t len)

Retrieves the PCIe BDF (Bus, Device, Function) of the specified Houmo logical device.

The BDF string uniquely identifies the PCIe device within the system.

Linux Format: domain:bus:device.function

Components:

domain: PCIe domain number (Linux only).
bus: PCIe bus number.
device: Device number on the specified bus.
function: Specific function or port number of the device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
bdf -- [out] A pointer to a buffer for storing the PCIe BDF string.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns a negative value on failure.

Note

This function is supported only on Linux and Android systems. It is not supported on Windows.

5.1.6. hm_sys_get_board_power

int hm_sys_get_board_power(int dev_index, float *power)

Retrieves the real-time power consumption (W) of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
power -- [out] A pointer to a float to store the power consumption in Watts (W).

Returns

Returns 0 on success; returns a negative value on failure.

5.1.7. hm_sys_get_buildtime

int hm_sys_get_buildtime(char *buildtime, size_t len)

Retrieves the build time of the Houmo Dadao SDK as a string in the format YYYY-MM-DD HH:MM:SS.

Parameters

buildtime -- [out] A pointer to a buffer for storing the build time string.
len -- [in] The maximum size of the output buffer in bytes. The minimum supported value is 32 bytes.

Returns

Returns 0 on success; returns -1 on failure.

5.1.8. hm_sys_get_chip_revision

int hm_sys_get_chip_revision(int dev_index, int *revision)

Retrieves the M50 chip revision of a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
revision -- [out] Pointer to an integer to store the M50 chip revision.

Returns

Returns 0 on success; returns -1 on failure (e.g., invalid device index or unprogrammed eFuse).

Note

This function requires valid data in the Houmo device eFuse. The chip revision can be retrieved only if the eFuse has been programmed.

5.1.9. hm_sys_get_computing_power

int hm_sys_get_computing_power(int dev_index)

Retrieves the computing power (TFLOPS) of the specified Houmo logical device.

Parameters: dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns the computing power on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The computing power can be retrieved only if the eFuse has been programmed.

5.1.10. hm_sys_get_core_count

int hm_sys_get_core_count(int dev_index)

Retrieves the total number of IPU cores of the specified Houmo logical device.

Parameters: dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns the total number of IPU cores on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The number of IPU cores can be retrieved only if the eFuse has been programmed.

5.1.11. hm_sys_get_ctc_phy_id

int hm_sys_get_ctc_phy_id(int dev_index, int *group_id, int *chip_id)

Retrieves the CTC (Chip-to-Chip) PHY identifiers associated with the given Houmo logical device ID.

In configurations with multiple Houmo chips, Houmo chips interconnected via CTC form a logical group. Each group represents an independent CTC interconnection domain. Only chips belonging to the same group can establish physical CTC connections.

See also

hm_sys_check_device_index

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
group_id -- [out] Pointer to the group ID.
chip_id -- [out] Pointer to the chip ID.

Returns

Returns 0 on success; returns a negative value on failure.

5.1.12. hm_sys_get_ddr_chip_capacity

int hm_sys_get_ddr_chip_capacity(int dev_index, int *capacity)

Retrieves the capacity (in GB) of each DDR chip on a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
capacity -- [out] Pointer to an integer to store the capacity per DDR chip in GB.

Returns

Returns 0 on success; returns -1 on failure (e.g., invalid device index or unprogrammed eFuse).

Note

This function requires valid data in the Houmo device eFuse. The DDR chip capacity can be retrieved only if the eFuse has been programmed.

5.1.13. hm_sys_get_ddr_chip_quantity

int hm_sys_get_ddr_chip_quantity(int dev_index, int *quantity)

Retrieves the total number of DDR chips available on a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
quantity -- [out] Pointer to an integer to store the total DDR chip count.

Returns

Returns 0 on success; returns -1 on failure (e.g., invalid device index or unprogrammed eFuse).

Note

This function requires valid data in the Houmo device eFuse. The DDR chip quantity can be retrieved only if the eFuse has been programmed.

5.1.14. hm_sys_get_ddr_size

int hm_sys_get_ddr_size(int dev_index, uint64_t *ddr_size)

Retrieves the total DDR memory size (in bytes) of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
ddr_size -- [out] Pointer to the total DDR memory size in bytes.

Returns

Returns 0 on success; returns a negative value on failure.

Note

This function requires valid data in the Houmo device eFuse. The total DDR memory size can be retrieved only if the eFuse has been programmed.

5.1.15. hm_sys_get_device_info

uint32_t hm_sys_get_device_info(struct hm_device_info *info)

Retrieves information about all Houmo logical devices connected to the host.

Each M50 chip is identified as a unique logical device with its own logical ID. For Houmo products containing multiple M50 chips, this function returns the information for each chip.

Parameters: info -- [out] Pointer to an hm_device_info structure that holds the device information.
Returns: Returns the number of Houmo devices on success; returns 0 on failure.

5.1.16. hm_sys_get_device_name

int hm_sys_get_device_name(int dev_index, char name[], int len)

Retrieves the model name of a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
name -- [out] A pointer to a buffer for storing the model name.
len -- [in] The maximum size of the output buffer in bytes. The maximum value is HM_SYS_DEVICE_NAME_LEN. It is recommended to set this value to HM_SYS_DEVICE_NAME_LEN. If the buffer size is smaller than the model name length, the function returns an error.

Returns

Returns 0 on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The model name can be retrieved only if the eFuse has been programmed.

5.1.17. hm_sys_get_device_pn

int hm_sys_get_device_pn(int dev_index, char pn[], int len)

Retrieves the part number of a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Valid IDs can be get from struct hm_device_info::device_ids.
pn -- [out] A pointer to a buffer for storing the part number.
len -- [in] The maximum size of the output buffer in bytes. The maximum value is HM_SYS_DEVICE_PN_LEN. It is recommended to set this value to HM_SYS_DEVICE_PN_LEN. If the buffer size is smaller than the part number length, the function returns an error.

Returns

Returns 0 on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The part number can be retrieved only if the eFuse has been programmed.

5.1.18. hm_sys_get_device_sn

int hm_sys_get_device_sn(int dev_index, char sn[], int len)

Retrieves the serial number of a Houmo device with the specified logical ID.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
sn -- [out] A pointer to a buffer for storing the serial number.
len -- [in] The maximum size of the output buffer in bytes. The maximum value is HM_SYS_DEVICE_SN_LEN. It is recommended to set this value to HM_SYS_DEVICE_SN_LEN. If the buffer size is smaller than the serial number length, the function returns an error.

Returns

Returns 0 on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The serial number can be retrieved only if the eFuse has been programmed.

5.1.19. hm_sys_get_device_version

int hm_sys_get_device_version(int dev_index, char *version, size_t len)

Retrieves the firmware version of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
version -- [out] A pointer to a buffer for storing the firmware version string.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns -1 on failure.

5.1.20. hm_sys_get_driver_version

int hm_sys_get_driver_version(char *version, size_t len)

Retrieves the driver version string.

Parameters

version -- [out] A pointer to a buffer for storing the driver version string.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns -1 on failure.

Note

This function is supported only on Linux and Android systems. It is not supported on Windows.

5.1.21. hm_sys_get_dvfs_mode

int hm_sys_get_dvfs_mode(int dev_index, enum hm_dvfs_mode *mode)

Retrieves the current DVFS mode of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
mode -- [out] A pointer to an hm_dvfs_mode enum to store the current DVFS mode.

Returns

Returns 0 on success; returns a negative value on failure.

5.1.22. hm_sys_get_ipu_core_utili_rate

float hm_sys_get_ipu_core_utili_rate(int dev_index, uint32_t core_id)

Retrieves the real-time utilization rate of the specified IPU core on the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
core_id -- [in] The ID of the IPU core for which the utilization rate is retrieved.

Returns

Returns the real-time utilization rate of the specified IPU cores on success; returns a negative value on failure.

Note

This function requires valid data in the Houmo device eFuse. IPU core utilization rate can be retrieved only if the eFuse has been programmed.

5.1.23. hm_sys_get_ipu_frequency

int hm_sys_get_ipu_frequency(int dev_index, uint64_t *frequency)

Retrieves the real-time average frequency (Hz) of all IPU cores of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
frequency -- [out] Pointer to the frequency value in Hertz (Hz).

Returns

Returns 0 on success; returns -1 on failure.

5.1.24. hm_sys_get_ipu_utili_rate

float hm_sys_get_ipu_utili_rate(int dev_index)

Retrieves the real-time average utilization rate of all IPU cores of the specified Houmo logical device.

The return value is shown as a floating-point percentage value in the range 0.0 to 100.0.

Parameters: dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns the average utilization rate of all IPU cores on success; returns a negative value on failure.

Note

This function requires valid data in the Houmo device eFuse. IPU core utilization rate can be retrieved only if the eFuse has been programmed.

5.1.25. hm_sys_get_ipu_voltage

int hm_sys_get_ipu_voltage(int dev_index, float *voltage)

Retrieves the real-time average voltage (mV) of all IPU cores of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
voltage -- [out] Pointer to the voltage value in millivolts (mV).

Returns

Returns 0 on success; returns -1 on failure.

5.1.26. hm_sys_get_mem_info

int hm_sys_get_mem_info(int dev_index, struct hm_mem_info *mem_info)

Retrieves the DDR memory information of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
mem_info -- [out] Pointer to an hm_mem_info struct that holds the DDR memory information.

Returns

Returns 0 on success; returns -1 on failure.

5.1.27. hm_sys_get_temperature

int hm_sys_get_temperature(int dev_index, float *temp)

Retrieves the real-time temperature (°C) of the specified Houmo logical device.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
temp -- [out] Pointer to the temperature value in Celsius (°C).

Returns

Returns 0 on success; returns -1 on failure.

5.1.28. hm_sys_get_vendor_id

int hm_sys_get_vendor_id(int dev_index)

Retrieves the vendor ID of a Houmo device with the specified logical ID.

Parameters: dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns the vendor ID of the specified Houmo device on success; returns -1 on failure.

Note

This function requires valid data in the Houmo device eFuse. The vendor ID can be retrieved only if the eFuse has been programmed.

5.1.29. hm_sys_get_version

int hm_sys_get_version(char *version, size_t len)

Retrieves the version of the Houmo Dadao SDK.

Parameters

version -- [out] A pointer to a buffer for storing the version string.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns -1 on failure.

5.1.30. hm_sys_ipu_reset

int hm_sys_ipu_reset(int dev_id)

Resets the IPU subsystem of the specified Houmo logical device.

Parameters: dev_id -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
Returns: Returns 0 on success; returns a negative value on failure.

Note

This API must be invoked only when no synchronization operations are in progress on this device.

5.1.31. hm_sys_set_dvfs_mode

int hm_sys_set_dvfs_mode(int dev_index, enum hm_dvfs_mode mode)

Sets the DVFS mode for the specified M50 logical device of a Houmo product.

Note

After a power cycle, the system returns to the default HM_DVFS_PERFORMANCE mode.
The DVFS mode is configured per M50 logical device. Each M50 chip is treated as an M50 logical device. If a Houmo product contains more than one M50 chip, this function sets the DVFS mode only for the M50 logical device specified by the dev_index parameter.

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
mode -- [in] The DVFS mode to set. Valid values are HM_DVFS_PERFORMANCE and HM_DVFS_ONDEMAND.

Returns

Returns 0 on success; returns a negative value on failure.

5.2. Firmware Upgrade

5.2.1. hm_fw_get_version

int hm_fw_get_version(const char *fw_path, char version[], size_t len)

Retrieves the firmware version from a firmware image.

The firmware version consists of major, minor and patch components. For instance, if major is 2, minor is 0, and patch is 0, this API the string "v2.0.0".

Parameters

fw_path -- [in] Path to the firmware image firmware.img.
version -- [out] Pointer to an output buffer used to store the firmware version string. On success, the string is null-terminated.
len -- [in] The maximum size of the output buffer in bytes.

Returns

Returns 0 on success; returns a negative value on failure.

5.2.2. hm_fw_upgrade_deinit

hm_fw_upgrade_result_t hm_fw_upgrade_deinit(hm_fw_upgrade_ctx_t *ctx)

Destroys the firmware upgrade context and releases the upgrade resources for a Houmo logical device.

Example: See examples in hm_fw_upgrade_execute() and hm_fw_upgrade_start().

Parameters: ctx -- [in] The firmware upgrade context to destroy.
Returns: Returns HM_FW_UPGRADE_SUCCESS if the context is successfully destroyed; returns a hm_fw_upgrade_result_t error code on failure.

5.2.3. hm_fw_upgrade_execute

hm_fw_upgrade_result_t hm_fw_upgrade_execute(hm_fw_upgrade_ctx_t *ctx)

Executes a firmware upgrade synchronously.

This function performs the firmware upgrade in the calling thread and blocks until the upgrade process completes.

This API is used in the following scenarios:

Single-device synchronous upgrade.
User-managed thread upgrade, where the caller creates a thread and invokes this function within that thread.

Example: Single-device synchronous upgrade

// Initialize a firmware upgrade context
hm_fw_upgrade_ctx_t *ctx = hm_fw_upgrade_init(dev_index, fw_path);
if (!ctx) {
       fprintf(stderr, "[Sync] Dev %d: Init failed\n", dev_index);
       return -1;
}
printf("[Sync] Dev %d: Starting upgrade...\n", dev_index);
// Upgrade firmware synchronously
hm_fw_upgrade_result_t ret = hm_fw_upgrade_execute(ctx);
if (ret == HM_FW_UPGRADE_SUCCESS) {
    printf("Upgrade completed successfully.\n");
}
// Destroy the firmware upgrade context
hm_fw_upgrade_deinit(ctx);

Parameters: ctx -- [in] The firmware upgrade context.
Returns: Returns HM_FW_UPGRADE_SUCCESS indicates successful completion; returns a hm_fw_upgrade_result_t error code on failure.

Note

You must call hm_fw_upgrade_init() to initialize the firmware upgrade context before calling this API, and call hm_fw_upgrade_deinit() after the upgrade process completes to destroy the upgrade context and release resources.

5.2.4. hm_fw_upgrade_get_progress

hm_fw_upgrade_result_t hm_fw_upgrade_get_progress(hm_fw_upgrade_ctx_t *ctx, int *progress)

Retrieves the current firmware upgrade progress.

This function retrieves the current progress of an ongoing firmware upgrade operation in a thread-safe manner. Progress is reported on a scale from 0 to 10000, corresponding to 0.00% to 100.00%.

Example: See examples in hm_fw_upgrade_start().

Parameters

ctx -- [in] The firmware upgrade context.
progress -- [out] The current upgrade progress value

Returns

Returns a hm_fw_upgrade_result_t value indicating on success or failure.

5.2.5. hm_fw_upgrade_get_result

hm_fw_upgrade_result_t hm_fw_upgrade_get_result(hm_fw_upgrade_ctx_t *ctx)

Retrieve the firmware upgrade operation result.

This function returns the result code of the firmware upgrade operation associated with the specified context.

Example: See examples in hm_fw_upgrade_start().

Parameters: ctx -- [in] The firmware upgrade context.
Returns: Returns a hm_fw_upgrade_result_t value indicating the current status of the firmware upgrade operation.

5.2.6. hm_fw_upgrade_init

hm_fw_upgrade_ctx_t *hm_fw_upgrade_init(int dev_index, const char *fw_img)

Initializes a firmware upgrade context for a Houmo logical device.

Note

The context is allocated on the heap and must be released by calling hm_fw_upgrade_deinit() when no longer needed.

Example: See examples in hm_fw_upgrade_execute() and hm_fw_upgrade_start().

Parameters

dev_index -- [in] The logical ID of the Houmo device. Each physical M50 chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual M50 chip. Valid IDs can be get from hm_device_info::device_ids.
fw_img -- [in] Path to the firmware image firmware.img.

Returns

Returns a pointer to the initialized firmware upgrade context on success; returns NULL on failure.

5.2.7. hm_fw_upgrade_start

hm_fw_upgrade_result_t hm_fw_upgrade_start(hm_fw_upgrade_ctx_t *ctx)

Starts a firmware upgrade in asynchronous mode.

This function starts the firmware upgrade process and returns immediately. The upgrade is executed by an internal worker thread, which internally invokes hm_fw_upgrade_execute.

This API is used in the following scenarios:

Single-device asynchronous upgrade
Multi-device parallel upgrade, where one upgrade context is created per device and this function is called for each context

Example: Single-device asynchronous upgrade

// Initialize a firmware upgrade context
hm_fw_upgrade_ctx_t *ctx = hm_fw_upgrade_init(dev_index, fw_path);
if (!ctx) {
       fprintf(stderr, "[Sync] Dev %d: Init failed\n", dev_index);
}
printf("[Sync] Dev %d: Starting upgrade...\n", dev_index);
// Start to upgrade firmware synchronously
hm_fw_upgrade_result_t ret = hm_fw_upgrade_start(ctx);
if (ret != HM_FW_UPGRADE_SUCCESS) {
       fprintf(stderr, "[Async] Dev %d: Init failed\n", dev_index);
       hm_fw_upgrade_deinit(ctx);
}
// Poll progress and wait for completion
int progress = 0;
while (hm_fw_upgrade_get_result(ctx) == HM_FW_UPGRADE_SUCCESS) {
       ret = hm_fw_upgrade_get_progress(ctx, &progress);
       printf("\r[Async] Dev %d: Progress %.2f%%", dev_index,
              (float)progress / 100.0);
       fflush(stdout);
       if (progress >= 10000)
           break;
       usleep(500 * 1000);
}

// Fetch and display progress
ret = hm_fw_upgrade_get_result(ctx);
if (ret == HM_FW_UPGRADE_SUCCESS) {
       printf("[Async] Dev %d: Upgrade done\n", dev_index);
} else {
    fprintf(stderr, "[Async] Dev %d: Failed - %s\n", dev_index,
        upgrade_result_to_str(ret));
}
// Destroy the firmware upgrade context
hm_fw_upgrade_deinit(ctx);

Parameters: ctx -- [in] The firmware upgrade context.
Returns: Returns a hm_fw_upgrade_result_t value indicating if the upgrade process was successfully started.

Note

You must call hm_fw_upgrade_init() to initialize the firmware upgrade context before calling this API, and call hm_fw_upgrade_deinit() after the upgrade process completes to destroy the upgrade context and release resources.