ekfsm 0.11.0b1.post3__py3-none-any.whl

ekfsm/core/slots.py

@@ -0,0 +1,201 @@
+from enum import Enum
+from ekfsm.core.components import HwModule
+
+
+from munch import Munch
+
+
+from typing import Any
+
+
+class SlotType(Enum):
+    """
+    Define the types of slots that can be found in a chassis.
+
+    The following slot types are defined:
+    - CPCI_S0_UTILITY: CompactPCI Serial Utility Connector
+    - CPCI_S0_SYS: CompactPCI Serial System Slot
+    - CPCI_S0_PER: CompactPCI Serial Peripheral Slot
+    - CPCI_S0_PSU: CompactPCI Serial Power Supply Slot
+    """
+
+    CPCI_S0_UTILITY = 1  # CompactPCI Serial Utility Connector
+    CPCI_S0_SYS = 2  # CompactPCI Serial System Slot
+    CPCI_S0_PER = 3  # CompactPCI Serial Peripheral Slot
+    CPCI_S0_PSU = 4  # CompactPCI Serial Power Supply Slot
+
+    @classmethod
+    def from_string(cls, name: str) -> "SlotType":
+        try:
+            return cls[name]
+        except KeyError:
+            raise ValueError(f"Invalid {cls.__name__}: {name}")
+
+    def to_string(self) -> str:
+        return self.name
+
+
+class Slot:
+    """
+    A slot represents a physical slot in a chassis.
+
+    Parameters
+    ----------
+    name
+        The name of the slot, e.g. "SlotA" or "CPCI-SYSTEMSLOT"
+    slot_type
+        The type of the slot, e.g. SlotType.CPCI_S0_SYS
+    desired_hwmodule_type
+        The desired type of the hardware module that should be in the slot (currently unused)
+    desired_hwmodule_name
+        The name to be used for the hardware module instance in the slot. (currently unused)
+    master
+        The master board of the system
+    hwmodule
+        The hardware module that is in the slot
+    number
+        The number of the slot
+    attributes
+        Additional attributes
+    """
+
+    def __init__(
+        self,
+        name: str,
+        slot_type: SlotType,
+        desired_hwmodule_type: str,
+        desired_hwmodule_name: str,
+        number: int,
+        hwmodule: HwModule | None = None,
+        master: HwModule | None = None,
+        attributes: Munch | None = None,
+    ) -> None:
+        self._name = name
+        self.slot_type = slot_type
+        self._desired_hwmodule_type = desired_hwmodule_type
+        self._desired_hwmodule_name = desired_hwmodule_name
+        self.number = number
+        self.hwmodule = hwmodule
+        self.master = master
+        self.attributes = attributes
+
+    def info(self) -> dict[str, Any]:
+        """
+        Returns a dictionary with information about the slot.
+
+        - name (str): The name of the slot
+        - slot_type (str): The type of the slot
+        - number (int): The number of the slot
+        - desired_hwmodule_type (str): The desired type of the hardware module
+        - actual_hwmodule_type (str): The actual type of the hardware module
+        - desired_hwmodule_name (str): The desired name of the hardware module
+        - is_populated (bool): Is the slot populated?
+        - is_correctly_populated (bool): Is the slot correctly populated?
+        """
+        return {
+            "name": self._name,
+            "slot_type": self.slot_type.to_string(),
+            "number": self.number,
+            "desired_hwmodule_type": self._desired_hwmodule_type,
+            "actual_hwmodule_type": self.hwmodule.board_type if self.hwmodule else None,
+            "desired_hwmodule_name": self._desired_hwmodule_name,
+            "is_populated": self.is_populated,
+            "is_correctly_populated": self.is_correctly_populated,
+        }
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(name={self._name}, slot_type={self.slot_type})"
+        )
+
+    @property
+    def name(self) -> str:
+        """
+        Return the name of the slot.
+        """
+        return self._name
+
+    @property
+    def is_populated(self) -> bool:
+        """
+        Return True if the slot is populated, False otherwise.
+        """
+        return self.hwmodule is not None
+
+    @property
+    def is_correctly_populated(self) -> bool:
+        """
+        Return True if the slot is populated with the desired hardware module type, False otherwise.
+        """
+        return (
+            self.hwmodule is not None
+            and self.hwmodule.board_type.lower() == self._desired_hwmodule_type.lower()
+        )
+
+
+class Slots(Munch):
+    """
+    A collection of slots.
+
+    Slots are stored in a dictionary-like object, where the key is the slot name and the value is the Slot object.
+    Slots can be accessed by name, by number or via an attribute access matching the key.
+
+    Example
+    -------
+    >>> from ekfsm.slot import Slot, Slots, SlotType
+    >>> slotA = Slot("SlotA", SlotType.CPCI_S0_PER, "Bla", "Blubb", 3)
+    >>> slots = Slots((slotA.name, slotA))
+    >>> print(slots[name])
+    >>> print(slots.slotA) # attribute access, same as slots[name]
+    >>> print(slots[3]) # number access, same as slots.slotA
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+    def __getitem__(self, key: int | str) -> Slot:
+        """
+        Get a slot by name, number or attribute access.
+        """
+        if isinstance(key, int):
+            return next(slot for slot in self.values() if slot.number == key)
+
+        return super().__getitem__(key)
+
+    def __setitem__(self, key, value):
+        """
+        Add a Slot object to the collection.
+
+        Raises
+        ------
+        ValueError
+            if:
+            - the value is not a Slot object
+            - the key does not match the slot name
+            - the slot already exists in collection
+            - or the slot number is not unique
+        """
+        if not isinstance(value, Slot):
+            raise ValueError("Only Slot instances can be added to a Slots collection.")
+        elif key != value.name:
+            raise ValueError("Slot name must match key.")
+        elif value in self.values():
+            raise ValueError("Slot already exists in collection.")
+        elif value.number in [slot.number for slot in self.values()]:
+            raise ValueError("Slot number must be unique.")
+
+        return super().__setitem__(key, value)
+
+    def add(self, slot: Slot) -> None:
+        """
+        Add a Slot object to the collection, where the name of the slot object is used as the key.
+
+        Example
+        -------
+        >>> from ekfsm.slot import Slot, Slots, SlotType
+        >>> slotA = Slot("SlotA", SlotType.CPCI_S0_PER, "Bla", "Blubb", 3)
+        >>> slots = Slots()
+        >>> slots.add(slotA) # add slotA to the collection
+        >>> print(slots.SlotA) # attribute access, same as slots["SlotA"]
+        """
+        self[slot.name] = slot

ekfsm/core/sysfs.py

@@ -0,0 +1,91 @@
+from pathlib import Path
+
+SYSFS_ROOT = Path("/sys")
+
+
+def sysfs_root() -> Path:
+    return SYSFS_ROOT
+
+
+def set_sysfs_root(path: Path) -> None:
+    global SYSFS_ROOT
+    SYSFS_ROOT = path
+
+
+def file_is_sysfs_attr(path: Path) -> bool:
+    return path.is_file() and not path.stat().st_mode & 0o111
+
+
+class SysFSAttribute:
+    """
+    A SysFSAttribute is a singular sysfs attribute located somewhere in */sys*.
+
+    Attributes
+    ----------
+    path : Path
+        path to the underlying file for the SysFSAttribute instance
+    name : str
+        attribute name, or the last part of self.path
+
+    Methods
+    -------
+    read() -> Optional[str]
+        Reads the file attribute if it exists
+    write(data: Union[str, int]) -> None
+        Writes data to the file attribute
+
+    """
+
+    def __init__(self, path: Path):
+        self.path = path
+        if not path.exists() or not path.is_file():
+            raise FileNotFoundError("Invalid sysfs attribute path")
+
+        self.name: str = path.name
+
+    def read_utf8(self) -> str:
+        return self.path.read_text()
+
+    def read_bytes(self) -> bytes:
+        return self.path.read_bytes()
+
+    def write(self, data: str | bytes | None, offset: int = 0) -> None:
+        if self.is_sysfs_attr() and data is not None:
+            mode = 'r+' if isinstance(data, str) else 'rb+'
+            with open(self.path, mode) as f:
+                f.seek(offset)
+                f.write(data)
+
+    def is_sysfs_attr(self) -> bool:
+        return file_is_sysfs_attr(self.path)
+
+    def __repr__(self):
+        return f"SysFSAttribute: {self.name}"
+
+
+def list_sysfs_attributes(path: Path) -> list[SysFSAttribute]:
+    if not path.exists() or not path.is_dir():
+        raise FileNotFoundError(f"Invalid sysfs directory: {path}")
+
+    return [SysFSAttribute(item) for item in path.iterdir() if file_is_sysfs_attr(item)]
+
+
+class SysFSDevice:
+    def __init__(self, base_dir: Path):
+        self.path: Path = base_dir
+        self.attributes: list[SysFSAttribute] = list_sysfs_attributes(self.path)
+
+    def pre(self) -> None:
+        pass
+
+    def post(self) -> None:
+        pass
+
+    def write_attr(self, attr: str, data: str | bytes, offset: int = 0) -> None:
+        next(x for x in self.attributes if x.name == attr).write(data, offset)
+
+    def read_attr_utf8(self, attr: str) -> str:
+        return next(x for x in self.attributes if x.name == attr).read_utf8()
+
+    def read_attr_bytes(self, attr: str) -> bytes:
+        return next(x for x in self.attributes if x.name == attr).read_bytes()

ekfsm/core/utils.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+import logging
+from typing import TYPE_CHECKING
+from anytree import AnyNode
+
+from ekfsm.devices import CLASS_MAP
+from ekfsm.exceptions import ConfigError
+
+if TYPE_CHECKING:
+    from .components import HwModule
+    from ekfsm.devices.generic import Device
+
+
+class BoardDictImporter:
+
+    def __init__(self, nodecls=AnyNode):
+        self.nodecls = nodecls
+
+    def import_(self, logger: logging.Logger, data, parent=None):
+        """Import tree from `data`."""
+        return self.__import(logger, data, parent=parent)
+
+    def __import(self, logger: logging.Logger, data, parent=None):
+        from .components import HwModule
+
+        device_type = data.get("device_type")
+        nodecls = CLASS_MAP.get(device_type)
+        if nodecls is None:
+            raise ConfigError(f"Unknown device type: {device_type}")
+
+        children = data.pop("children", [])
+        if parent is not None and isinstance(parent, HwModule):
+            pass
+
+        node = nodecls(parent=parent, **data)
+
+        if children is not None:
+            for child in children:
+                try:
+                    logger.debug(f"Importing sub device {child}")
+                    self.__import(logger, child, parent=node)
+                except Exception as e:
+                    logger.error(
+                        f"Failed to import sub device {child}: {e}. continue anyway"
+                    )
+        return node
+
+
+def deserialize_hardware_tree(
+    logger: logging.Logger, data: dict, parent: "HwModule"
+) -> tuple[str, str, str, list["Device"]]:
+    importer = BoardDictImporter()
+
+    id = data.pop("id", None)
+    if id is None:
+        raise ConfigError("Board configuration must contain `id`")
+    name = data.pop("name", None)
+    if name is None:
+        raise ConfigError("Board configuration must contain `name`")
+    slot_type = data.pop("slot_type")
+    if slot_type is None:
+        raise ConfigError("Board configuration must contain `board_type`")
+
+    children = data.pop("children", None)
+    devices = []
+    if children:
+        for child in children:
+            try:
+                logger.debug(f"Importing top level device {child}")
+                node = importer.import_(logger, child, parent=parent)
+                devices.append(node)
+            except Exception as e:
+                logger.error(
+                    f"Failed to import top level device {child}: {e}. continue anyway"
+                )
+
+    return id, name, slot_type, devices

ekfsm/devices/__init__.py

@@ -0,0 +1,28 @@
+from ekfsm.devices.generic import Device
+from ekfsm.devices.hwmon import HWMON
+from ekfsm.devices.smbios import SMBIOS
+from .eeprom import EEPROM, EKF_EEPROM, EKF_CCU_EEPROM
+from .pmbus import PmBus
+from .gpio import GPIO, EKFIdentificationIOExpander, GPIOExpander
+from .ekf_sur_led import EKFSurLed
+from .ekf_ccu_uc import EKFCcuUc
+from .iio_thermal_humidity import IIOThermalHumidity
+from .mux import I2CMux, MuxChannel
+
+CLASS_MAP = {
+    "GenericDevice": Device,
+    "I2CMux": I2CMux,
+    "MuxChannel": MuxChannel,
+    "GPIO": GPIO,
+    "GPIOExpander": GPIOExpander,
+    "EKFIdentificationIOExpander": EKFIdentificationIOExpander,
+    "EEPROM": EEPROM,
+    "EKF_EEPROM": EKF_EEPROM,
+    "EKF_CCU_EEPROM": EKF_CCU_EEPROM,
+    "EKFCcuUc": EKFCcuUc,
+    "PmBus": PmBus,
+    "SMBIOS": SMBIOS,
+    "HWMON": HWMON,
+    "EKFSurLed": EKFSurLed,
+    "IIOThermalHumidity": IIOThermalHumidity,
+}