ekfsm 0.13.0a168.post1__tar.gz → 0.13.0a183.post1__tar.gz

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ekfsm
-Version: 0.13.0a168.post1
+Version: 0.13.0a183.post1
 Summary: The EKF System Management Library (ekfsm) is a sensor monitoring suite for Compact PCI Serial devices.
 Author-email: Klaus Popp <klaus.popp@ci4rail.com>, Jan Jansen <jan@ekf.de>, Felix Päßler <fp@ekf.de>
 Requires-Python: >=3.10

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/boards/ekf/ccu.rst

@@ -5,11 +5,23 @@ EKF CCU
 ===========
 
 
-Chassis Inventory (Object: `system_inventory`)
+Chassis Inventory (Object: `chassis_inventory`)
 ===============================================
 
 The system inventory provides access to the chassis inventory, such as the vendor, model, serial number, and revision.
 
+You can access the chassis inventory from the ccu object via the `chassis_inventory` attribute.
+
+Alternatively, if your system configuration has the following snippet:
+
+.. code-block:: yaml
+
+    system_config:
+    name: "MySystem"
+    aggregates:
+        chassis_inventory: inventory
+
+you can access the chassis inventory via the system object's `inventory` attribute.
 
 +--------------------------------------------------------------------+-------------------------------+--------------------+
 | Method                                                             | Description                   | Example Value      |

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/boards/ekf/sc9-toccata.rst

@@ -33,8 +33,8 @@ The CPU temperature object provides the current CPU Die temperature in degrees C
 
 
 
-+--------------------------------------------+------------------+---------------+
-| Method                                     | Description      | Example Value |
-+--------------------------------------------+------------------+---------------+
-| :meth:`~ekfsm.devices.hwmon.HWMON.cputemp` | Get the CPU temp | ``65``        |
-+--------------------------------------------+------------------+---------------+
++--------------------------------------------------+------------------+---------------+
+| Method                                           | Description      | Example Value |
++--------------------------------------------------+------------------+---------------+
+| :meth:`~ekfsm.devices.coretemp.CoreTemp.cputemp` | Get the CPU temp | ``65``        |
++--------------------------------------------------+------------------+---------------+

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to EKF System Management Library documentation!
-======================================================
+========================================================
 
 
 .. toctree::

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/intro.rst

@@ -180,12 +180,22 @@ ensures that the relevant linux sysfs entries and devices are protected from con
 However, there are some exceptions due to the nature of some devices. For example, the
 :ref:`ccu` has some methods that cannot be simultaneously accessed by multiple processes.
 
+This is why the ekfsm package provides a locking mechanism for these devices. The locking mechanism is
+implemented using a file lock. Application can choose to use the locking mechanism or not.
+By default, the locking mechanism is enabled and uses the default lockfile directory ``/var/lock/ekfsm``.
+The :meth:`~ekfsm.locking_configure` method can be used to enable or disable the locking mechanism and
+to configure the lockfile directory.
+
+To ensure that file locks are properly released, the application should
+call the :meth:`~ekfsm.locking_cleanup` whenever the program exits. This can be done
+using the `atexit` module.
+
 
 Usage from within a container
 -----------------------------
 
-The ekfsm package can be used from within a container, but the container must have access to the `/sys` and `/dev`
-directories of the host system.
+The ekfsm package can be used from within a container, but the container must have access to the `/sys`, `/dev` #
+and - if locking is enabled - `/var/lock` directories of the host system.
 
 This can be achieved by mounting the host's `/sys` and `/dev` directories into the container, e.g.
 

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/reference/ekfsm.rst

@@ -53,9 +53,9 @@ EKF CCU Microcontroller
 Devices using SysFs
 -------------------
 
-HWMON
-~~~~~
-.. automodule:: ekfsm.devices.hwmon
+CoreTemp
+~~~~~~~~
+.. automodule:: ekfsm.devices.coretemp
 
 SMBIOS
 ~~~~~~

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/docs/source/reference/systemconfig.rst

@@ -62,3 +62,27 @@ currently not used, but you can access it via the `System` object's `name` attri
    - For CompactPCI slots, `slot_coding` defines the geographical address of the slot, i.e.
      the setting of the GA[3:0] pins on the backplane.
    - The `is_master` attribute is used to designate the master slot.
+
+
+Making board objects accessible from the system object
+------------------------------------------------------
+
+Some hardware modules provide functions that belong to the whole system, such as the
+:ref:`ccu`, which provides a `chassis_inventory` function that returns the serial number etc.
+of the complete system. You can make this function accessible from the system object like so:
+
+.. code-block:: yaml
+
+  system_config:
+    name: "Simple System"
+    aggregates:
+      chassis_inventory: inventory
+
+Then, you can access the function like this:
+
+.. code-block:: python
+
+    import ekfsm
+
+    system = ekfsm.System("system.yaml")
+    serial = system.inventory.serial()

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/ekfsm/__init__.py

@@ -3,6 +3,7 @@ from .system import System
 from .core import HwModule
 from .core.slots import SlotType
 from .exceptions import ConfigError
+from .lock import locking_cleanup, locking_configure
 
 __all__ = (
     "System",
@@ -10,4 +11,6 @@ __all__ = (
     "HwModule",
     "Slot",
     "SlotType",
+    "locking_cleanup",
+    "locking_configure",
 )

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/ekfsm/boards/oem/hitron/hdrc-300s.yaml

@@ -1,4 +1,4 @@
-id: HDRC300S-110J-D120E(N)
+id: HDRC300S.*
 name: "Hitron HDRC-300S"
 slot_type: CPCI_S0_PSU
 children:

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/ekfsm/devices/ekf_ccu_uc.py

@@ -4,6 +4,7 @@ from enum import Enum
 from typing import Tuple
 from ekfsm.core.components import SysTree
 from ..exceptions import AcquisitionError
+from ..lock import Locker
 from .imu import ImuSample
 import struct
 
@@ -292,21 +293,18 @@ class EKFCcuUc(Device):
         progress_callback
             A callback function that is called with the current progress in bytes.
 
-        Warning
-        ---------
-        Do not call this method at the same time from multiple threads or processes.
-
         """
-        offset = 0
-        max_chunk_len = 28
-        while len(firmware) > 0:
-            chunk, firmware = firmware[:max_chunk_len], firmware[max_chunk_len:]
-            self._load_firmware_chunk(offset, len(firmware) == 0, chunk)
-            offset += len(chunk)
-            if len(firmware) != 0:
-                self._nop()
-            if progress_callback is not None:
-                progress_callback(offset)
+        with Locker(self.name + "-load_firmware").lock():
+            offset = 0
+            max_chunk_len = 28
+            while len(firmware) > 0:
+                chunk, firmware = firmware[:max_chunk_len], firmware[max_chunk_len:]
+                self._load_firmware_chunk(offset, len(firmware) == 0, chunk)
+                offset += len(chunk)
+                if len(firmware) != 0:
+                    self._nop()
+                if progress_callback is not None:
+                    progress_callback(offset)
 
     def _load_firmware_chunk(self, offset: int, is_last: bool, data: bytes) -> None:
         if is_last:
@@ -369,22 +367,20 @@ class EKFCcuUc(Device):
         str
             The parameterset in JSON format.
 
-        Warning
-        ---------
-        Do not call this method at the same time from multiple threads or processes.
         """
-        json = b""
-        begin = True
-        while True:
-            chunk = self._get_parameterset_chunk(begin)
-            if len(chunk) < 32:
-                break
-            # if chunk ends with zero byte, remove it (workaround for I2C slave bug)
-            if chunk[-1] == 0:
-                chunk = chunk[:-1]
-            json += chunk
-            begin = False
-        return json.decode("utf-8")
+        with Locker(self.name + "-parameterset").lock():
+            json = b""
+            begin = True
+            while True:
+                chunk = self._get_parameterset_chunk(begin)
+                if len(chunk) < 32:
+                    break
+                # if chunk ends with zero byte, remove it (workaround for I2C slave bug)
+                if chunk[-1] == 0:
+                    chunk = chunk[:-1]
+                json += chunk
+                begin = False
+            return json.decode("utf-8")
 
     def _get_parameterset_chunk(self, begin: bool) -> bytes:
         data = self._smbus.read_block_data(
@@ -423,19 +419,16 @@ class EKFCcuUc(Device):
         _cfg
             The parameterset in JSON format.
 
-        Warning
-        ---------
-        Do not call this method at the same time from multiple threads or processes.
-
         """
-        cfg = _cfg.encode("utf-8")
-        offset = 0
-        max_chunk_len = 28
-        while len(cfg) > 0:
-            chunk, cfg = cfg[:max_chunk_len], cfg[max_chunk_len:]
-            self._load_parameterset_chunk(offset, len(cfg) == 0, chunk)
-            offset += len(chunk)
-            self._nop()
+        with Locker(self.name + "-parameterset").lock():
+            cfg = _cfg.encode("utf-8")
+            offset = 0
+            max_chunk_len = 28
+            while len(cfg) > 0:
+                chunk, cfg = cfg[:max_chunk_len], cfg[max_chunk_len:]
+                self._load_parameterset_chunk(offset, len(cfg) == 0, chunk)
+                offset += len(chunk)
+                self._nop()
 
     def _load_parameterset_chunk(self, offset: int, is_last: bool, data: bytes) -> None:
         if is_last:

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/ekfsm/devices/pmbus.py

@@ -12,6 +12,7 @@ from time import sleep
 from functools import wraps
 from ekfsm.log import ekfsm_logger
 from threading import Lock
+import re
 
 __all__ = ["PsuStatus", "PmBus", "retry"]
 
@@ -118,7 +119,8 @@ class PmBus(Device, ProbeableDevice):
         from ekfsm.core import HwModule
 
         assert isinstance(self.hw_module, HwModule)
-        return self.hw_module.id == self.model()
+        # 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:

ekfsm-0.13.0a183.post1/ekfsm/lock.py

@@ -0,0 +1,94 @@
+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.
+
+USE_LOCK = True
+LOCKFILE_ROOT = "/var/lock/ekfsm"
+ALL_LOCKERS: list["Locker"] = []  # List of all locker instances
+
+
+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)
+    """
+    global USE_LOCK, LOCKFILE_ROOT
+    USE_LOCK = enable
+    LOCKFILE_ROOT = lockfile_root
+
+
+def locking_cleanup():
+    """
+    Cleans up all lockfiles and closes all lock file descriptors.
+    Should be called at the end of the program to ensure all locks are released.
+    """
+    for locker in ALL_LOCKERS:
+        locker.cleanup()
+
+
+class Locker:
+    """
+    A class that implements a locking mechanism using file locks.
+
+    Parameters
+    ----------
+    module
+        The name of the module or resource to lock. This will be used to create a unique lock file.
+
+    Example
+    -------
+    with Locker("mysharedresourcename").lock():
+        # Access the shared resource here
+        pass
+    """
+
+    def __init__(self, module: str):
+        if not USE_LOCK:
+            return
+
+        self.lockfile_path = Path(LOCKFILE_ROOT) / module
+        self.lock_fd = None
+        # Ensure lockfile exists
+        os.makedirs(LOCKFILE_ROOT, exist_ok=True)
+        open(self.lockfile_path, "a").close()
+        ALL_LOCKERS.append(self)
+
+    def cleanup(self):
+        if not USE_LOCK:
+            return
+        if self.lock_fd is not None:
+            try:
+                fcntl.flock(self.lock_fd, fcntl.LOCK_UN)
+                os.close(self.lock_fd)
+                self.lock_fd = None
+            except (OSError, AttributeError):
+                pass
+
+    @contextmanager
+    def lock(self):
+        if not USE_LOCK:
+            yield
+        self.lock_fd = os.open(self.lockfile_path, os.O_RDWR)
+        try:
+            fcntl.flock(self.lock_fd, fcntl.LOCK_EX)
+            yield
+        finally:
+            self.cleanup()

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/pyproject.toml

@@ -21,7 +21,7 @@ authors = [
 ]
 description = "The EKF System Management Library (ekfsm) is a sensor monitoring suite for Compact PCI Serial devices."
 requires-python = ">=3.10"
-version = "0.13.0-alpha.168.post.1"
+version = "0.13.0-alpha.183.post.1"
 
 [project.scripts]
 ekfsm-cli = "ekfsm.cli:main"

ekfsm-0.13.0a183.post1/tests/locking/lock_tester.py

@@ -0,0 +1,35 @@
+#!python
+import time
+import random
+import sys
+
+from ekfsm.lock import Locker
+
+
+def use_shared_resource(myid: str):
+    with open("shared_resource.txt", "w") as f:
+        f.write(f"{myid}\n")
+    time.sleep(random.random() * 1)  # Simulate some work with the shared resource
+    # read the file
+    with open("shared_resource.txt", "r") as f:
+        data = f.read(len(myid))
+        if data != myid:
+            raise ValueError(f"file doesn't contain my id, but {data}")
+        print("data ok")
+
+
+def main():
+    myid = sys.argv[1]
+    print(f"myid is {myid}")
+
+    lock = Locker("shared_resource.txt")
+
+    for _ in range(5):
+        with lock.lock():
+            use_shared_resource(myid)
+        time.sleep(0.5)
+
+    sys.exit(0)
+
+
+main()

ekfsm-0.13.0a183.post1/tests/locking/test_lock.py

@@ -0,0 +1,30 @@
+import pytest
+import sys
+import subprocess
+import time
+
+# start 2 times test_lock.py and wait for them to finish
+
+
+def test_locking():
+    """
+    Test the locking mechanism by running two instances of the same script in parallel.
+    """
+
+    # Start the first instance
+    proc1 = subprocess.Popen([sys.executable, "tests/locking/lock_tester.py", "1"])
+    time.sleep(1)  # Give it some time to start
+
+    # Start the second instance
+    proc2 = subprocess.Popen([sys.executable, "tests/locking/lock_tester.py", "2"])
+
+    # Wait for both processes to finish
+    proc1.wait()
+    proc2.wait()
+
+    assert proc1.returncode == 0
+    assert proc2.returncode == 0
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])

ekfsm-0.13.0a183.post1/tests/sim/sys/devices/virtual/dmi/id/board_version

@@ -0,0 +1 @@
+1

{ekfsm-0.13.0a168.post1 → ekfsm-0.13.0a183.post1}/tests/zip2-ccu-only.yaml

@@ -1,5 +1,5 @@
 system_config:
-  name: "DB ZIP2 Test System"
+  name: "Test System"
   slots:
     - name: SYSTEM_SLOT
       slot_type: CPCI_S0_SYS

ekfsm-0.13.0a168.post1/tests/zip2-smoke.yaml → ekfsm-0.13.0a183.post1/tests/zip2-comp1.yaml

@@ -1,5 +1,7 @@
 system_config:
-  name: "DB ZIP2 Test System"
+  name: "ZIP2 Compute1"
+  aggregates:
+    chassis_inventory: inventory
   slots:
     - name: NETZ1
       slot_type: CPCI_S0_PSU
@@ -7,39 +9,51 @@ system_config:
       desired_hwmodule_name: psu
       attributes:
         slot_coding: 0x0
-    - name: SYSTEM_SLOT
+    - name: CPU1
       slot_type: CPCI_S0_SYS
       desired_hwmodule_type: EKF SC9-TOCCATA
-      desired_hwmodule_name: CPU1
+      desired_hwmodule_name: cpu
       attributes:
         is_master: true
-    - name: SLOT3
+    - name: LAN1
       slot_type: CPCI_S0_PER
-      desired_hwmodule_type: EKF SQ1-TRACK
-      desired_hwmodule_name: SQ1
+      desired_hwmodule_type: EKF SN4-DJEMBE
+      desired_hwmodule_name: lan
+      attributes:
+        slot_coding: 0x5
+    - name: SSD1
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SE5-CLUB
+      desired_hwmodule_name: ssd1
       attributes:
         slot_coding: 0x4
-    - name: SLOT4
+    - name: KOM1
       slot_type: CPCI_S0_PER
       desired_hwmodule_type: EKF SPV-MYSTIC
-      desired_hwmodule_name: SPV
+      desired_hwmodule_name: kom
       attributes:
         slot_coding: 0x3
-    - name: SLOT7
+    - name: IO1
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SQ1-TRACK
+      desired_hwmodule_name: io
+      attributes:
+        slot_coding: 0x2
+    - name: SSD2
       slot_type: CPCI_S0_PER
-      desired_hwmodule_type: EKF SQ3-QUARTET
-      desired_hwmodule_name: INFO
+      desired_hwmodule_type: EKF SE5-CLUB
+      desired_hwmodule_name: ssd2
       attributes:
         slot_coding: 0x1
-    - name: SLOT8
+    - name: SER1
       slot_type: CPCI_S0_PER
       desired_hwmodule_type: EKF SUR-UART
-      desired_hwmodule_name: SUR
+      desired_hwmodule_name: ser
       attributes:
         slot_coding: 0x0
-    - name: AUX_SLOT
+    - name: CCU
       slot_type: CPCI_S0_UTILITY
       desired_hwmodule_type: EKF CCU
-      desired_hwmodule_name: CCU
+      desired_hwmodule_name: ccu
       attributes:
         slot_coding: 0x7

ekfsm-0.13.0a183.post1/tests/zip2-comp1_smoke.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from ekfsm.system import System, HwModule
+import logging
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+
+
+def print_inventory(name, inventory):
+    print(f"{name}: {inventory.vendor()} {inventory.model()} {inventory.serial()}")
+
+
+def probe_and_print_inventory(board: HwModule):
+    board.probe()
+    print_inventory(board.name, board.inventory)
+
+
+config = Path(__file__).parent / "zip2-comp1.yaml"
+system = System(config, abort=False)
+print(system)
+
+_psu = system.psu
+probe_and_print_inventory(_psu)
+
+_cpu = system.cpu
+probe_and_print_inventory(_cpu)
+
+_lan = system.lan
+probe_and_print_inventory(_lan)
+
+_ssd1 = system.ssd1
+probe_and_print_inventory(_ssd1)
+
+_kom = system.kom
+probe_and_print_inventory(_kom)
+
+_io = system.io
+board = _io
+board.probe()
+print(f"inventory: {board.inventory.vendor()} {board.inventory.model()} ")
+
+probe_and_print_inventory(_io)
+
+_ssd2 = system.ssd2
+probe_and_print_inventory(_ssd2)
+
+_ser = system.ser
+probe_and_print_inventory(_ser)
+
+_ccu = system.ccu
+probe_and_print_inventory(_ccu)
+
+
+# SUR LED Test
+_ser.led_a.set(0, "red")
+_ser.led_a.set(1, "yellow")
+_ser.led_c.set(0, "white")
+_ser.led_d.set(1, "blue")
+
+print(f"SUR TEMP: {_ser.th.temperature()}")
+print(f"SUR HUMIDITY: {_ser.th.humidity()}")
+
+
+# CCU Test
+# chassis inventory via ccu object
+print_inventory("chassis", _ccu.chassis_inventory)
+# alternative way to get chassis inventory
+print_inventory("chassis", system.inventory)
+
+print(f"CCU firmware: {_ccu.management.identify_firmware()}")
+
+# SPV Test
+print(f"spv gpio0 control lines {_kom.gpio0.num_lines()}")
+print(f"spv gpio1 control lines {_kom.gpio1.num_lines()}")
+print(f"spv gpio2 control lines {_kom.gpio2.num_lines()}")

ekfsm-0.13.0a183.post1/tests/zip2-comp2.yaml

@@ -0,0 +1,59 @@
+system_config:
+  name: "ZIP2 Compute2"
+  aggregates:
+    chassis_inventory: inventory
+  slots:
+    - name: NETZ2
+      slot_type: CPCI_S0_PSU
+      desired_hwmodule_type: Hitron HDRC-300S
+      desired_hwmodule_name: psu
+      attributes:
+        slot_coding: 0x1
+    - name: CPU2
+      slot_type: CPCI_S0_SYS
+      desired_hwmodule_type: EKF SC9-TOCCATA
+      desired_hwmodule_name: cpu
+      attributes:
+        is_master: true
+    - name: LAN2
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SN4-DJEMBE
+      desired_hwmodule_name: lan
+      attributes:
+        slot_coding: 0x6
+    - name: SSD3
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SE5-CLUB
+      desired_hwmodule_name: ssd1
+      attributes:
+        slot_coding: 0x5
+    - name: SER2
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SUR-UART
+      desired_hwmodule_name: ser
+      attributes:
+        slot_coding: 0x4
+    - name: SSD4
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SE5-CLUB
+      desired_hwmodule_name: ssd2
+      attributes:
+        slot_coding: 0x3
+    - name: SSD5
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SE5-CLUB
+      desired_hwmodule_name: ssd3
+      attributes:
+        slot_coding: 0x2
+    - name: INFO
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SQ3-QUARTET
+      desired_hwmodule_name: info
+      attributes:
+        slot_coding: 0x1
+    - name: CCU
+      slot_type: CPCI_S0_UTILITY
+      desired_hwmodule_type: EKF CCU
+      desired_hwmodule_name: ccu
+      attributes:
+        slot_coding: 0x7