sdwire 0.3.1__tar.gz → 0.4.0__tar.gz

{sdwire-0.3.1 → sdwire-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sdwire
-Version: 0.3.1
+Version: 0.4.0
 Summary: CLI application to interact with Badgerd SDWire devices
 License: GPL-3
 Author: Talha Can Havadar
@@ -111,3 +111,19 @@ bdgrd_sdwirec_522	[sd-wire::SRPOL]
 ❯ sdwire switch host
 ```
 
+### SDWire3 and Linux USB power management
+
+On Linux, the SDWire3 only hands the SD card to the target while the USB device
+is runtime-suspended. `sdwire switch target` enables this automatically
+(`power/autosuspend_delay_ms=0`, `power/control=auto`) and verifies that
+`power/runtime_status` becomes `suspended`; otherwise it exits with an error.
+Writing to sysfs requires root, or install `udev/90-sdwire.rules`, which applies
+the setting when the device is plugged in.
+
+To do it by hand (replace `2-8` with your device's sysfs name, e.g. `5-1`):
+
+```
+echo 0    | sudo tee /sys/bus/usb/devices/2-8/power/autosuspend_delay_ms
+echo auto | sudo tee /sys/bus/usb/devices/2-8/power/control
+```
+

{sdwire-0.3.1 → sdwire-0.4.0}/README.md

@@ -94,3 +94,19 @@ bdgrd_sdwirec_522	[sd-wire::SRPOL]
 
 ❯ sdwire switch host
 ```
+
+### SDWire3 and Linux USB power management
+
+On Linux, the SDWire3 only hands the SD card to the target while the USB device
+is runtime-suspended. `sdwire switch target` enables this automatically
+(`power/autosuspend_delay_ms=0`, `power/control=auto`) and verifies that
+`power/runtime_status` becomes `suspended`; otherwise it exits with an error.
+Writing to sysfs requires root, or install `udev/90-sdwire.rules`, which applies
+the setting when the device is plugged in.
+
+To do it by hand (replace `2-8` with your device's sysfs name, e.g. `5-1`):
+
+```
+echo 0    | sudo tee /sys/bus/usb/devices/2-8/power/autosuspend_delay_ms
+echo auto | sudo tee /sys/bus/usb/devices/2-8/power/control
+```

{sdwire-0.3.1 → sdwire-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sdwire"
-version = "0.3.1"
+version = "0.4.0"
 description = "CLI application to interact with Badgerd SDWire devices"
 authors = ["Talha Can Havadar <havadartalha@gmail.com>"]
 license = "GPL-3"

{sdwire-0.3.1 → sdwire-0.4.0}/sdwire/backend/detect.py

@@ -17,6 +17,8 @@ import usb.util
 
 log = logging.getLogger(__name__)
 
+USB_HUB_CLASS = 9
+
 
 def get_sdwirec_devices() -> List[SDWireC]:
     """Detect and return all connected SDWireC devices.
@@ -25,7 +27,11 @@ def get_sdwirec_devices() -> List[SDWireC]:
         List of SDWireC device instances found on the system
     """
     try:
-        found_devices = usb.core.find(find_all=True)
+        # skip hubs: opening one blocks while the kernel enumerates a child port
+        found_devices = usb.core.find(
+            find_all=True,
+            custom_match=lambda d: d.bDeviceClass != USB_HUB_CLASS,
+        )
         devices = list(found_devices or [])
     except Exception as e:
         log.debug("Error finding USB devices: %s", e)

sdwire-0.4.0/sdwire/backend/device/power.py

@@ -0,0 +1,86 @@
+"""Linux USB runtime power-management helpers for SDWire3.
+
+The SDWire3 RTS5306E controller hands the SD card to the target side only when
+the USB device is runtime-suspended, which requires ``power/control == auto``.
+"""
+
+import logging
+import os
+import time
+
+log = logging.getLogger(__name__)
+
+SYSFS_USB_DEVICES = "/sys/bus/usb/devices"
+
+
+class PowerManagementError(RuntimeError):
+    """Raised when the device power state cannot be configured or verified."""
+
+
+class UsbPower:
+    def __init__(
+        self,
+        bus: int | None,
+        port_numbers,
+        root: str = SYSFS_USB_DEVICES,
+    ):
+        self.path: str | None = None
+        if bus is not None and port_numbers:
+            name = f"{bus}-{'.'.join(map(str, port_numbers))}"
+            self.path = os.path.join(root, name)
+
+    @property
+    def available(self) -> bool:
+        return self.path is not None and os.path.isdir(os.path.join(self.path, "power"))
+
+    def _file(self, name: str) -> str:
+        return os.path.join(self.path or "", "power", name)
+
+    def _read(self, name: str) -> str | None:
+        try:
+            with open(self._file(name)) as f:
+                return f.read().strip()
+        except OSError:
+            return None
+
+    def _write(self, name: str, value: str) -> None:
+        try:
+            with open(self._file(name), "w") as f:
+                f.write(value)
+        except PermissionError as e:
+            raise PowerManagementError(
+                f"permission denied writing '{value}' to {self._file(name)}; "
+                "run as root or install the udev rule from the udev/ directory"
+            ) from e
+        except OSError as e:
+            raise PowerManagementError(
+                f"failed to write '{value}' to {self._file(name)}: {e}"
+            ) from e
+
+    @property
+    def control(self) -> str | None:
+        return self._read("control")
+
+    @property
+    def runtime_status(self) -> str | None:
+        return self._read("runtime_status")
+
+    def enable_autosuspend(self) -> None:
+        """Set autosuspend delay to 0 and power/control to auto."""
+        if not self.available:
+            raise PowerManagementError(
+                "cannot locate the sysfs power directory of the SDWire3 device"
+            )
+        if self._read("autosuspend_delay_ms") != "0":
+            self._write("autosuspend_delay_ms", "0")
+        if self.control != "auto":
+            self._write("control", "auto")
+
+    def wait_for_status(self, expected: str, timeout: float = 5.0) -> bool:
+        deadline = time.monotonic() + timeout
+        while True:
+            if self.runtime_status == expected:
+                return True
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.1)

sdwire-0.4.0/sdwire/backend/device/sdwire.py

@@ -0,0 +1,139 @@
+import logging
+
+import usb.core
+import usb.util
+
+from sdwire.backend.block_device_utils import map_usb_device_to_block_device
+from sdwire.backend.device.power import PowerManagementError, UsbPower
+from sdwire.backend.device.usb_device import PortInfo, USBDevice
+
+log = logging.getLogger(__name__)
+
+SDWIRE_GENERATION_SDWIRE3 = 2
+
+
+class SDWire(USBDevice):
+    __block_dev = None
+
+    def __init__(self, port_info: PortInfo, generation: int):
+        super().__init__(port_info)
+        self.generation = generation
+        self._update_block_device()
+
+    @property
+    def power(self) -> UsbPower:
+        return UsbPower(
+            getattr(self.usb_device, "bus", None),
+            getattr(self.usb_device, "port_numbers", None),
+        )
+
+    def query_device_state(self):
+        """Return True when in host mode, False when in target mode."""
+        if not self.usb_device:
+            raise RuntimeError("USB device not available")
+
+        try:
+            host_attached = bool(self.usb_device.is_kernel_driver_active(0))
+        except NotImplementedError as e:
+            raise RuntimeError("state query is not supported on this platform") from e
+        power = self.power
+        if (
+            not host_attached
+            and power.available
+            and power.runtime_status != "suspended"
+        ):
+            log.warning(
+                "driver is detached but the device is not runtime-suspended "
+                "(power/control=%s, runtime_status=%s); the card is not switched to target",
+                power.control,
+                power.runtime_status,
+            )
+        return host_attached
+
+    def _release_usb_handle(self) -> None:
+        # an open usb handle keeps the device awake and prevents runtime suspend
+        usb.util.dispose_resources(self.usb_device)
+
+    def switch_ts(self) -> None:
+        if not self.usb_device:
+            raise RuntimeError("USB device not available")
+
+        try:
+            if self.usb_device.is_kernel_driver_active(0):
+                log.debug("already in ts mode")
+                return
+            self.usb_device.attach_kernel_driver(0)
+            self.usb_device.reset()
+        except (usb.core.USBError, NotImplementedError) as e:
+            if self.power.available:
+                raise
+            # platforms without sysfs (e.g. macOS) can't verify the switch,
+            # keep the previous non-fatal behaviour
+            log.warning("not able to switch to ts mode: %s", e)
+        self._release_usb_handle()
+
+    def switch_dut(self) -> None:
+        if not self.usb_device:
+            raise RuntimeError("USB device not available")
+
+        power = self.power
+        if power.available:
+            power.enable_autosuspend()
+        else:
+            log.debug("sysfs power control not found, cannot verify the switch")
+
+        try:
+            if self.usb_device.is_kernel_driver_active(0):
+                self.usb_device.detach_kernel_driver(0)
+                self.usb_device.reset()
+        except (usb.core.USBError, NotImplementedError) as e:
+            if power.available:
+                raise
+            log.warning("not able to switch to dut mode: %s", e)
+        self._release_usb_handle()
+
+        if power.available and not power.wait_for_status("suspended"):
+            raise PowerManagementError(
+                f"device did not runtime-suspend (power/control={power.control}, "
+                f"runtime_status={power.runtime_status}) at {power.path}; "
+                "the SD card is not connected to the target"
+            )
+
+    def _update_block_device(self) -> None:
+        """Update block device detection based on current device state."""
+        if not self.usb_device:
+            self.__block_dev = None
+            return
+
+        try:
+            storage_device = self.storage_device
+            if storage_device is not None:
+                self.__block_dev = map_usb_device_to_block_device(storage_device)
+                log.debug(f"SDWire3: Found block device: {self.__block_dev}")
+            else:
+                self.__block_dev = None
+        except Exception as e:
+            log.debug(f"SDWire3: Block device detection failed: {e}")
+            self.__block_dev = None
+
+    @property
+    def block_dev(self) -> str | None:
+        return self.__block_dev
+
+    @property
+    def storage_device(self) -> usb.core.Device | None:
+        """Return the USB device that corresponds to the storage interface.
+
+        For SDWire3, this is the same device we control (direct media controller).
+
+        Returns:
+            usb.core.Device: The USB device for storage, or None if not available
+        """
+        return self.usb_device
+
+    def __str__(self) -> str:
+        block_dev_str = self.block_dev if self.block_dev is not None else "None"
+        return f"{self.serial_string:<30}[{int(self.manufacturer_string):04x}::{int(self.product_string):04x}]\t\t{block_dev_str}"
+
+    def __repr__(self) -> str:
+        return self.__str__()

sdwire-0.3.1/sdwire/backend/device/sdwire.py

@@ -1,99 +0,0 @@
-import logging
-from typing import Optional
-import usb.core
-from sdwire.backend.device.usb_device import USBDevice, PortInfo
-from sdwire.backend.block_device_utils import map_usb_device_to_block_device
-
-log = logging.getLogger(__name__)
-
-SDWIRE_GENERATION_SDWIRE3 = 2
-
-
-class SDWire(USBDevice):
-    __block_dev = None
-
-    def __init__(self, port_info: PortInfo, generation: int):
-        super().__init__(port_info)
-        self.generation = generation
-        self._update_block_device()
-
-    def query_device_state(self):
-        if not self.usb_device:
-            log.error("USB device not available")
-            return
-
-        try:
-            state = self.usb_device.is_kernel_driver_active(0)
-            return state
-        except Exception as e:
-            log.debug(
-                "not able to query device state. err: %s",
-                e,
-            )
-
-    def switch_ts(self) -> None:
-        if not self.usb_device:
-            log.error("USB device not available")
-            return
-
-        try:
-            self.usb_device.attach_kernel_driver(0)
-            self.usb_device.reset()
-        except Exception as e:
-            log.debug(
-                "not able to switch to ts mode. Device might be already in ts mode, err: %s",
-                e,
-            )
-
-    def switch_dut(self) -> None:
-        if not self.usb_device:
-            log.error("USB device not available")
-            return
-
-        try:
-            self.usb_device.detach_kernel_driver(0)
-            self.usb_device.reset()
-        except Exception as e:
-            log.debug(
-                "not able to switch to dut mode. Device might be already in dut mode, err: %s",
-                e,
-            )
-
-    def _update_block_device(self) -> None:
-        """Update block device detection based on current device state."""
-        if not self.usb_device:
-            self.__block_dev = None
-            return
-
-        try:
-            storage_device = self.storage_device
-            if storage_device is not None:
-                self.__block_dev = map_usb_device_to_block_device(storage_device)
-                log.debug(f"SDWire3: Found block device: {self.__block_dev}")
-            else:
-                self.__block_dev = None
-        except Exception as e:
-            log.debug(f"SDWire3: Block device detection failed: {e}")
-            self.__block_dev = None
-
-    @property
-    def block_dev(self) -> Optional[str]:
-        return self.__block_dev
-
-    @property
-    def storage_device(self) -> Optional[usb.core.Device]:
-        """Return the USB device that corresponds to the storage interface.
-
-        For SDWire3, this is the same device we control (direct media controller).
-
-        Returns:
-            usb.core.Device: The USB device for storage, or None if not available
-        """
-        return self.usb_device
-
-    def __str__(self) -> str:
-        block_dev_str = self.block_dev if self.block_dev is not None else "None"
-        return f"{self.serial_string:<30}[{int(self.manufacturer_string):04x}::{int(self.product_string):04x}]\t\t{block_dev_str}"
-
-    def __repr__(self) -> str:
-        return self.__str__()