tcim_lite.pydev_ctrl

Python bindings for the Houmo IPU Device Control HAL (Hardware Abstraction Layer).

This module provides a unified interface for system-level management of Houmo accelerators. It encapsulates core operations including hardware reset orchestration, DVFS (Dynamic Voltage and Frequency Scaling) configuration, and real-time hardware telemetry.

Architectural Features:

  • Late-binding Mechanism: To ensure maximum flexibility, this module does not link against vendor libraries at compile time. Instead, it utilizes a DynamicLoader to resolve backend-specific symbols only when a device instance is created.

  • Binary Decoupling: This 'plug-and-play' approach allows a single Python extension to support multiple backends (such as, M50, M30) without requiring the presence of all driver libraries during the initial import.

    Supported backends:

    • M30 products: Xh1HdiBackend

    • M50 products: Xh2HalBackend.

Operational Notes:

  • Entry Point: A HalDevice instance must be explicitly initialized via HalDeviceFactory.create before accessing any hardware features.

  • Feature Availability: If a specific backend does not support a requested operation, the API returns Status.UNSUPPORTED and logs a diagnostic error.

Data Types

enum DvfsMode

class DvfsMode(self: tcim_lite.pydev_ctrl.DvfsMode, value: int)

DVFS (Dynamic Voltage and Frequency Scaling) operating mode for the specified Houmo logical device.

Note: Not all backends support DVFS. Calling HalDevice.get_dvfs_mode or HalDevice.set_dvfs_mode on an unsupported platform returns Status.UNSUPPORTED.

Members:

PERFORMANCE : IPU cores always run at maximum frequency. This is the default mode.

ON_DEMAND : IPU core frequency is dynamically adjusted based on real-time utilization within the default range of 1400 MHz to 700 MHz.

enum Status

class tcim_lite.pydev_ctrl.Status

The return status of the functions.

Values:

ERR_UNDEFINED

An undefined or unknown internal error has occurred.

OK

This function returned with no errors.

UNINITIALIZED

This object or the related resource is not initialized.

OUT_OF_RANGE

The index or value passed to the function is out of range.

UNSUPPORTED

This function is not yet supported.

INVALID_ARGUMENT

One or more arguments passed to the function are invalid.

ALREADY_EXISTS

This error occurs when attempting to create an item that already exists.

PERMISSION_DENIED

Permission to perform the function denied.

UNAVAILABLE

The requested service or resource is temporarily unavailable.

UNAUTHENTICATED

Authentication is required to access the resource.

RESOURCE_EXHAUSTED

This error occurs when the resource limit, such as memory or disk space, has been reached or exceeded.

TIMEOUT

A timeout occurred while the function is waiting to be processed.

ERR_KERNEL

Internal error.

ERR_FATAL

A critical unrecoverable error occurred during model inference. The IPU core must be reset.

struct MemInfo

class MemInfo(self: tcim_lite.pydev_ctrl.MemInfo)

Structure that holds DDR memory information of a Houmo device.

property mem_avail

DDR memory available for the Houmo logical device in MB.

property mem_total

Total DDR memory of the Houmo logical device in MB.

property mem_used

DDR memory consumed by the Houmo logical device in MB.

Classes

HalDevice

class HalDevice

High-level Runtime interface for Houmo chip management.

Instances must be obtained exclusively via HalDeviceFactory.create.

property backend_name

HalDevice.backend_name

Name of the underlying HAL backend, such as 'Xh2HalBackend'.

get_device_count API

HalDevice.get_device_count(self: tcim_lite.pydev_ctrl.HalDevice) → int

Returns the number of available Houmo logical devices for the current backend.

Returns:

The total count of logical devices, or -1 if the backend fails to probe the hardware or is uninitialized.

Return type:

int

get_dvfs_mode API

HalDevice.get_dvfs_mode(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int) → tuple[tcim_lite.pytcim.Status, tcim_lite.pydev_ctrl.DvfsMode]

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

Parameters:

device_id -- 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:

A tuple of (Status, DvfsMode). Status is Status.OK on success, or Status.UNSUPPORTED if the backend does not provide DVFS controls.

get_ipu_frequency API

HalDevice.get_ipu_frequency(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int) → tuple[tcim_lite.pytcim.Status, int]

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

Parameters:

device_id -- 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:

A tuple of (Status, frequency_hz). Returns (Status.UNSUPPORTED, 0) if the backend does not expose frequency telemetry.

get_ipu_util_rate API

HalDevice.get_ipu_util_rate(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int) → tuple[tcim_lite.pytcim.Status, float]

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

Note:

  • The utilization is returned as a floating-point percentage (0.0 to 100.0).

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

Parameters:

device_id -- 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:

A tuple of (Status, util_rate). Returns (Status.UNSUPPORTED, 0.0) if utilization telemetry is not available on the current backend.

get_mem_info API

HalDevice.get_mem_info(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int) → tuple[tcim_lite.pytcim.Status, tcim_lite.pydev_ctrl.MemInfo]

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

Parameters:

device_id -- 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:

A tuple of (Status, MemInfo). Status is Status.OK on success, or Status.UNSUPPORTED if the backend does not expose memory telemetry.

ipu_reset API

HalDevice.ipu_reset(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int) → tcim_lite.pytcim.Status

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:

  1. Call HalDevice.register_pre_reset_callback API to define mandatory pre-reset operations, such as resource cleanup or buffer deallocation.

  2. Call HalDevice.register_post_reset_callback API to define post-reset operations, such as to state restoration or model reloading.

  3. Call this API to reset the specified Houmo logical device.

See example in HalDevice for more information.

Notes:

  • 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.

Parameters:

device_id -- 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 expose a hardware reset API.

register_post_reset_callback API

HalDevice.register_post_reset_callback(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int, callback: object) → int

Registers a callback to be invoked automatically by ipu_reset after a device reset completes.

Parameters:

  • device_id -- 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.

  • callback -- A 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 (int) that can be passed to unregister_reset_callback.

register_pre_reset_callback API

HalDevice.register_pre_reset_callback(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int, callback: object) → int

Registers a callback to be invoked automatically by ipu_reset before a device reset.

Parameters:

  • device_id -- 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.

  • callback -- A 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 (int) that can be passed to unregister_reset_callback.

set_dvfs_mode API

HalDevice.set_dvfs_mode(self: tcim_lite.pydev_ctrl.HalDevice, device_id: int, mode: tcim_lite.pydev_ctrl.DvfsMode) → tcim_lite.pytcim.Status

Sets the DVFS mode for the specified Houmo logical device.

Note:

  • After a power cycle, the system returns to the default PERFORMANCE mode.

  • The mode is configured per Houmo logical device. If a product contains multiple chips, this only affects the device specified by device_id.

Parameters:

  • device_id -- 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 -- The DVFS mode to set. Valid values are PERFORMANCE and ON_DEMAND.

Returns:

Status.OK on success, or Status.UNSUPPORTED if controls are missing.

unregister_reset_callback API

HalDevice.unregister_reset_callback(self: tcim_lite.pydev_ctrl.HalDevice, handle: int) → None

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 ipu_reset operations.

Parameters:

handle -- The unique handle returned by register_pre_reset_callback or register_post_reset_callback. If the handle is unknown or has already been unregistered, this function has no effect.

HalDeviceFactory

class HalDeviceFactory

Entry point for instantiating HalDevice objects.

This factory manages the instantiation of Houmo device backends.

Example:

dev = tcim_lite.dev_ctrl.HalDeviceFactory.create('Xh2HalBackend')
dev = tcim_lite.dev_ctrl.HalDeviceFactory.create()  # use default backend
backends = tcim_lite.dev_ctrl.HalDeviceFactory.get_supported_backends()

create API

static HalDeviceFactory.create(backend_name: str = '') → tcim_lite.pydev_ctrl.HalDevice

Creates a HalDevice instance for the specified backend.

Backend Selection Logic:

  1. If backend_name is provided, the specific backend is used.

  2. 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 (str) -- The name of the backend. Defaults to empty.

Returns:

A HalDevice instance, or None if the requested backend is not compiled in or unavailable.

Return type:

HalDevice

get_supported_backends API

static HalDeviceFactory.get_supported_backends() → list[str]

Retrieves the list of backends available in the current build.

Returns:

A list of available backend name strings.

Return type:

list[str]