feature: Add more APIs to L0 Sysman python binding

aviralni · aviralni · commit 7b1ab039179d · 2026-05-19T07:33:04.000+05:30
Related-To: NEO-18602

Add following apis to python:
1. zesFrequencyGetProperties
2. zesPowerGetProperties
3. zesPowerGetUsage

Signed-off-by: Aviral Nigam &lt;aviral.nigam@intel.com&gt;
diff --git a/bindings/sysman/python/source/examples/pyzes_black_box_test.py b/bindings/sysman/python/source/examples/pyzes_black_box_test.py
@@ -638,7 +638,7 @@ def test_memory_modules(device_handle, device_index):
 
 
 def test_power_module(device_handle, device_index):
-    """Test power domain enumeration and energy counter operations"""
+    """Test power domain enumeration, usage, and energy counter operations"""
     print(f"\n---- Device {device_index} Power Domains Test ----")
 
     # Get power domain count
@@ -665,6 +665,36 @@ def test_power_module(device_handle, device_index):
     for i in range(power_count.value):
         print_verbose(f"\n  Power Domain {i}:")
 
+        power_props = pz.zes_power_properties_t()
+        power_props.stype = pz.ZES_STRUCTURE_TYPE_POWER_PROPERTIES
+        power_props.pNext = None
+
+        rc = pz.zesPowerGetProperties(power_handles[i], byref(power_props))
+        if check_rc(f"zesPowerGetProperties(power {i})", rc):
+            print_verbose("    Properties:")
+            print_verbose(f"      On Subdevice: {bool(power_props.onSubdevice)}")
+            print_verbose(f"      Subdevice ID: {power_props.subdeviceId}")
+            print_verbose(f"      Can Control: {bool(power_props.canControl)}")
+            print_verbose(
+                "      Energy Threshold Supported: "
+                f"{bool(power_props.isEnergyThresholdSupported)}"
+            )
+            print_verbose(f"      Default Limit: {power_props.defaultLimit}")
+            print_verbose(f"      Min Limit: {power_props.minLimit}")
+            print_verbose(f"      Max Limit: {power_props.maxLimit}")
+
+        # Test power usage
+        instant_power = c_uint32(0)
+        average_power = c_uint32(0)
+
+        rc = pz.zesPowerGetUsage(
+            power_handles[i], byref(instant_power), byref(average_power)
+        )
+        if check_rc(f"zesPowerGetUsage(power {i})", rc):
+            print_verbose("    Usage:")
+            print_verbose(f"      Instant Power: {instant_power.value}")
+            print_verbose(f"      Average Power: {average_power.value}")
+
         # Test power energy counter
         energy_counter = pz.zes_power_energy_counter_t()
 
@@ -726,6 +756,37 @@ def test_frequency_domains(device_handle, device_index):
     for i in range(freq_count.value):
         print_verbose(f"\n  Frequency Domain {i}:")
 
+        # Test frequency properties
+        freq_props = pz.zes_freq_properties_t()
+        freq_props.stype = pz.ZES_STRUCTURE_TYPE_FREQ_PROPERTIES
+        freq_props.pNext = None
+
+        rc = pz.zesFrequencyGetProperties(freq_handles[i], byref(freq_props))
+        if not check_rc(f"zesFrequencyGetProperties(frequency {i})", rc):
+            continue
+
+        print_verbose("    Frequency Properties:")
+        print_verbose(
+            f"      Domain Type: {get_frequency_domain_string(freq_props.type)}"
+        )
+        print_verbose(f"      On Subdevice: {bool(freq_props.onSubdevice)}")
+        print_verbose(f"      Subdevice ID: {freq_props.subdeviceId}")
+        print_verbose(f"      Can Control: {bool(freq_props.canControl)}")
+        print_verbose(
+            "      Throttle Event Supported: "
+            f"{bool(freq_props.isThrottleEventSupported)}"
+        )
+        print_verbose(
+            f"      Min Frequency: {freq_props.min:.1f}"
+            if freq_props.min >= 0
+            else "      Min Frequency: Unknown"
+        )
+        print_verbose(
+            f"      Max Frequency: {freq_props.max:.1f}"
+            if freq_props.max >= 0
+            else "      Max Frequency: Unknown"
+        )
+
         # Test frequency state
         freq_state = pz.zes_freq_state_t()
         freq_state.stype = pz.ZES_STRUCTURE_TYPE_FREQ_STATE
diff --git a/bindings/sysman/python/source/pyzes.py b/bindings/sysman/python/source/pyzes.py
@@ -478,6 +478,28 @@ class zes_mem_bandwidth_t(_PrintableStructure):
 
 
 ## Power structures ##
+class zes_power_properties_t(_PrintableStructure):
+    _fields_ = [
+        ("stype", c_int32),  # ZES_STRUCTURE_TYPE_POWER_PROPERTIES
+        ("pNext", c_void_p),
+        ("onSubdevice", ze_bool_t),  # is on subdevice
+        ("subdeviceId", c_uint32),  # subdevice ID
+        ("canControl", ze_bool_t),  # software-controllable power domain
+        (
+            "isEnergyThresholdSupported",
+            ze_bool_t,
+        ),  # supports energy threshold crossed event
+        ("defaultLimit", c_int32),  # default power limit in milliwatts
+        ("minLimit", c_int32),  # minimum power limit in milliwatts
+        ("maxLimit", c_int32),  # maximum power limit in milliwatts
+    ]
+    _fmt_ = {
+        "defaultLimit": "%d mW",
+        "minLimit": "%d mW",
+        "maxLimit": "%d mW",
+    }
+
+
 class zes_power_energy_counter_t(_PrintableStructure):
     _fields_ = [
         ("energy", c_uint64),  # monotonic energy counter in microjoules
@@ -487,6 +509,21 @@ class zes_power_energy_counter_t(_PrintableStructure):
 
 
 ## Frequency structures ##
+class zes_freq_properties_t(_PrintableStructure):
+    _fields_ = [
+        ("stype", c_int32),  # ZES_STRUCTURE_TYPE_FREQ_PROPERTIES
+        ("pNext", c_void_p),
+        ("type", zes_freq_domain_t),  # frequency domain type
+        ("onSubdevice", ze_bool_t),  # is on subdevice
+        ("subdeviceId", c_uint32),  # subdevice ID
+        ("canControl", ze_bool_t),  # software-controllable frequency domain
+        ("isThrottleEventSupported", ze_bool_t),  # supports throttled event
+        ("min", c_double),  # minimum hardware clock in MHz
+        ("max", c_double),  # maximum non-overclock hardware clock in MHz
+    ]
+    _fmt_ = {"min": "%.1f MHz", "max": "%.1f MHz"}
+
+
 class zes_freq_state_t(_PrintableStructure):
     _fields_ = [
         ("stype", c_int32),  # ZES_STRUCTURE_TYPE_FREQ_STATE
@@ -819,6 +856,25 @@ def zesDeviceEnumPowerDomains(hDevice, pCount, phPower):
     return retVal
 
 
+def zesPowerGetProperties(hPower, pProperties):
+        """Wraps API:
+        ze_result_t zesPowerGetProperties(
+                zes_pwr_handle_t hPower,
+                zes_power_properties_t* pProperties)
+
+        Parameters:
+            hPower: power handle
+            pProperties: POINTER(zes_power_properties_t) - properties structure to fill
+        Returns:
+            ze_result_t - return code only, properties are filled into pProperties
+        """
+        funcPtr = getFunctionPointerList("zesPowerGetProperties")
+        funcPtr.argtypes = [zes_pwr_handle_t, POINTER(zes_power_properties_t)]
+        funcPtr.restype = ze_result_t
+        retVal = funcPtr(hPower, pProperties)
+        return retVal
+
+
 def zesPowerGetEnergyCounter(hPower, pEnergy):
     """Wraps API:
     ze_result_t zesPowerGetEnergyCounter(
@@ -839,6 +895,28 @@ def zesPowerGetEnergyCounter(hPower, pEnergy):
     return retVal
 
 
+def zesPowerGetUsage(hPower, pInstantPower, pAveragePower):
+        """Wraps API:
+        ze_result_t zesPowerGetUsage(
+                zes_pwr_handle_t hPower,
+                uint32_t* pInstantPower,
+                uint32_t* pAveragePower)
+
+        Parameters:
+            hPower: power handle
+            pInstantPower: POINTER(c_uint32) - instant power in milliwatts
+            pAveragePower: POINTER(c_uint32) - average power in milliwatts
+        Returns:
+            ze_result_t - return code only, usage values are filled into the output pointers
+        """
+        funcPtr = getFunctionPointerList("zesPowerGetUsage")
+        funcPtr.argtypes = [zes_pwr_handle_t, POINTER(c_uint32), POINTER(c_uint32)]
+        funcPtr.restype = ze_result_t
+
+        retVal = funcPtr(hPower, pInstantPower, pAveragePower)
+        return retVal
+
+
 ## Frequency module functions ##
 def zesDeviceEnumFrequencyDomains(hDevice, pCount, phFrequency):
     """Wraps API:
@@ -863,6 +941,26 @@ def zesDeviceEnumFrequencyDomains(hDevice, pCount, phFrequency):
     return retVal
 
 
+def zesFrequencyGetProperties(hFrequency, pProperties):
+    """Wraps API:
+    ze_result_t zesFrequencyGetProperties(
+            zes_freq_handle_t hFrequency,
+            zes_freq_properties_t* pProperties)
+
+    Parameters:
+      hFrequency: frequency handle
+      pProperties: POINTER(zes_freq_properties_t) - properties structure to fill
+    Returns:
+      ze_result_t - return code only, properties are filled into pProperties
+    """
+    funcPtr = getFunctionPointerList("zesFrequencyGetProperties")
+    funcPtr.argtypes = [zes_freq_handle_t, POINTER(zes_freq_properties_t)]
+    funcPtr.restype = ze_result_t
+
+    retVal = funcPtr(hFrequency, pProperties)
+    return retVal
+
+
 def zesFrequencyGetState(hFrequency, pState):
     """Wraps API:
     ze_result_t zesFrequencyGetState(
diff --git a/bindings/sysman/python/test/unit_tests/test_frequency.py b/bindings/sysman/python/test/unit_tests/test_frequency.py
@@ -87,6 +87,51 @@ def mock_get_state(frequency_handle, state_ptr):
         mock_get_func.assert_called_with("zesFrequencyGetState")
         mock_func.assert_called_once()
 
+    def test_GivenValidFrequencyHandleWhenCallingZesFrequencyGetPropertiesThenCallSucceedsWithProperties(
+        self, mock_get_func
+    ):
+        mock_type = self.pyzes.ZES_FREQ_DOMAIN_GPU
+        mock_on_subdevice = 1
+        mock_subdevice_id = 0
+        mock_can_control = 1
+        mock_throttle_event_supported = 1
+        mock_min = 300.0
+        mock_max = 2100.0
+
+        def mock_get_properties(frequency_handle, properties_ptr):
+            properties_ptr._obj.type = mock_type
+            properties_ptr._obj.onSubdevice = mock_on_subdevice
+            properties_ptr._obj.subdeviceId = mock_subdevice_id
+            properties_ptr._obj.canControl = mock_can_control
+            properties_ptr._obj.isThrottleEventSupported = (
+                mock_throttle_event_supported
+            )
+            properties_ptr._obj.min = mock_min
+            properties_ptr._obj.max = mock_max
+            return self.pyzes.ZE_RESULT_SUCCESS
+
+        mock_func = MagicMock(side_effect=mock_get_properties)
+        mock_get_func.return_value = mock_func
+
+        frequency_handle = self.pyzes.zes_freq_handle_t()
+        freq_properties = self.pyzes.zes_freq_properties_t()
+        result = self.pyzes.zesFrequencyGetProperties(
+            frequency_handle, byref(freq_properties)
+        )
+
+        self.assertEqual(result, self.pyzes.ZE_RESULT_SUCCESS)
+        self.assertEqual(freq_properties.type, mock_type)
+        self.assertEqual(freq_properties.onSubdevice, mock_on_subdevice)
+        self.assertEqual(freq_properties.subdeviceId, mock_subdevice_id)
+        self.assertEqual(freq_properties.canControl, mock_can_control)
+        self.assertEqual(
+            freq_properties.isThrottleEventSupported, mock_throttle_event_supported
+        )
+        self.assertEqual(freq_properties.min, mock_min)
+        self.assertEqual(freq_properties.max, mock_max)
+        mock_get_func.assert_called_with("zesFrequencyGetProperties")
+        mock_func.assert_called_once()
+
 
 if __name__ == "__main__":
     unittest.main()
diff --git a/bindings/sysman/python/test/unit_tests/test_power.py b/bindings/sysman/python/test/unit_tests/test_power.py
@@ -74,6 +74,70 @@ def mock_get_energy(power_handle, energy_ptr):
         mock_get_func.assert_called_with("zesPowerGetEnergyCounter")
         mock_func.assert_called_once()
 
+    def test_GivenValidPowerHandleWhenCallingZesPowerGetUsageThenCallSucceedsWithUsageData(
+        self, mock_get_func
+    ):
+        mock_instant_power = 42000
+        mock_average_power = 38000
+
+        def mock_get_usage(power_handle, instant_ptr, average_ptr):
+            instant_ptr._obj.value = mock_instant_power
+            average_ptr._obj.value = mock_average_power
+            return self.pyzes.ZE_RESULT_SUCCESS
+
+        mock_func = MagicMock(side_effect=mock_get_usage)
+        mock_get_func.return_value = mock_func
+
+        power_handle = self.pyzes.zes_pwr_handle_t()
+        instant_power = c_uint32(0)
+        average_power = c_uint32(0)
+
+        result = self.pyzes.zesPowerGetUsage(
+            power_handle, byref(instant_power), byref(average_power)
+        )
+
+        self.assertEqual(result, self.pyzes.ZE_RESULT_SUCCESS)
+        self.assertEqual(instant_power.value, mock_instant_power)
+        self.assertEqual(average_power.value, mock_average_power)
+        mock_get_func.assert_called_with("zesPowerGetUsage")
+        mock_func.assert_called_once()
+
+    def test_GivenValidPowerHandleWhenCallingZesPowerGetPropertiesThenCallSucceedsWithProperties(
+        self, mock_get_func
+    ):
+        mock_default_limit = 150000
+        mock_min_limit = 100000
+        mock_max_limit = 225000
+
+        def mock_get_properties(power_handle, properties_ptr):
+            properties_ptr._obj.onSubdevice = True
+            properties_ptr._obj.subdeviceId = 1
+            properties_ptr._obj.canControl = True
+            properties_ptr._obj.isEnergyThresholdSupported = True
+            properties_ptr._obj.defaultLimit = mock_default_limit
+            properties_ptr._obj.minLimit = mock_min_limit
+            properties_ptr._obj.maxLimit = mock_max_limit
+            return self.pyzes.ZE_RESULT_SUCCESS
+
+        mock_func = MagicMock(side_effect=mock_get_properties)
+        mock_get_func.return_value = mock_func
+
+        power_handle = self.pyzes.zes_pwr_handle_t()
+        properties = self.pyzes.zes_power_properties_t()
+
+        result = self.pyzes.zesPowerGetProperties(power_handle, byref(properties))
+
+        self.assertEqual(result, self.pyzes.ZE_RESULT_SUCCESS)
+        self.assertEqual(properties.onSubdevice, True)
+        self.assertEqual(properties.subdeviceId, 1)
+        self.assertEqual(properties.canControl, True)
+        self.assertEqual(properties.isEnergyThresholdSupported, True)
+        self.assertEqual(properties.defaultLimit, mock_default_limit)
+        self.assertEqual(properties.minLimit, mock_min_limit)
+        self.assertEqual(properties.maxLimit, mock_max_limit)
+        mock_get_func.assert_called_with("zesPowerGetProperties")
+        mock_func.assert_called_once()
+
 
 if __name__ == "__main__":
     unittest.main()
