driver/usbloader: rename RKUSBDriver to reflect rkdeveloptool usage

To interact with a Rockchip SoC in BootROM mode over USB, Rockchip
offers the rkdeveloptool, which is among others already packaged in
Debian.

We currently support this via the RKUSBDriver, which binds to the
RKUSBLoader resource, which currently lists a single VID/PID pair.

Actually making use of this is where things get confusing:
Labgrid will look up the rk-usb-loader key to find rkdeveloptool and then
fall back to a binary named `rk-usb-loader`. To my knowledge, no one names
their rkdeveloptool that way and `rk-usb-loader` has since become the
name of the Rockchip USB loader distributed by barebox.

On systems, like the LXA TAC, this is doubly confusing: There's a
rk-usb-loader binary, which Labgrid would use by default, but it's not
compatible with rkdeveloptool, supports only the RK35xx SoCs barebox
supports and is currently not supported by Labgrid at all.

Given that RKUSBLoader only supports a single SoC, our documentation is
wrong (it references the unrelated barebox' rk-usb-loader) and that
our usage of rkdeveloptool goes beyond the BootROM's USB protocol and
additionally flashes persistent media by talking to a first stage
usb_loader that's uploaded first, I think the best course of action
is to rename both the driver and the tool key to reflect that
rkdeveloptool is actually used.

Signed-off-by: Ahmad Fatoum <[email protected]>

CHANGES.rst

@@ -47,6 +47,11 @@ Other breaking changes include:
   maintained vxi11 module which again uses the deprecated (and in Python 3.13
   removed) xdrlib. See
   `issue #1507 <https://github.com/labgrid-project/labgrid/issues/1507>`_.
+- ``RKUSBDriver`` has been renamed to `RKDevelopToolUSBDriver` and its
+  ``rk-usb-loader`` tool key is now called ``rkdeveloptool``.
+  This better reflects what is used under the hood and avoids conflation
+  with the unrelated barebox' ``rk-usb-loader``, which even Labgrid's own
+  docs got wrong.
 
 Known issues in 24.1
 ~~~~~~~~~~~~~~~~~~~~
@@ -524,7 +529,7 @@ New Features in 0.3.0
   allowing custom configuration in the user's ``.ssh/config`` as needed.
   Note that not all drivers have been updated to use the ProxyManager yet.
 - Deditec RELAIS8 devices are now supported by the `DeditecRelaisDriver`.
-- The `RKUSBDriver` was added to support the rockchip serial download mode.
+- The ``RKUSBDriver`` was added to support the rockchip serial download mode.
 - The `USBStorageDriver` gained support for BMAP.
 - Flashrom support added, by hard-wiring e.g. an exporter to the DUT, the ROM
   on the DUT can be written directly. The flashrom driver implements the

doc/configuration.rst

@@ -713,7 +713,7 @@ Arguments:
   - match (dict): key and value pairs for a udev match, see `udev Matching`_
 
 Used by:
-  - `RKUSBDriver`_
+  - `RKDevelopToolUSBDriver`_
 
 NetworkMXSUSBLoader
 ~~~~~~~~~~~~~~~~~~~
@@ -2445,9 +2445,9 @@ Implements:
 Arguments:
   - None
 
-RKUSBDriver
-~~~~~~~~~~~
-An :any:`RKUSBDriver` is used to upload an image into a device in the *Rockchip
+RKDevelopToolUSBDriver
+~~~~~~~~~~~~~~~~~~~~~~
+An :any:`RKDevelopToolUSBDriver` is used to upload an image into a device in the *Rockchip
 USB loader state*.
 This is useful to bootstrap a bootloader onto a device.
 
@@ -2464,7 +2464,7 @@ Implements:
    targets:
      main:
        drivers:
-         RKUSBDriver:
+         RKDevelopToolUSBDriver:
            image: 'mybootloaderkey'
            usb_loader: 'myloaderkey'
 

labgrid/driver/__init__.py

@@ -16,7 +16,7 @@
                          DigitalOutputPowerDriver, YKUSHPowerDriver, \
                          USBPowerDriver, SiSPMPowerDriver, NetworkPowerDriver, \
                          PDUDaemonDriver
-from .usbloader import MXSUSBDriver, IMXUSBDriver, BDIMXUSBDriver, RKUSBDriver, UUUDriver
+from .usbloader import MXSUSBDriver, IMXUSBDriver, BDIMXUSBDriver, RKDevelopToolUSBDriver, UUUDriver
 from .usbsdmuxdriver import USBSDMuxDriver
 from .usbsdwiredriver import USBSDWireDriver
 from .common import Driver

labgrid/driver/usbloader.py

@@ -87,7 +87,7 @@ def load(self, filename=None):
 
 @target_factory.reg_driver
 @attr.s(eq=False)
-class RKUSBDriver(Driver, BootstrapProtocol):
+class RKDevelopToolUSBDriver(Driver, BootstrapProtocol):
     bindings = {
         "loader": {"RKUSBLoader", "NetworkRKUSBLoader"},
     }
@@ -99,9 +99,9 @@ def __attrs_post_init__(self):
         super().__attrs_post_init__()
         # FIXME make sure we always have an environment or config
         if self.target.env:
-            self.tool = self.target.env.config.get_tool('rk-usb-loader')
+            self.tool = self.target.env.config.get_tool('rkdeveloptool')
         else:
-            self.tool = 'rk-usb-loader'
+            self.tool = 'rkdeveloptool'
 
     def on_activate(self):
         pass

labgrid/remote/client.py

@@ -1098,7 +1098,7 @@ def bootstrap(self):
                         drv = OpenOCDDriver(target, name=name, **args)
                     drv.interface.timeout = self.args.wait
                 elif isinstance(resource, NetworkRKUSBLoader):
-                    drv = self._get_driver_or_new(target, "RKUSBDriver", activate=False, name=name)
+                    drv = self._get_driver_or_new(target, "RKDevelopToolUSBDriver", activate=False, name=name)
                     drv.loader.timeout = self.args.wait
                 if drv:
                     break

man/labgrid-device-config.5

@@ -128,9 +128,9 @@ See:  <https://openocd.org/>
 Path to the quartus_hps binary, used by the QuartusHPSDriver.
 See:  <https://www.intel.com/content/www/us/en/docs/programmable/683039/22\-3/hps\-flash\-programmer.html> 
 .TP
-.B \fBrk\-usb\-loader\fP
-Path to the rk\-usb\-loader binary, used by the RKUSBDriver.
-See:  <https://git.pengutronix.de/cgit/barebox/tree/scripts/rk\-usb\-loader.c> 
+.B \fBrkdeveloptool\fP
+Path to the \fBrkdeveloptool\fP binary, used by the RKDevelopToolUSBDriver.
+See:  <https://github.com/rockchip\-linux/rkdeveloptool>
 .TP
 .B \fBsd\-mux\-ctrl\fP
 Path to the sd\-mux\-ctrl binary, used by the USBSDWireDriver.

man/labgrid-device-config.rst

@@ -127,9 +127,9 @@ TOOLS KEYS
     Path to the quartus_hps binary, used by the QuartusHPSDriver.
     See: https://www.intel.com/content/www/us/en/docs/programmable/683039/22-3/hps-flash-programmer.html
 
-``rk-usb-loader``
-    Path to the rk-usb-loader binary, used by the RKUSBDriver.
-    See: https://git.pengutronix.de/cgit/barebox/tree/scripts/rk-usb-loader.c
+``rkdeveloptool``
+    Path to the ``rkdeveloptool`` binary, used by the RKDevelopToolUSBDriver.
+    See: https://github.com/rockchip-linux/rkdeveloptool
 
 ``sd-mux-ctrl``
     Path to the sd-mux-ctrl binary, used by the USBSDWireDriver.