feature: Add more APIs to L0 Sysman python binding

Related-To: NEO-18602

Added following APIs to python binding:

1. zesDevicePciGetProperties
2. zesDevicePciGetStats
3. zesDeviceEccAvailable
4. zesDeviceEccConfigurable
5. zesDeviceGetEccState
6. zesDeviceSetEccState
7. zesPowerGetLimitsExt
8. zesPowerSetLimitsExt
9. zesFrequencyGetAvailableClocks
10. zesFrequencyGetRange
11. zesFrequencySetRange
12. zesFrequencyGetThrottleTime
13. zesDevicePciGetState
14. zesPowerGetProperties

Signed-off-by: Aviral Nigam <aviral.nigam@intel.com>

Author: aviralni

bindings/sysman/python/source/examples/pyzes_black_box_test.py

@@ -13,6 +13,7 @@
 import argparse
 import os
 import sys
+import time
 from ctypes import *
 
 # Add the source directory to Python path so we can import pyzes
@@ -912,7 +913,7 @@ def test_memory_modules(device_handle, device_index):
 
 
 def test_power_module(device_handle, device_index):
-    """Test power domain enumeration, energy counter, and power limit extension operations"""
+    """Test power domain enumeration, properties, energy-derived power, and power limit extension operations"""
     print(f"\n---- Device {device_index} Power Domains Test ----")
 
     # Get power domain count
@@ -939,6 +940,33 @@ def test_power_module(device_handle, device_index):
     for i in range(power_count.value):
         print_verbose(f"\n  Power Domain {i}:")
 
+        default_limit = pz.zes_power_limit_ext_desc_t()
+        ext_properties = pz.zes_power_ext_properties_t()
+        ext_properties.stype = pz.ZES_STRUCTURE_TYPE_POWER_EXT_PROPERTIES
+        ext_properties.pNext = None
+        ext_properties.defaultLimit = pointer(default_limit)
+
+        properties = pz.zes_power_properties_t()
+        properties.stype = pz.ZES_STRUCTURE_TYPE_POWER_PROPERTIES
+        properties.pNext = cast(pointer(ext_properties), c_void_p)
+
+        rc = pz.zesPowerGetProperties(power_handles[i], byref(properties))
+        if not check_rc(f"zesPowerGetProperties(power {i})", rc):
+            continue
+
+        print_verbose("    Power Properties:")
+        print_verbose(f"      On Subdevice: {bool(properties.onSubdevice)}")
+        if properties.onSubdevice:
+            print_verbose(f"      Subdevice ID: {properties.subdeviceId}")
+        print_verbose(f"      Can Control: {bool(properties.canControl)}")
+        print_verbose(
+            f"      Energy Threshold Supported: {bool(properties.isEnergyThresholdSupported)}"
+        )
+        print_verbose(f"      Default Limit: {properties.defaultLimit}")
+        print_verbose(f"      Min Limit: {properties.minLimit}")
+        print_verbose(f"      Max Limit: {properties.maxLimit}")
+        print_verbose(f"      Domain: {get_power_domain_string(ext_properties.domain)}")
+
         limit_count = c_uint32(0)
         rc = pz.zesPowerGetLimitsExt(power_handles[i], byref(limit_count), None)
         if not check_rc(f"zesPowerGetLimitsExt(power {i}, count)", rc):
@@ -989,31 +1017,26 @@ def test_power_module(device_handle, device_index):
                 )
                 print_verbose(f"        Limit: {limit_desc.limit}")
 
-        # Test power energy counter
-        energy_counter = pz.zes_power_energy_counter_t()
-
-        rc = pz.zesPowerGetEnergyCounter(power_handles[i], byref(energy_counter))
-        if not check_rc(f"zesPowerGetEnergyCounter(power {i})", rc):
+        energy_counter1 = pz.zes_power_energy_counter_t()
+        rc = pz.zesPowerGetEnergyCounter(power_handles[i], byref(energy_counter1))
+        if not check_rc(f"zesPowerGetEnergyCounter(power {i}, first)", rc):
             continue
 
-        print_verbose("    Energy Counter:")
-        print_verbose(f"      Energy: {energy_counter.energy}")
-        print_verbose(f"      Timestamp: {energy_counter.timestamp} microseconds")
-
-        # Take a second reading after a small delay
-        import time
-
-        time.sleep(0.01)  # 10ms delay
+        time.sleep(1)
 
         energy_counter2 = pz.zes_power_energy_counter_t()
-        ret2 = pz.zesPowerGetEnergyCounter(power_handles[i], byref(energy_counter2))
-        if ret2 == pz.ZE_RESULT_SUCCESS:
-            energy_delta = energy_counter2.energy - energy_counter.energy
-            time_delta = energy_counter2.timestamp - energy_counter.timestamp
-            if time_delta > 0:
-                print_verbose(
-                    f"    Energy Delta: {energy_delta} over {time_delta} microseconds"
-                )
+        rc = pz.zesPowerGetEnergyCounter(power_handles[i], byref(energy_counter2))
+        if not check_rc(f"zesPowerGetEnergyCounter(power {i}, second)", rc):
+            continue
+
+        energy_delta = energy_counter2.energy - energy_counter1.energy
+        time_delta = energy_counter2.timestamp - energy_counter1.timestamp
+        if time_delta > 0:
+            power_watt = energy_delta / time_delta
+            device_scope = "subDevice" if properties.onSubdevice else "rootDevice"
+            print_verbose(f"    Current Power: {power_watt:.6f} W for {device_scope}")
+        else:
+            print_verbose("    Current Power: unavailable due to zero delta time")
 
         if limit_descs is None:
             continue
@@ -1029,9 +1052,7 @@ def test_power_module(device_handle, device_index):
         if not check_rc(f"zesPowerSetLimitsExt(power {i})", rc):
             return False
 
-        print_verbose(
-            f"    Re-applied {set_count.value} power limit descriptor(s) successfully"
-        )
+        print_verbose(f"    Set power limit successfully")
 
     return True
 
@@ -1100,15 +1121,6 @@ def test_frequency_domains(device_handle, device_index):
         print_verbose(f"      Min: {freq_range.min:.1f} MHz")
         print_verbose(f"      Max: {freq_range.max:.1f} MHz")
 
-        throttle_time = pz.zes_freq_throttle_time_t()
-        rc = pz.zesFrequencyGetThrottleTime(freq_handles[i], byref(throttle_time))
-        if not check_rc(f"zesFrequencyGetThrottleTime(frequency {i})", rc):
-            continue
-
-        print_verbose("    Throttle Time:")
-        print_verbose(f"      Throttle Time: {throttle_time.throttleTime}")
-        print_verbose(f"      Timestamp: {throttle_time.timestamp} microseconds")
-
         # Test frequency state
         freq_state = pz.zes_freq_state_t()
         freq_state.stype = pz.ZES_STRUCTURE_TYPE_FREQ_STATE

bindings/sysman/python/source/pyzes.py

@@ -355,6 +355,7 @@ class zes_engine_handle_t(c_void_p):
 # Structure type enum values
 ZES_STRUCTURE_TYPE_DEVICE_PROPERTIES = 0x1
 ZES_STRUCTURE_TYPE_PCI_PROPERTIES = 0x2
+ZES_STRUCTURE_TYPE_POWER_PROPERTIES = 0xD
 ZES_STRUCTURE_TYPE_PCI_STATE = 0x17
 ZES_STRUCTURE_TYPE_DEVICE_ECC_DESC = 0x25
 ZES_STRUCTURE_TYPE_DEVICE_ECC_PROPERTIES = 0x26
@@ -615,6 +616,20 @@ class zes_mem_bandwidth_t(_PrintableStructure):
 
 
 ## Power structures ##
+class zes_power_properties_t(_PrintableStructure):
+    _fields_ = [
+        ("stype", c_int32),
+        ("pNext", c_void_p),
+        ("onSubdevice", ze_bool_t),
+        ("subdeviceId", c_uint32),
+        ("canControl", ze_bool_t),
+        ("isEnergyThresholdSupported", ze_bool_t),
+        ("defaultLimit", c_int32),
+        ("minLimit", c_int32),
+        ("maxLimit", c_int32),
+    ]
+
+
 class zes_power_limit_ext_desc_t(_PrintableStructure):
     _fields_ = [
         ("stype", c_int32),
@@ -1146,6 +1161,26 @@ def zesPowerGetEnergyCounter(hPower, pEnergy):
     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) - power properties structure to fill
+    Returns:
+        ze_result_t - return code only, power 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 zesPowerGetLimitsExt(hPower, pCount, pSustained):
     """Wraps API:
     ze_result_t zesPowerGetLimitsExt(

bindings/sysman/python/test/unit_tests/test_power.py

@@ -73,6 +73,61 @@ def mock_get_energy(power_handle, energy_ptr):
         mock_get_func.assert_called_with("zesPowerGetEnergyCounter")
         mock_func.assert_called_once()
 
+    def test_GivenValidPowerHandleWhenCallingZesPowerGetPropertiesThenCallSucceedsWithDomainData(
+        self, mock_get_func
+    ):
+        def mock_get_properties(power_handle, properties_ptr):
+            properties = properties_ptr._obj
+            properties.onSubdevice = 1
+            properties.subdeviceId = 3
+            properties.canControl = 1
+            properties.isEnergyThresholdSupported = 1
+            properties.defaultLimit = 250000
+            properties.minLimit = 150000
+            properties.maxLimit = 300000
+
+            ext_properties_ptr = cast(
+                properties.pNext, POINTER(self.pyzes.zes_power_ext_properties_t)
+            )
+            ext_properties_ptr.contents.domain = self.pyzes.ZES_POWER_DOMAIN_GPU
+            ext_properties_ptr.contents.defaultLimit.contents.level = (
+                self.pyzes.ZES_POWER_LEVEL_SUSTAINED
+            )
+            ext_properties_ptr.contents.defaultLimit.contents.limit = 250000
+            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()
+        default_limit = self.pyzes.zes_power_limit_ext_desc_t()
+        ext_properties = self.pyzes.zes_power_ext_properties_t()
+        ext_properties.stype = self.pyzes.ZES_STRUCTURE_TYPE_POWER_EXT_PROPERTIES
+        ext_properties.defaultLimit = pointer(default_limit)
+
+        properties = self.pyzes.zes_power_properties_t()
+        properties.stype = self.pyzes.ZES_STRUCTURE_TYPE_POWER_PROPERTIES
+        properties.pNext = cast(pointer(ext_properties), c_void_p)
+
+        result = self.pyzes.zesPowerGetProperties(power_handle, byref(properties))
+
+        self.assertEqual(result, self.pyzes.ZE_RESULT_SUCCESS)
+        self.assertEqual(properties.onSubdevice, 1)
+        self.assertEqual(properties.subdeviceId, 3)
+        self.assertEqual(properties.canControl, 1)
+        self.assertEqual(properties.isEnergyThresholdSupported, 1)
+        self.assertEqual(properties.defaultLimit, 250000)
+        self.assertEqual(properties.minLimit, 150000)
+        self.assertEqual(properties.maxLimit, 300000)
+        self.assertEqual(ext_properties.domain, self.pyzes.ZES_POWER_DOMAIN_GPU)
+        self.assertEqual(
+            ext_properties.defaultLimit.contents.level,
+            self.pyzes.ZES_POWER_LEVEL_SUSTAINED,
+        )
+        self.assertEqual(ext_properties.defaultLimit.contents.limit, 250000)
+        mock_get_func.assert_called_with("zesPowerGetProperties")
+        mock_func.assert_called_once()
+
     def test_GivenValidPowerHandleWhenCallingZesPowerGetLimitsExtThenCallSucceedsWithDescriptors(
         self, mock_get_func
     ):