ekfsm 1.1.0a15.post1__py3-none-any.whl → 1.3.0__py3-none-any.whl

ekfsm/devices/mux.py

@@ -1,8 +1,11 @@
 from ekfsm.core.components import SysTree
+from ekfsm.log import ekfsm_logger
 
-from ..core.sysfs import SysFSDevice
+from ..core.sysfs import SysfsDevice
 from .generic import Device
 
+logger = ekfsm_logger(__name__)
+
 
 class MuxChannel(Device):
     """
@@ -25,20 +28,21 @@ class MuxChannel(Device):
     def __init__(
         self,
         name: str,
-        channel_id: int,
         parent: "I2CMux",
         children: list[Device] | None = None,
+        abort=False,
+        channel_id: int | None = None,
         *args,
         **kwargs,
     ) -> None:
-        super().__init__(name=name, parent=parent, children=children)
+        super().__init__(name, parent, children, abort, *args, **kwargs)
         self.channel_id = channel_id
 
         assert parent.sysfs_device is not None
         assert isinstance(self.parent, I2CMux)
 
         path = parent.sysfs_device.path / f"channel-{self.channel_id}"
-        self.sysfs_device = SysFSDevice(path)
+        self.sysfs_device = SysfsDevice(path, False)
 
 
 class I2CMux(Device):
@@ -59,11 +63,12 @@ class I2CMux(Device):
         self,
         name: str,
         parent: SysTree | None = None,
-        children: list[MuxChannel] | None = None,
+        children: list[Device] | None = None,
+        abort=False,
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, children, **kwargs)
+        super().__init__(name, parent, children, abort, *args, **kwargs)
 
         self.addr = self.get_i2c_chip_addr()
         self.sysfs_device = self.get_i2c_sysfs_device(self.addr)

ekfsm/devices/pmbus.py

@@ -1,20 +1,17 @@
+import re
 from enum import IntFlag
-from pathlib import Path
+from functools import wraps
+from time import sleep
 
 from ekfsm.core.components import SysTree
+from ekfsm.exceptions import HWMonError
+from ekfsm.log import ekfsm_logger
 
-from ..core.sysfs import SysFSDevice, sysfs_root
-
-from .generic import Device
 from ..core.probe import ProbeableDevice
+from ..core.sysfs import list_sysfs_attributes, sysfs_root
+from .generic import Device
 
-from time import sleep
-from functools import wraps
-from ekfsm.log import ekfsm_logger
-from threading import Lock
-import re
-
-__all__ = ["PsuStatus", "PmBus", "retry"]
+__all__ = ["PSUStatus", "PMBus", "retry"]
 
 logger = ekfsm_logger(__name__)
 
@@ -34,8 +31,8 @@ def retry(max_attempts=5, delay=0.5):
 
     Important
     ---------
-    This decorator is thread-safe, meaning a read attempt is atomic and cannot
-    be interupted by scheduler.
+    This decorator is _not_ thread-safe across multiple ekfsm processes. Unfortunately,
+    we cannot use fcntl or flock syscalls with files on virtual filesystems like sysfs.
 
     Parameters
     ----------
@@ -45,26 +42,19 @@ def retry(max_attempts=5, delay=0.5):
         The delay in seconds between attempts.
     """
 
-    lock = Lock()
-
     def decorator(func):
         @wraps(func)
         def wrapper(*args, **kwargs):
             attempts = 0
             while attempts < max_attempts:
-                with lock:
-                    try:
-                        return func(*args, **kwargs)
-                    except Exception as e:
-                        attempts += 1
-                        if attempts == max_attempts:
-                            logger.exception(
-                                f"Failed to execute {func.__name__} after {max_attempts} attempts: {e}"
-                            )
-                            raise e
-                        logger.info(
-                            f"Retrying execution of {func.__name__} in {delay}s..."
-                        )
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    attempts += 1
+                    if attempts == max_attempts:
+                        logger.exception(f"Failed to execute {func.__name__} after {max_attempts} attempts: {e}")
+                        raise e
+                    logger.info(f"Retrying execution of {func.__name__} in {delay}s...")
                 sleep(delay)
 
         return wrapper
@@ -72,7 +62,7 @@ def retry(max_attempts=5, delay=0.5):
     return decorator
 
 
-class PsuStatus(IntFlag):
+class PSUStatus(IntFlag):
     """
     Represents the status of a PSU according to STATUS_BYTE register.
 
@@ -93,9 +83,8 @@ class PsuStatus(IntFlag):
     >>> PsuStatus.OK in status
     True
     >>> # Instead, check if status is OK
-    >>> status = PsuStatus(0x00)
-    >>> status
-    <PsuStatus.OK: 0>
+    >>> status == PsuStatus(0x00)
+    False
     >>> PsuStatus.OUTPUT_OVERCURRENT in status
     False
     """
@@ -109,44 +98,47 @@ class PsuStatus(IntFlag):
     OK = 0x00
 
 
-class PmBus(Device, ProbeableDevice):
-    """
-    This class represents a PMBus device (e.g. a PSU).
-    """
+logger = ekfsm_logger(__name__)
+
 
+class PMBus(Device, ProbeableDevice):
     def __init__(
         self,
         name: str,
         parent: SysTree | None = None,
         children: list[Device] | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, children, *args, **kwargs)
+        super().__init__(name, parent, children, abort, *args, **kwargs)
         self.addr = self.get_i2c_chip_addr()
-        self.sysfs_device = self.get_i2c_sysfs_device(self.addr)
-
-        files = list(Path(self.sysfs_device.path).rglob("hwmon/*/in1_input"))
-        if len(files) == 0:
-            raise FileNotFoundError("No HWMON entries found in sysfs")
-        self.hwmon_sysfs = SysFSDevice(files[0].parent)
-
-        self.debugfs_root = sysfs_root() / "kernel/debug/pmbus"
-        files = list(self.debugfs_root.rglob("hwmon*/status*_input"))
-        if len(files) == 0:
-            raise FileNotFoundError("No HWMON entries found in debugfs")
-        self.hwmon_debugfs = SysFSDevice(files[0].parent)
+        self.sysfs_device = self.get_i2c_sysfs_device(self.addr, driver_required=True)
+
+        try:
+            for entry in self.sysfs_device.path.glob("hwmon/hwmon*"):
+                if entry.is_dir():
+                    attrs = list_sysfs_attributes(entry)
+                    self.sysfs_device.extend_attributes(attrs)
+
+                    debug_attrs_path = sysfs_root().joinpath(f"kernel/debug/pmbus/{entry.name}")
+                    debug_attrs = list_sysfs_attributes(debug_attrs_path)
+                    self.sysfs_device.extend_attributes(debug_attrs)
+        except FileNotFoundError:
+            logger.debug("Expected sysfs attribute not found")
+        except StopIteration:
+            raise HWMonError("Device is not managed by hwmon subsystem")
 
     def probe(self, *args, **kwargs) -> bool:
-        from ekfsm.core import HwModule
+        from ekfsm.core import HWModule
 
-        assert isinstance(self.hw_module, HwModule)
+        assert isinstance(self.hw_module, HWModule)
         # compare the regexp from the board yaml file with the model
         return re.match(self.hw_module.id, self.model()) is not None
 
     # Voltage and Current Interfaces
-    def _conversion(self, in_file: str) -> float:
-        return float(self.hwmon_sysfs.read_attr_utf8(in_file)) / 1000.0
+    def __convert_and_scale(self, attr: str) -> float:
+        return self.sysfs.read_float(attr) / 1000.0
 
     @retry()
     def in1_input(self) -> float:
@@ -157,7 +149,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input voltage in volts
         """
-        return self._conversion("in1_input")
+        return self.__convert_and_scale("in1_input")
 
     @retry()
     def in2_input(self) -> float:
@@ -168,7 +160,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input voltage in volts
         """
-        return self._conversion("in2_input")
+        return self.__convert_and_scale("in2_input")
 
     @retry()
     def curr1_input(self) -> float:
@@ -179,7 +171,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input current in amperes
         """
-        return self._conversion("curr1_input")
+        return self.__convert_and_scale("curr1_input")
 
     @retry()
     def curr2_input(self) -> float:
@@ -190,32 +182,32 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input current in amperes
         """
-        return self._conversion("curr2_input")
+        return self.__convert_and_scale("curr2_input")
 
     # Status Interface
     @retry()
-    def status0_input(self) -> PsuStatus:
+    def status0_input(self) -> PSUStatus:
         """
         Get the status of PSU page 1.
 
         Returns
         -------
-            PSU status as defined in PsuStatus
+            PSU status as defined in PSUStatus
         """
-        status = int(self.hwmon_debugfs.read_attr_utf8("status0_input").strip(), 16)
-        return PsuStatus(status)
+        status = self.sysfs.read_int("status0_input")
+        return PSUStatus(status)
 
     @retry()
-    def status1_input(self) -> PsuStatus:
+    def status1_input(self) -> PSUStatus:
         """
         Get the status of PSU page 2.
 
         Returns
         -------
-            PSU status as defined in PsuStatus
+            PSU status as defined in PSUStatus
         """
-        status = int(self.hwmon_debugfs.read_attr_utf8("status1_input").strip(), 16)
-        return PsuStatus(status)
+        status = self.sysfs.read_int("status1_input")
+        return PSUStatus(status)
 
     # Temperature Interface
     @retry()
@@ -227,7 +219,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU temperature in degrees celsius
         """
-        return self._conversion("temp1_input")
+        return self.__convert_and_scale("temp1_input")
 
     # Inventory Interface
     def vendor(self) -> str:
@@ -238,7 +230,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU vendor
         """
-        return self.hwmon_sysfs.read_attr_utf8("vendor").strip()
+        return self.sysfs.read_utf8("vendor")
 
     def model(self) -> str:
         """
@@ -248,7 +240,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU model
         """
-        return self.hwmon_sysfs.read_attr_utf8("model").strip()
+        return self.sysfs.read_utf8("model")
 
     def serial(self) -> str:
         """
@@ -258,7 +250,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU serial number
         """
-        return self.hwmon_sysfs.read_attr_utf8("serial").strip()
+        return self.sysfs.read_utf8("serial")
 
     def revision(self) -> str:
         """
@@ -268,4 +260,4 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU revision
         """
-        return self.hwmon_sysfs.read_attr_utf8("revision").strip()
+        return self.sysfs.read_utf8("revision")

ekfsm/devices/smbios.py

@@ -1,6 +1,8 @@
 from pathlib import Path
-from ekfsm.core.components import HwModule
-from ekfsm.core.sysfs import SysFSDevice, sysfs_root
+
+from ekfsm.core.components import HWModule
+from ekfsm.core.sysfs import SysfsDevice, sysfs_root
+
 from .generic import Device
 
 
@@ -18,15 +20,15 @@ class SMBIOS(Device):
     def __init__(
         self,
         name: str,
-        parent: HwModule | None = None,
+        parent: HWModule | None = None,
+        children: list["Device"] | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        self.sysfs_device: SysFSDevice = SysFSDevice(
-            sysfs_root() / Path("devices/virtual/dmi/id")
-        )
+        self.sysfs_device: SysfsDevice | None = SysfsDevice(sysfs_root() / Path("devices/virtual/dmi/id"), False)
 
-        super().__init__(name, parent, None, *args, **kwargs)
+        super().__init__(name, parent, None, abort, *args, **kwargs)
 
     def revision(self) -> str:
         """
@@ -37,4 +39,4 @@ class SMBIOS(Device):
         str
             The board revision.
         """
-        return self.sysfs_device.read_attr_utf8("board_version").strip()
+        return self.sysfs.read_utf8("board_version")

ekfsm/devices/smbus.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from typing import List
 
 
-class SimSmbus(ABC):
+class SimSMBus(ABC):
     @abstractmethod
     def read_word_data(self, cmd: int) -> int:
         pass

ekfsm/devices/utils.py

@@ -1,13 +1,4 @@
 from crcmod.predefined import Crc
-from typing import Sequence
-
-
-def compute_int_from_bytes(data: Sequence[int]) -> int:
-    # Combine the bytes into a single integer
-    result = 0
-    for num in data:
-        result = (result << 8) | num
-    return result
 
 
 def get_crc16_xmodem(data: bytes) -> int:

ekfsm/exceptions.py

@@ -3,6 +3,7 @@ from enum import Enum
 
 class EkfSmException(Exception):
     """Base class for all exceptions in the EKFSM Library"""
+
     pass
 
 
@@ -12,7 +13,7 @@ class ConfigError(EkfSmException):
     pass
 
 
-class SYSFSError(EkfSmException):
+class SysFSError(EkfSmException):
     """Error while handling sysfs pseudo file system"""
 
     pass
@@ -31,9 +32,31 @@ class GPIOError(EkfSmException):
     def __init__(self, error_type: ErrorType, details: str | None = None):
         self.error_type = error_type
         self.details = details
-        super().__init__(
-            f"{error_type.value}: {details}" if details else error_type.value
-        )
+        super().__init__(f"{error_type.value}: {details}" if details else error_type.value)
+
+
+class DriverError(EkfSmException):
+    """No driver found for device"""
+
+    pass
+
+
+class HWMonError(EkfSmException):
+    """No HwMon entry found for device"""
+
+    pass
+
+
+class ConversionError(EkfSmException):
+    """Failed to convert"""
+
+    pass
+
+
+class UnsupportedModeError(EkfSmException):
+    """Format not supported"""
+
+    pass
 
 
 class FirmwareNodeError(EkfSmException):
@@ -47,9 +70,7 @@ class DataCorruptionError(EkfSmException):
 
     def __init__(self, details: str | None = None):
         self.details = details
-        super().__init__(
-            f"Data corruption: {details}" if details else "Data corruption"
-        )
+        super().__init__(f"Data corruption: {details}" if details else "Data corruption")
 
 
 class AcquisitionError(EkfSmException):

ekfsm/lock.py

@@ -1,22 +1,23 @@
+"""
+Some devices or device functions don't allow concurrent access.
+The locking mechanism is used to ensure that only one process/thread can
+access the device (function) at a time.
+
+Locking granularity is defined by the device.
+It may be at the device level or function level.
+
+Application can choose to use the locking mechanism or not.
+By default, the locking mechanism is enabled and uses the default
+lockfile root directory ``/var/lock/ekfsm``.
+
+Use :func:`locking_configure` to enable or disable the locking mechanism or to change
+the lockfile root directory.
+"""
+
 import fcntl
 import os
-from pathlib import Path
 from contextlib import contextmanager
-
-#
-# Some devices or device functions don't allow concurrent access.
-# The locking mechanism is used to ensure that only one process/thread can
-# access the device (function) at a time.
-#
-# Locking granularity is defined by the device.
-# It may be at the device level or function level.
-#
-# Application can choose to use the locking mechanism or not.
-# By default, the locking mechanism is enabled and uses the default
-# lockfile root directory /var/lock/ekfsm.
-#
-# Use locking_configure() to enable or disable the locking mechanism or to change
-# the lockfile root directory.
+from pathlib import Path
 
 USE_LOCK = True
 LOCKFILE_ROOT = "/var/lock/ekfsm"
@@ -27,8 +28,12 @@ def locking_configure(enable: bool, lockfile_root: str = LOCKFILE_ROOT):
     """
     Configures the locking mechanism.
 
-    :param enable: Whether to enable or disable locking.
-    :param lockfile_root: The root directory for lockfiles. (default: /var/lock/ekfsm)
+    Parameters
+    ----------
+    enable
+        Whether to enable or disable locking.
+    lockfile_root
+        The root directory for lockfiles.
     """
     global USE_LOCK, LOCKFILE_ROOT
     USE_LOCK = enable
@@ -55,9 +60,12 @@ class Locker:
 
     Example
     -------
-    with Locker("mysharedresourcename").lock():
-        # Access the shared resource here
-        pass
+    .. code-block:: python
+
+        with Locker("mysharedresourcename").lock():
+            # Access the shared resource here
+            pass
+
     """
 
     def __init__(self, module: str):
@@ -72,6 +80,17 @@ class Locker:
         ALL_LOCKERS.append(self)
 
     def cleanup(self):
+        """
+        Cleans up the lock file and closes the lock file descriptor.
+
+        Important
+        ---------
+        This method should be called when the lock is no longer needed.
+
+        Note
+        ----
+        It is automatically called when the context manager exits.
+        """
         if not USE_LOCK:
             return
         if self.lock_fd is not None:
@@ -84,6 +103,14 @@ class Locker:
 
     @contextmanager
     def lock(self):
+        """
+        Locks the resource for exclusive access.
+
+        Note
+        ----
+        This method is a context manager that locks the resource when entered
+        and releases the lock when exited.
+        """
         if not USE_LOCK:
             yield
         self.lock_fd = os.open(self.lockfile_path, os.O_RDWR)