Classes

Class HalDevice

class HalDevice

High-level Runtime interface for Houmo chip management.

This class abstracts the underlying driver-level complexity, providing the Runtime layer with a standardized interface for device control and real-time monitoring. It acts as a safety and orchestration layer between user applications and the kernel-mode driver.

Key Characteristics

These device management APIs are dedicated to device management. It is completely separate from the inference APIs.
Instances must be obtained exclusively via HalDeviceFactory::Create. You cannot instantiate this class directly.

Reset Lifecycle

To ensure a safe and consistent state transition, the following lifecycle requirements must be observed when calling HalDevice::IpuReset to reset the IPU subsystem of the specified Houmo logical device:

All inference resources such as, Module, Buffer, Stream, associated with the target device_id must be released before the reset.
Register a pre-reset callback to trigger automated cleanup or state-saving just before the device reset begins.
Register a post-reset callback to handle the re-initialization of device states and reload models once the device is back.

The example of reset a Houmo logical device is as follows:

// Initialize the HalDevice class instance
auto dev = tcim::dev_ctrl::HalDeviceFactory::Create();
auto pre = dev->RegisterPreResetCallback(0, [](int id) {
  // destroy all Module / Buffer objects on device id
});
auto post = dev->RegisterPostResetCallback(0, [](int id) {
  // reload models on device id
});
dev->IpuReset(0);   // fires pre-callback -> hw reset -> post-callback
dev->UnregisterResetCallback(pre);
dev->UnregisterResetCallback(post);

~HalDevice

virtual tcim::dev_ctrl::HalDevice::~HalDevice() = default: Destructor.

GetBackendName

virtual std::string tcim::dev_ctrl::HalDevice::GetBackendName() const = 0

Retrieves the backend name of the current HalDevice object.

Returns:: Returns the current backend name string, such as "Xh2HalBackend".

Note

Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

GetDeviceCount

virtual int tcim::dev_ctrl::HalDevice::GetDeviceCount() = 0

Retrieves the number of available Houmo logical devices for this backend.

Returns:: Non-negative device count, or -1 on error if an error occurs.

GetDvfsMode

virtual Status tcim::dev_ctrl::HalDevice::GetDvfsMode(int device_id, DvfsMode *mode) = 0

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

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
mode -- [out] A pointer to an DvfsMode enum to store the current DVFS mode.

Returns:

Status::OK on success, Status::UNSUPPORTED if the backend does not provide DVFS controls.

Note

Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

GetIpuFrequency

virtual Status tcim::dev_ctrl::HalDevice::GetIpuFrequency(int device_id, uint64_t *frequency) = 0

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

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
frequency -- [out] Pointer to the frequency value in Hertz (Hz).

Returns:

Status::OK on success, Status::UNSUPPORTED if the backend does not expose frequency telemetry.

Note

Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

GetIpuUtilRate

virtual Status tcim::dev_ctrl::HalDevice::GetIpuUtilRate(int device_id, float *util_rate) = 0

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:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
util_rate -- [out] the real-time average utilization rate of all IPU cores.

Returns:

Status::OK on success, Status::UNSUPPORTED if the backend does not expose utilization telemetry.

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.
Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

GetMemInfo

virtual Status tcim::dev_ctrl::HalDevice::GetMemInfo(int device_id, MemInfo *mem_info) = 0

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

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
mem_info -- [out] Pointer to an MemInfo struct that holds the DDR memory information.

Returns:

Status::OK on success, Status::UNSUPPORTED if the backend does not expose memory telemetry.

Note

Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

IpuReset

virtual Status tcim::dev_ctrl::HalDevice::IpuReset(int device_id) = 0

Resets the IPU subsystem of the specified Houmo logical device.

This API coordinates the device reset sequence and triggers the registered lifecycle callbacks. It ensures the chip is returned to a clean state and is ready for model re-initialization.

To ensure a successful reset, you must:

Call HalDevice::RegisterPreResetCallback to define mandatory pre-reset operations, such as resource cleanup or buffer deallocation.
Call HalDevice::RegisterPostResetCallback to define post-reset operations, such as to state restoration or model reloading.
Call this API to reset the specified Houmo logical device.

See example in HalDevice for more information.

Parameters:: device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
Returns:: Status::OK on success, Status::UNSUPPORTED if the backend does not provide an IPU reset API.

Note

All Module and Buffer resources on the device must be released before calling this API to reset device (use pre-reset callbacks).
This API must be invoked only when no synchronization operations are in progress on this device.
This is a synchronous call; it will block until all three phases of the sequence are successfully completed.

RegisterPostResetCallback

virtual ResetCallbackHandle tcim::dev_ctrl::HalDevice::RegisterPostResetCallback(int device_id, ResetCallback cb) = 0

Registers a callback to be invoked automatically by HalDevice::IpuReset after a device reset completes.

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
cb -- [in] Callable invoked with device_id immediately after device reset completes. Implementation must be non-blocking to ensure the reset orchestration is not stalled.

Returns:

A ResetCallbackHandle for revocation.

Returns:

An opaque handle that can be passed to HalDevice::UnregisterResetCallback.

RegisterPreResetCallback

virtual ResetCallbackHandle tcim::dev_ctrl::HalDevice::RegisterPreResetCallback(int device_id, ResetCallback cb) = 0

Registers a callback to be invoked automatically by HalDevice::IpuReset before a device reset.

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
cb -- [in] Callable invoked with device_id immediately prior to device reset. Implementation must be non-blocking to ensure the reset orchestration is not stalled.

Returns:

An opaque handle that can be passed to HalDevice::UnregisterResetCallback.

SetDvfsMode

virtual Status tcim::dev_ctrl::HalDevice::SetDvfsMode(int device_id, DvfsMode mode) = 0

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

Note

After a power cycle, the system returns to the default DvfsMode::kPerformance mode.
The DVFS mode is configured per Houmo logical device. Each Houmo chip is treated as an Houmo logical device. If a Houmo product contains more than one Houmo chip, this function sets the DVFS mode only for the Houmo logical device specified by the device_id parameter.
Before calling this method, you must call HalDeviceFactory::Create to obtain a valid HalDevice instance.

Parameters:

device_id -- [in] The logical ID of the Houmo device. Each physical Houmo chip is identified as an independent logical device. On a multi-chip product, the system assigns a separate logical ID to every individual Houmo chip.
mode -- [in] The DVFS mode to set. Valid values are DvfsMode::kPerformance and DvfsMode::kOnDemand.

Returns:

Status::OK on success, Status::UNSUPPORTED if the backend does not provide DVFS controls.

UnregisterResetCallback

virtual void tcim::dev_ctrl::HalDevice::UnregisterResetCallback(ResetCallbackHandle handle) = 0

Unregisters a previously registered reset callback.

This method removes the specified functional hook from the reset orchestration sequence. Once unregistered, the callback will no longer be invoked during subsequent HalDevice::IpuReset operations.

Parameters:: handle -- [in] The unique handle returned by HalDevice::RegisterPreResetCallback or HalDevice::RegisterPostResetCallback. If the handle is unknown or has already been unregistered, this function has no effect.

Class HalDeviceFactory

class HalDeviceFactory

Entry point for instantiating HalDevice objects.

This factory manages the instantiation of Houmo device backends.

Example of instantiating a HalDevice object is as follows:

auto dev = tcim::dev_ctrl::HalDeviceFactory::Create("Xh2HalBackend");
DvfsMode mode;
dev->GetDvfsMode(0, &mode);
dev->SetDvfsMode(0, DvfsMode::kOnDemand);

Create

static std::shared_ptr<HalDevice> tcim::dev_ctrl::HalDeviceFactory::Create(const std::string &backend_name = "")

Creates a HalDevice instance for the specified backend.

Backend Selection Logic:

If backend_name is provided, the specific backend is used.
If backend_name is empty, the backend is determined based on the current environment configuration, typically using:
- The TCIM_BACKEND environment variable.
- The TCIM_DEFAULT_BACKEND build-time definition.

Parameters:: backend_name -- [in] The backend name, default is an empty string.
Returns:: A std::shared_ptr to the HalDevice instance, or nullptr if the requested backend is not compiled in or unavailable.

GetSupportedBackends

static std::vector<std::string> tcim::dev_ctrl::HalDeviceFactory::GetSupportedBackends()

Retrieves the list of backend available in the current build.

Returns:: A vector of available backend name strings.