doc/configuration: document FTDI GPIO outputs

Document FTDIGPIO and NetworkFTDIGPIO resources for FTDI asynchronous
bit-bang data-bus outputs.

Signed-off-by: Ozan Durgut <ozan.durgut@analog.com>

Author: ozan956

doc/configuration.rst

@@ -575,6 +575,44 @@ Arguments:
 Used by:
   - `HIDRelayDriver`_
 
+FTDIGPIO
+++++++++
+An :class:`~labgrid.resource.udev.FTDIGPIO` resource describes a single FTDI
+data-bus GPIO line.
+This uses FTDI bit-bang mode for the 8-bit data bus exposed by the selected
+interface, not CBUS ``ftdi-cbus`` gpiochips or EEPROM-configured ACBUS
+functions.
+
+Supported devices are FT2232-style devices (``0403:6010``, interfaces 1..2),
+FT4232H (``0403:6011``, interfaces 1..4), and FT232H (``0403:6014``,
+interface 1). For each interface, ``index`` selects bit ``0`` to ``7`` on
+that interface's data bus.
+Writes use a read-modify-write cycle on the selected 8-bit interface to avoid
+changing unrelated bits managed by labgrid.
+
+.. code-block:: yaml
+
+   FTDIGPIO:
+     index: 0
+     interface: 1
+     invert: false
+     match:
+       ID_PATH: 'pci-0000:00:14.0-usb-0:2'
+
+Arguments:
+  - index (int): GPIO bit number to use, from ``0`` to ``7``
+  - interface (int, default=1): FTDI interface/channel number to use
+  - invert (bool, default=False): whether to invert the logical GPIO value
+  - match (dict): key and value pairs for a udev match, see `udev Matching`_
+
+Used by:
+  - `FTDIGPIODriver`_
+
+NetworkFTDIGPIO
++++++++++++++++
+A :any:`NetworkFTDIGPIO` describes an `FTDIGPIO`_ resource available on a
+remote computer.
+
 HttpDigitalOutput
 +++++++++++++++++
 An :any:`HttpDigitalOutput` resource describes a generic digital output that
@@ -2584,6 +2622,28 @@ Implements:
 Arguments:
   - None
 
+FTDIGPIODriver
+~~~~~~~~~~~~~~
+The :any:`FTDIGPIODriver` controls one `FTDIGPIO`_ or `NetworkFTDIGPIO`_ line
+via FTDI bit-bang GPIO output mode.
+
+The FTDI serial kernel driver must not be bound to the same interface.
+
+Binds to:
+  gpio:
+    - `FTDIGPIO`_
+    - `NetworkFTDIGPIO`_
+
+Implements:
+  - :any:`DigitalOutputProtocol`
+
+.. code-block:: yaml
+
+   FTDIGPIODriver: {}
+
+Arguments:
+  - None
+
 SerialPortDigitalOutputDriver
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The :any:`SerialPortDigitalOutputDriver` makes it possible to use a UART

tests/test_ftdigpiodriver.py

@@ -42,12 +42,38 @@ def device(vendor_id, model_id):
             },
         )
 
+    def child_device(parent):
+        return types.SimpleNamespace(
+            device_type="usb_interface",
+            find_parent=lambda subsystem, device_type: parent,
+        )
+
     assert resource.filter_match(device("0403", "6014")) is True
+    assert resource.filter_match(child_device(device("0403", "6014"))) is True
+    assert resource.filter_match(child_device(None)) is False
     assert resource.filter_match(device("0403", "6010")) is True
     assert resource.filter_match(device("0403", "6011")) is True
     assert resource.filter_match(device("0403", "6001")) is False
 
 
+def test_network_ftdigpio_resource_validates_range(target, monkeypatch):
+    monkeypatch.setattr(NetworkFTDIGPIO, "manager_cls", ResourceManager)
+    kwargs = {
+        "host": "exporter",
+        "busnum": 1,
+        "devnum": 39,
+        "path": "1-12.4.2",
+        "vendor_id": 0x0403,
+        "model_id": 0x6014,
+    }
+
+    with pytest.raises(ValueError):
+        NetworkFTDIGPIO(target, name=None, index=8, interface=1, **kwargs)
+
+    with pytest.raises(ValueError):
+        NetworkFTDIGPIO(target, name=None, index=0, interface=0, **kwargs)
+
+
 def test_ftdigpio_driver_create(target, monkeypatch):
     monkeypatch.setattr(NetworkFTDIGPIO, "manager_cls", ResourceManager)
     NetworkFTDIGPIO(
@@ -122,6 +148,12 @@ def close(self):
     target.deactivate(driver)
 
 
+def test_ftdigpio_driver_release_ignores_unknown_agent():
+    ftdigpiodriver._shared_agents.clear()
+
+    ftdigpiodriver._release_agent("exporter", 1, 39, 1)
+
+
 def test_ftdigpio_agent(monkeypatch):
     from labgrid.util.agents import ftdigpio
 
@@ -259,6 +291,125 @@ def ctrl_transfer(self, request_type, request, value, index, data, timeout=None)
         ftdigpio.handle_get(0x0403, 0x6014, 1, 39, 1, 3)
 
 
+def test_ftdigpio_agent_configures_device_after_usb_error(monkeypatch):
+    from labgrid.util.agents import ftdigpio
+
+    class FakeEndpoint:
+        bEndpointAddress = 0x02
+
+        def write(self, data, timeout=None):
+            pass
+
+    class FakeConfig:
+        def __getitem__(self, item):
+            assert item == (0, 0)
+            return [FakeEndpoint()]
+
+    class FakeDevice:
+        bus = 1
+        address = 39
+
+        def __init__(self):
+            self.active_config_attempts = 0
+            self.configured = False
+            self.detached = []
+
+        def set_configuration(self):
+            self.configured = True
+
+        def is_kernel_driver_active(self, interface):
+            assert interface == 0
+            return True
+
+        def detach_kernel_driver(self, interface):
+            self.detached.append(interface)
+
+        def get_active_configuration(self):
+            self.active_config_attempts += 1
+            if self.active_config_attempts == 1:
+                raise ftdigpio.usb.core.USBError("not configured")
+            return FakeConfig()
+
+        def ctrl_transfer(self, request_type, request, value, index, data, timeout=None):
+            if request_type == ftdigpio.IN_REQTYPE and request == ftdigpio.SIO_READ_PINS:
+                return b"\x00"
+            return None
+
+    device = FakeDevice()
+    monkeypatch.setattr(ftdigpio.usb.core, "find", lambda **kwargs: [device])
+    monkeypatch.setattr(ftdigpio.usb.util, "claim_interface", lambda dev, interface: None)
+    monkeypatch.setattr(ftdigpio.usb.util, "release_interface", lambda dev, interface: None)
+    monkeypatch.setattr(ftdigpio.usb.util, "dispose_resources", lambda dev: None)
+
+    assert ftdigpio.handle_get(0x0403, 0x6014, 1, 39, 1, 0) is False
+    assert device.configured is True
+    assert device.detached == [0, 0]
+
+
+def test_ftdigpio_agent_rejects_missing_output_endpoint(monkeypatch):
+    from labgrid.util.agents import ftdigpio
+
+    class FakeEndpoint:
+        bEndpointAddress = 0x81
+
+    class FakeConfig:
+        def __getitem__(self, item):
+            assert item == (0, 0)
+            return [FakeEndpoint()]
+
+    class FakeDevice:
+        bus = 1
+        address = 39
+
+        def set_configuration(self):
+            pass
+
+        def is_kernel_driver_active(self, interface):
+            return False
+
+        def get_active_configuration(self):
+            return FakeConfig()
+
+    device = FakeDevice()
+    monkeypatch.setattr(ftdigpio.usb.core, "find", lambda **kwargs: [device])
+    monkeypatch.setattr(ftdigpio.usb.util, "claim_interface", lambda dev, interface: None)
+
+    with pytest.raises(ValueError, match="output endpoint"):
+        ftdigpio.FTDIGPIO(0x0403, 0x6014, 1, 39, 1)
+
+
+def test_ftdigpio_agent_close_ignores_release_error(monkeypatch):
+    from labgrid.util.agents import ftdigpio
+
+    released = []
+    disposed = []
+    device = types.SimpleNamespace()
+    gpio = object.__new__(ftdigpio.FTDIGPIO)
+    gpio._dev = device
+    gpio._interface = 0
+
+    def release_interface(dev, interface):
+        released.append((dev, interface))
+        raise ftdigpio.usb.core.USBError("already released")
+
+    monkeypatch.setattr(ftdigpio.usb.util, "release_interface", release_interface)
+    monkeypatch.setattr(ftdigpio.usb.util, "dispose_resources", lambda dev: disposed.append(dev))
+
+    gpio.close()
+
+    assert released == [(device, 0)]
+    assert disposed == [device]
+
+
+def test_ftdigpio_agent_rejects_missing_device(monkeypatch):
+    from labgrid.util.agents import ftdigpio
+
+    monkeypatch.setattr(ftdigpio.usb.core, "find", lambda **kwargs: [])
+
+    with pytest.raises(ValueError, match="not found"):
+        ftdigpio.FTDIGPIO._find_device(0x0403, 0x6014, 1, 39)
+
+
 def test_ftdigpio_agent_rejects_unsupported_index():
     from labgrid.util.agents import ftdigpio