ekfsm 0.13.0a183__py3-none-any.whl → 1.5.0__py3-none-any.whl

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)

ekfsm/simctrl.py

@@ -1,20 +1,20 @@
 import socket
 import struct
-from unittest.mock import patch
 from pathlib import Path
+from typing import List
+from unittest.mock import patch
 
-from ekfsm.devices.smbus import SimSmbus
-from ekfsm.devices.gpio import EKFIdSimGpio
-from ekfsm.devices.gpio import SimGpio
-from .core.sysfs import set_sysfs_root
-from .core.components import SysTree
+from smbus2 import SMBus
 
+from ekfsm.devices.gpio import EKFIdSimGpio, SimGpio
+from ekfsm.devices.smbus import SimSMBus
+
+from .core.components import SysTree
+from .core.sysfs import set_sysfs_root
 from .devices import GPIO
-from typing import List
-from smbus2 import SMBus
 
 GPIO_SIM_MAPPING: dict[str, SimGpio] = {}
-SMBUS_SIM_MAPPING: dict[str, SimSmbus] = {}
+SMBUS_SIM_MAPPING: dict[str, SimSMBus] = {}
 
 
 def register_gpio_sim(major: int, minor: int, sim_gpio: SimGpio) -> None:
@@ -31,14 +31,14 @@ def find_gpio_dev_with_major_minor(major: int, minor: int) -> SimGpio:
     return GPIO_SIM_MAPPING[name]
 
 
-def register_smbus_sim(bus_num: int, i2c_addr: int, sim_smbus: SimSmbus) -> None:
+def register_smbus_sim(bus_num: int, i2c_addr: int, sim_smbus: SimSMBus) -> None:
     name = f"{bus_num}:{i2c_addr}"
     if name in SMBUS_SIM_MAPPING:
         raise ValueError(f"SMBUS_SIM_MAPPING already contains {name}")
     SMBUS_SIM_MAPPING[name] = sim_smbus
 
 
-def find_smbus_dev(bus_num: int, i2c_addr: int) -> SimSmbus:
+def find_smbus_dev(bus_num: int, i2c_addr: int) -> SimSMBus:
     name = f"{bus_num}:{i2c_addr}"
 
     if name not in SMBUS_SIM_MAPPING:
@@ -46,7 +46,7 @@ def find_smbus_dev(bus_num: int, i2c_addr: int) -> SimSmbus:
     return SMBUS_SIM_MAPPING[name]
 
 
-class GpioSimulator(GPIO):
+class GPIOSimulator(GPIO):
     def __init__(
         self,
         name: str,
@@ -80,7 +80,7 @@ class GpioSimulator(GPIO):
         return f"GPIO_SIM({self.name})"
 
 
-class SmbusSimulator:
+class SMBusSimulator:
     def __init__(self, bus_num: int):
         self.bus_num = bus_num
 
@@ -100,73 +100,12 @@ class SmbusSimulator:
         find_smbus_dev(self.bus_num, i2c_addr).write_word_data(cmd, data)
 
 
-def enable_gpio_simulation():
-    patched_methods = []
-
-    patched_methods.append(
-        patch.object(GPIO, "__init__", new_callable=lambda: GpioSimulator.__init__)
-    )
-    patched_methods.append(
-        patch.object(GPIO, "num_lines", new_callable=lambda: GpioSimulator.num_lines)
-    )
-    patched_methods.append(
-        patch.object(GPIO, "set_pin", new_callable=lambda: GpioSimulator.set_pin)
-    )
-    patched_methods.append(
-        patch.object(GPIO, "get_pin", new_callable=lambda: GpioSimulator.get_pin)
-    )
-    patched_methods.append(
-        patch.object(
-            GPIO, "set_direction", new_callable=lambda: GpioSimulator.set_direction
-        )
-    )
-    patched_methods.append(
-        patch.object(GPIO, "__str__", new_callable=lambda: GpioSimulator.__str__)
-    )
-    for pm in patched_methods:
-        pm.start()
-
-
-def enable_smbus_simulation():
-    patched_methods = []
-
-    patched_methods.append(
-        patch.object(SMBus, "__init__", new_callable=lambda: SmbusSimulator.__init__)
-    )
-    patched_methods.append(
-        patch.object(
-            SMBus, "read_word_data", new_callable=lambda: SmbusSimulator.read_word_data
-        )
-    )
-    patched_methods.append(
-        patch.object(
-            SMBus,
-            "read_block_data",
-            new_callable=lambda: SmbusSimulator.read_block_data,
-        )
-    )
-    patched_methods.append(
-        patch.object(
-            SMBus,
-            "write_block_data",
-            new_callable=lambda: SmbusSimulator.write_block_data,
-        )
-    )
-    patched_methods.append(
-        patch.object(
-            SMBus, "write_byte", new_callable=lambda: SmbusSimulator.write_byte
-        )
-    )
-    patched_methods.append(
-        patch.object(
-            SMBus,
-            "write_word_data",
-            new_callable=lambda: SmbusSimulator.write_word_data,
-        )
-    )
-
-    for pm in patched_methods:
-        pm.start()
+def patch_methods(cls, simulator, methods):
+    patched = []
+    for i, method in enumerate(methods):
+        if hasattr(cls, method) and hasattr(simulator, method):
+            patched.append(patch.object(cls, method, new_callable=lambda: getattr(simulator, method)))
+            patched[i].start()
 
 
 def enable_simulation(sysfs_path: Path | str) -> None:
@@ -180,8 +119,23 @@ def enable_simulation(sysfs_path: Path | str) -> None:
         sysfs_path = Path(sysfs_path)
 
     set_sysfs_root(sysfs_path)
-    enable_gpio_simulation()
-    enable_smbus_simulation()
+    patch_methods(
+        GPIO,
+        GPIOSimulator,
+        ["__init__", "num_lines", "set_pin", "get_pin", "set_direction", "__str__"],
+    )
+    patch_methods(
+        SMBus,
+        SMBusSimulator,
+        [
+            "__init__",
+            "read_word_data",
+            "read_block_data",
+            "write_block_data",
+            "write_byte",
+            "write_word_data",
+        ],
+    )
 
 
 def register_gpio_simulations():
@@ -189,7 +143,7 @@ def register_gpio_simulations():
     register_gpio_sim(233, 2, EKFIdSimGpio(0x34, 0xA, 0x0, 0x1))  # CCU Rev 0
 
 
-class SocketSmbus(SimSmbus):
+class SocketSmbus(SimSMBus):
     def __init__(self, host: str, port: int) -> None:
         self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         self.sock.connect((host, port))

ekfsm/system.py

@@ -1,52 +1,19 @@
-from typing import Tuple, Any, Generator
 from pathlib import Path
-from munch import Munch, munchify
+from typing import Any, Tuple
 
-from ekfsm.core.components import SysTree
 import yaml
+from munch import Munch, munchify
 
-from .core.slots import Slot, SlotType
+from ekfsm.core.components import SysTree
+from ekfsm.utils import all_board_cfg_files, find_board_config
 
 from .config import load_config
-from .core import HwModule
-from .core.slots import Slots
+from .core import HWModule
+from .core.slots import Slot, Slots, SlotType
 from .exceptions import ConfigError
 from .log import ekfsm_logger
 
 
-_CFG_DIR = Path(__file__).parent / "boards"
-
-
-def find_board_config(module_type: str) -> Path | None:
-    """
-    Find a matching board config in `boards/oem/` given the module type specified in
-    the system configuration file.
-
-    Parameters
-    ----------
-    module_type
-        Board type specified in the system configuration for a slot.
-        It must consist of an OEM and the board type, separated by whitespace. Neither
-        part may contain any other whitespace.
-    """
-    oem, board = module_type.split(maxsplit=1)
-    if (
-        path := _CFG_DIR / "oem" / oem.strip().lower() / f"{board.strip().lower()}.yaml"
-    ).exists():
-        return path
-    return None
-
-
-def all_board_cfg_files() -> Generator[Path, None, None]:
-    """
-    Generator that recursively yields all *.yaml files in a directory
-    """
-    path = Path(_CFG_DIR)
-    for item in path.rglob("*.yaml"):
-        if item.is_file():
-            yield item
-
-
 class System(SysTree):
     """
     A System represents a CPCI system.
@@ -57,15 +24,6 @@ class System(SysTree):
 
     Visual representation of the system is shown as trees of HW Modules and attached devices.
 
-    Iterating over the system will iterate over all boards in the system.
-
-    Accessing boards
-    ----------------
-    <board_name>
-        The board object can be accessed by its name.
-    <slot_number>
-        The board object can be accessed by its slot number.
-
     Attributes
     ----------
     name
@@ -81,11 +39,23 @@ class System(SysTree):
     config
         The system configuration.
 
+
+    Accessing boards
+    ----------------
+
+    Iterating over the system will iterate over all boards in the system.
+
+    <board_name>
+        The board object can be accessed by its name.
+    <slot_number>
+        The board object can be accessed by its slot number.
+
+
     Example
     -------
     >>> from ekfsm.system import System
     >>> system = System("path/to/config.yaml")
-    >>> print(system) # Print the system configuration as trees of HwModules
+    >>> print(system) # Print the system configuration as trees of HWModules
     >>> system.print() # same as above
     >>> cpu = system.cpu # Access the CPU board by its name
     >>> cpu = system[0] # Access the CPU board by its slot index (index as in configuration file)
@@ -101,6 +71,9 @@ class System(SysTree):
         ----------
         config
             Path to the config that specifies the system and how the slots are filled.
+        abort
+            If True, abort the program if a board cannot be created. If False, leave the slot empty.
+            Default is False.
         """
         self.config_path = config
         self.config = load_config(str(self.config_path))
@@ -116,7 +89,7 @@ class System(SysTree):
 
     def _init_system(self, config: Path):
         self.slots: Slots = Slots()
-        self.boards: list[HwModule] = []
+        self.boards: list[HWModule] = []
 
         self.master, self.master_slot_number = self._create_master()
         if self.master is None:
@@ -125,7 +98,7 @@ class System(SysTree):
         self.logger.info(f"Master board found in slot {self.master_slot_number}")
 
         for i, slot_cfg in enumerate(self.config.system_config.slots):
-            hwmod: HwModule | Slot | None
+            hwmod: HWModule | Slot | None
             if i == self.master_slot_number:
                 hwmod = self.master
             else:
@@ -164,35 +137,44 @@ class System(SysTree):
         """
         self.__init__(self.config_path)
 
-    def _create_master(self) -> Tuple[HwModule | None, int]:
+    def _create_master(self) -> Tuple[HWModule | None, int]:
         for i, slot in enumerate(self.config.system_config.slots):
             if "attributes" in slot:
                 if "is_master" in slot.attributes:
                     if slot.attributes.is_master:
                         master, _ = self.create_hwmodule(slot, i, None)
                         if master is not None:
-                            master.master = master
+                            master.master = master  # ???
                             return master, i
                         else:
                             return None, -1
         return None, -1  # ???
 
     def create_hwmodule(
-        self, slot_entry: Munch, slot_number: int, master: HwModule | None
-    ) -> Tuple[HwModule | None, Slot]:
+        self, slot_entry: Munch, slot_number: int, master: HWModule | None
+    ) -> Tuple[HWModule | None, Slot]:
         """
-        Create HwModule object for the slot.
+        Create HWModule object for the slot.
+
+        Parameters
+        ----------
+            slot_entry
+                The slot entry config (usually part of the system configuration).
+            slot_number
+                The slot number of the slot.
+            master
+                The master board of the system.
 
         Returns
         -------
-            HwModule and Slot. HwModule is None if it cannot be created.
+            HWModule and Slot. HWodule is None if it cannot be created.
         """
         slot = self._create_slot(slot_entry, slot_number, master)
         board_type = slot_entry.desired_hwmodule_type
         board_name = slot_entry.desired_hwmodule_name
 
         self.logger.debug(
-            f"Creating hwmodule {board_type} (desired name: {board_name}) in slot {slot.name}"
+            f"Creating HWModule {board_type} (desired name: {board_name}) in slot {slot.name}"
         )
 
         if board_type != "":
@@ -210,12 +192,12 @@ class System(SysTree):
             except Exception as e:
                 if self.abort:
                     self.logger.error(
-                        f"failed to create desired hwmodule {board_type} (as {board_name}): {e}. Aborting!"
+                        f"failed to create desired HWModule {board_type} (as {board_name}): {e}. Aborting!"
                     )
                     raise e
                 else:
                     self.logger.error(
-                        f"failed to create desired hwmodule {board_type} (as {board_name}): {e}. Leaving slot empty!"
+                        f"failed to create desired HWModule {board_type} (as {board_name}): {e}. Leaving slot empty!"
                     )
                     return None, slot
 
@@ -239,7 +221,7 @@ class System(SysTree):
                 continue
             except Exception as e:
                 self.logger.debug(
-                    f"failed to create hwmodule {path} for slot {slot.name}: {e}"
+                    f"failed to create HWmodule {path} for slot {slot.name}: {e}"
                 )
                 continue
 
@@ -252,7 +234,7 @@ class System(SysTree):
         return None, slot
 
     def _create_slot(
-        self, slot_entry: Munch, slot_number: int, master: HwModule | None
+        self, slot_entry: Munch, slot_number: int, master: HWModule | None
     ) -> Slot:
         attributes = None
         if "attributes" in slot_entry:
@@ -271,14 +253,14 @@ class System(SysTree):
 
     def _create_hwmodule_from_cfg_file(
         self, slot: Slot, board_name: str, path: Path
-    ) -> HwModule:
+    ) -> HWModule:
         """
-        Try to create a HwModule object from a board config file.
+        Try to create a HWModule object from a board config file.
         It does not probe the hardware.
 
         Returns
         -------
-            HwModule object.
+            HWModule object.
 
         Raises
         ------
@@ -299,7 +281,7 @@ class System(SysTree):
                     f"Slot type mismatch for slot {slot.name}: {cfg.slot_type} != {slot.slot_type}"
                 )
 
-            hwmod = HwModule(
+            hwmod = HWModule(
                 instance_name=board_name,
                 config=yaml_data,
                 slot=slot,
@@ -309,7 +291,21 @@ class System(SysTree):
 
             return hwmod
 
-    def get_module_in_slot(self, idx: int) -> HwModule | None:
+    def get_module_in_slot(self, idx: int) -> HWModule | None:
+        """
+        Get the HWModule in the given slot.
+
+        Parameters
+        ----------
+            idx
+                The slot index.
+        Returns
+        -------
+            HWModule
+                The HWModule in the given slot.
+            None
+                If no HWModule is present in the given slot.
+        """
         return next(
             (
                 v.hwmodule
@@ -319,16 +315,36 @@ class System(SysTree):
             None,
         )
 
-    def get_module_by_name(self, name: str) -> HwModule | None:
+    def get_module_by_name(self, name: str) -> HWModule | None:
+        """
+        Get the HWModule by its name.
+
+        Parameters
+        ----------
+            name
+                The name of the HWModule.
+
+        Returns
+        -------
+            HWModule
+                The HWModule with the given name.
+            None
+                If no HWModule is present with the given name.
+        """
         return next(
-            (b for b in self.boards if getattr(b, "instance_name", None) == name),
+            (
+                b
+                for b in self.boards
+                if getattr(b, "instance_name", None) is not None
+                and getattr(b, "instance_name").lower() == name.lower()
+            ),
             None,
         )
 
     def __iter__(self):
         return iter(self.boards)
 
-    def __getitem__(self, key) -> HwModule:
+    def __getitem__(self, key) -> HWModule:
         if isinstance(key, int):
             value = self.get_module_in_slot(key)
         else:
@@ -342,9 +358,9 @@ class System(SysTree):
     def __getattr__(self, name: str) -> Any:
         """Access board by attribute using dot notation"""
         # This fixes mypy error: "... has no object ..."
-        hwModule = self.get_module_by_name(name)
-        if hwModule is not None:
-            return hwModule
+        if (hw_module := self.get_module_by_name(name)) is not None:
+            return hw_module
+
         raise AttributeError(
             f"'{type(self).__name__}' object has no board with name '{name}'"
         )

ekfsm/utils.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+from typing import Generator
+
+_CFG_DIR = Path(__file__).parent / "boards"
+
+
+def find_board_config(module_type: str) -> Path | None:
+    """
+    Find a matching board config in `boards/oem/` given the module type specified in
+    the system configuration file.
+
+    Parameters
+    ----------
+    module_type
+        Board type specified in the system configuration for a slot.
+        It must consist of an OEM and the board type, separated by whitespace. Neither
+        part may contain any other whitespace.
+    """
+    oem, board = module_type.split(maxsplit=1)
+    if (path := _CFG_DIR / "oem" / oem.strip().lower() / f"{board.strip().lower()}.yaml").exists():
+        return path
+    return None
+
+
+def all_board_cfg_files() -> Generator[Path, None, None]:
+    """
+    Generator that recursively yields all *.yaml files in the config directory.
+
+    Yields
+    ------
+    item: Path
+        Path to a config file.
+    """
+    path = Path(_CFG_DIR)
+    for item in path.rglob("*.yaml"):
+        if item.is_file():
+            yield item
+
+
+def next_or_raise(it, exc):
+    value = next(it, None)
+    if value is None:
+        raise exc
+    return value