driver: add RKUSBMaskromDriver bootstrap driver

Add a RKUSBMaskromDriver bootstrap driver with an accompanying
rkusbmaskrom agent to support bootstrapping targets with Rockchip SoCs.

The rkusbmaskrom agent expects the target to be in MASKROM mode and send
images to BootROM using vendor specific 0x471 and 0x472 control
transfers, in 4 KiB chunks.

The first image is loaded to SRAM using 0x471 and is expected to
initialize DRAM and then return back to BootROM. A second image can then
be loaded to start of DRAM using 0x472.

Signed-off-by: Jonas Karlman <[email protected]>

Author: Kwiboo

doc/configuration.rst

@@ -784,6 +784,7 @@ Arguments:
 
 Used by:
   - `RKUSBDriver`_
+  - `RKUSBMaskromDriver`_
 
 NetworkMXSUSBLoader
 ~~~~~~~~~~~~~~~~~~~
@@ -2638,6 +2639,39 @@ Arguments:
   - usb_loader (str): optional, key in :ref:`images <labgrid-device-config-images>` containing the path
     of a first-stage bootloader image to write
 
+RKUSBMaskromDriver
+~~~~~~~~~~~~~~~~~~
+An :any:`RKUSBMaskromDriver` is used to upload an image into a device in the
+*Rockchip USB Maskrom state*.
+This is useful to bootstrap a bootloader onto a device.
+
+Binds to:
+  loader:
+    - `RKUSBLoader`_
+    - `NetworkRKUSBLoader`_
+
+Implements:
+  - :any:`BootstrapProtocol`
+
+.. code-block:: yaml
+
+   targets:
+     main:
+       drivers:
+         RKUSBMaskromDriver:
+           initial: 'rkmaskrom471'
+           image: 'rkmaskrom472'
+
+   images:
+     rkmaskrom471: 'path/to/u-boot-rockchip-usb471.bin'
+     rkmaskrom472: 'path/to/u-boot-rockchip-usb472.bin'
+
+Arguments:
+  - initial (str): optional, key in :ref:`images <labgrid-device-config-images>` containing the path
+    of an image that typically initializes DRAM of the target
+  - image (str): optional, key in :ref:`images <labgrid-device-config-images>` containing the path
+    of a bootloader image to load to start of DRAM, or to SRAM when an initial image is unused
+
 UUUDriver
 ~~~~~~~~~
 A :any:`UUUDriver` is used to upload an image into a device in the *NXP USB

labgrid/driver/__init__.py

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

labgrid/driver/usbloader.py

@@ -3,8 +3,10 @@
 
 from ..factory import target_factory
 from ..protocol import BootstrapProtocol
+from ..resource.remote import NetworkRKUSBLoader
 from ..step import step
 from .common import Driver
+from ..util.agentwrapper import AgentWrapper
 from ..util.managedfile import ManagedFile
 from ..util.timeout import Timeout
 from ..util.helper import processwrapper
@@ -149,6 +151,53 @@ def load(self, filename=None):
                     raise
 
 
+@target_factory.reg_driver
+@attr.s(eq=False)
+class RKUSBMaskromDriver(Driver, BootstrapProtocol):
+    bindings = {"loader": {"RKUSBLoader", NetworkRKUSBLoader}}
+    initial = attr.ib(default=None)
+    image = attr.ib(default=None)
+    delay = attr.ib(default=0.0, validator=attr.validators.instance_of(float))
+
+    def __attrs_post_init__(self):
+        super().__attrs_post_init__()
+        self.wrapper = None
+
+    def on_activate(self):
+        if isinstance(self.loader, NetworkRKUSBLoader):
+            host = self.loader.host
+        else:
+            host = None
+        self.wrapper = AgentWrapper(host)
+        self.proxy = self.wrapper.load('rkusbmaskrom')
+
+    def on_deactivate(self):
+        self.proxy = None
+        if self.wrapper:
+            self.wrapper.close()
+        self.wrapper = None
+
+    @Driver.check_active
+    @step(args=['filename'])
+    def load(self, filename=None):
+        images = []
+        if self.initial is not None:
+            images.append(self.target.env.config.get_image_path(self.initial))
+        if not filename and self.image is not None:
+            filename = self.target.env.config.get_image_path(self.image)
+        if filename:
+            images.append(filename)
+        if not images:
+            raise Exception("No images to load")
+
+        args = [self.loader.busnum, self.loader.devnum]
+        for path in images:
+            mf = ManagedFile(path, self.loader)
+            mf.sync_to_resource()
+            args.append(mf.get_remote_path())
+        self.proxy.load(*args, delay=self.delay)
+
+
 @target_factory.reg_driver
 @attr.s(eq=False)
 class UUUDriver(Driver, BootstrapProtocol):

labgrid/util/agents/rkusbmaskrom.py

@@ -0,0 +1,141 @@
+"""
+This module implements the communication protocol to load an image to SRAM,
+that typically initializes DRAM, followed by optionally loading a secondary
+image to start of DRAM, when a Rockchip device is in MASKROM mode.
+"""
+from time import sleep
+
+import usb.core
+import usb.util
+
+
+RK_RC4_KEY = [
+    0x7c, 0x4e, 0x03, 0x04, 0x55, 0x05, 0x09, 0x07,
+    0x2d, 0x2c, 0x7b, 0x38, 0x17, 0x0d, 0x17, 0x11,
+]
+
+
+# polynomial: 0x1021
+CRC16_TABLE = [
+    0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
+    0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef,
+    0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6,
+    0x9339, 0x8318, 0xb37b, 0xa35a, 0xd3bd, 0xc39c, 0xf3ff, 0xe3de,
+    0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4, 0x5485,
+    0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee, 0xf5cf, 0xc5ac, 0xd58d,
+    0x3653, 0x2672, 0x1611, 0x0630, 0x76d7, 0x66f6, 0x5695, 0x46b4,
+    0xb75b, 0xa77a, 0x9719, 0x8738, 0xf7df, 0xe7fe, 0xd79d, 0xc7bc,
+    0x48c4, 0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823,
+    0xc9cc, 0xd9ed, 0xe98e, 0xf9af, 0x8948, 0x9969, 0xa90a, 0xb92b,
+    0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12,
+    0xdbfd, 0xcbdc, 0xfbbf, 0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a,
+    0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41,
+    0xedae, 0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49,
+    0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13, 0x2e32, 0x1e51, 0x0e70,
+    0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78,
+    0x9188, 0x81a9, 0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e, 0xe16f,
+    0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046, 0x6067,
+    0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c, 0xe37f, 0xf35e,
+    0x02b1, 0x1290, 0x22f3, 0x32d2, 0x4235, 0x5214, 0x6277, 0x7256,
+    0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e, 0xe54f, 0xd52c, 0xc50d,
+    0x34e2, 0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
+    0xa7db, 0xb7fa, 0x8799, 0x97b8, 0xe75f, 0xf77e, 0xc71d, 0xd73c,
+    0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634,
+    0xd94c, 0xc96d, 0xf90e, 0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab,
+    0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3,
+    0xcb7d, 0xdb5c, 0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a,
+    0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1, 0x1ad0, 0x2ab3, 0x3a92,
+    0xfd2e, 0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9,
+    0x7c26, 0x6c07, 0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1,
+    0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9, 0x9ff8,
+    0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1, 0x1ef0,
+]
+
+
+def crc16_ccitt_false(data, crc=0xffff):
+    for byte in data:
+        crc = ((crc << 8) & 0xff00) ^ CRC16_TABLE[((crc >> 8) & 0xff) ^ byte]
+    return crc & 0xffff
+
+
+def rc4_ksa(key):
+    keylength = len(key)
+    S = list(range(256))
+    j = 0
+    for i in range(256):
+        j = (j + S[i] + key[i % keylength]) % 256
+        S[i], S[j] = S[j], S[i]
+    return S
+
+
+def rc4_prga(S):
+    i = 0
+    j = 0
+    while True:
+        i = (i + 1) % 256
+        j = (j + S[i]) % 256
+        S[i], S[j] = S[j], S[i]
+        K = S[(S[i] + S[j]) % 256]
+        yield K
+
+
+class RKUSBMaskrom:
+    def __init__(self, **args):
+        self._dev = usb.core.find(**args)
+        if self._dev is None:
+            raise ValueError("Device not found")
+        if self._dev.idVendor != 0x2207:
+            raise ValueError(f"Unsupported device VID {self._dev.idVendor:x}")
+        if self._dev.bcdUSB & 0x0001:
+            raise ValueError("Device in LOADER mode")
+
+    def __enter__(self):
+        if self._dev.is_kernel_driver_active(0):
+            self._dev.detach_kernel_driver(0)
+        usb.util.claim_interface(self._dev, 0)
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        usb.util.release_interface(self._dev, 0)
+        usb.util.dispose_resources(self._dev)
+
+    def load(self, code, path):
+        with open(path, 'rb') as fh:
+            data = bytearray(fh.read())
+
+        # encrypt data using the known rockchip key for older devices
+        if self._dev.idProduct < 0x3500:
+            keystream = rc4_prga(rc4_ksa(RK_RC4_KEY))
+            data = bytearray([byte ^ next(keystream) for byte in data])
+
+        # ensure crc16 fit in the last chunk
+        if len(data) % 4096 == 4095:
+            data.append(0)
+
+        # append crc16 of data
+        crc = crc16_ccitt_false(data)
+        data.append(crc >> 8)
+        data.append(crc & 0xff)
+
+        # extra chunk to signal end of transfer
+        if len(data) % 4096 == 0:
+            data.append(0)
+
+        # transfer all chunks
+        for i in range(0, len(data), 4096):
+            chunk = data[i:i + 4096]
+            self._dev.ctrl_transfer(64, 12, 0, code, chunk, 5000)
+
+
+def handle_load(busnum, devnum, initial, secondary=None, delay=None):
+    with RKUSBMaskrom(bus=busnum, address=devnum) as maskrom:
+        maskrom.load(0x471, initial)
+        if secondary is not None:
+            if delay:
+                sleep(delay)
+            maskrom.load(0x472, secondary)
+
+
+methods = {
+    "load": handle_load,
+}

tests/test_agent.py

@@ -106,6 +106,9 @@ def test_all_modules():
     methods = aw.list()
     assert 'sysfsgpio.set' in methods
     assert 'sysfsgpio.get' in methods
+    aw.load('rkusbmaskrom')
+    methods = aw.list()
+    assert 'rkusbmaskrom.load' in methods
     aw.load('usb_hid_relay')
     methods = aw.list()
     assert 'usb_hid_relay.set' in methods
@@ -114,4 +117,4 @@ def test_all_modules():
 def test_import_modules():
     import labgrid.util.agents
     import labgrid.util.agents.dummy
-    from labgrid.util.agents import deditec_relais8, sysfsgpio
+    from labgrid.util.agents import deditec_relais8, rkusbmaskrom, sysfsgpio

tests/test_rkusbmaskromagent.py

@@ -0,0 +1,19 @@
+from labgrid.util.agents.rkusbmaskrom import (crc16_ccitt_false, rc4_ksa,
+                                              rc4_prga)
+
+
+def test_crc16_ccitt_false():
+    crc = crc16_ccitt_false("123456789".encode())
+    assert crc == 0x29b1
+
+
+def test_rc4_keystream():
+    # from RFC 6229: Test Vectors for the Stream Cipher RC4
+    key = list(bytes.fromhex("1ada31d5cf688221c109163908ebe51debb46227c6cc8b37641910833222772a"))
+    keystream = rc4_prga(rc4_ksa(key))
+    assert [next(keystream) for _ in range(16)] == list(bytes.fromhex("dd5bcb0018e922d494759d7c395d02d3"))
+    assert [next(keystream) for _ in range(16)] == list(bytes.fromhex("c8446f8f77abf737685353eb89a1c9eb"))
+    for _ in range(4048):
+        next(keystream)
+    assert [next(keystream) for _ in range(16)] == list(bytes.fromhex("d5a39e3dfcc50280bac4a6b5aa0dca7d"))
+    assert [next(keystream) for _ in range(16)] == list(bytes.fromhex("370b1c1fe655916d97fd0d47ca1d72b8"))