[ot] scripts/opentitan: spidevflash.py: add support for Unix connection and retry count

Signed-off-by: Emmanuel Blot <eblot@rivosinc.com>

Author: rivos-eblot

docs/opentitan/spidevflash.md

@@ -5,33 +5,43 @@
 ## Usage
 
 ````text
-usage: spidevflash.py [-h] -f FILE [-a ADDRESS] [-r HOST] [-p PORT] [-v] [-d]
+usage: spidevflash.py [-h] -f FILE [-a ADDRESS] [-S SOCKET] [-R RETRY_COUNT]
+                      [-r HOST] [-p PORT] [-v] [-d]
 
 SPI device flasher tool.
 
 options:
   -h, --help            show this help message and exit
-  -f FILE, --file FILE  Binary file to flash
-  -a ADDRESS, --address ADDRESS
-                        Address in the SPI flash (default to 0)
-  -r HOST, --host HOST  remote host name (default: localhost)
-  -p PORT, --port PORT  remote host TCP port (defaults to 8004)
+  -f, --file FILE       Binary file to flash
+  -a, --address ADDRESS
+                        Address in the SPI flash (default: 0)
+  -S, --socket SOCKET   connection string
+  -R, --retry-count RETRY_COUNT
+                        connection retry count (default: 1)
+  -r, --host HOST       remote host name (default: localhost)
+  -p, --port PORT       remote host TCP port (defaults to 8004)
   -v, --verbose         increase verbosity
   -d, --debug           enable debug mode
 ````
 
 ### Arguments
 
-* `-a` specify an alernative start address
+* `-a` specify an alernative start address'
 
 * `-d` only useful to debug the script, reports any Python traceback to the standard error stream.
 
-* `-f` specify the binary file to upload
+* `-f` specify the binary file to upload'
 
-* `-p` specify an alternative port for the TCP connection on the QEMU instance
+* `-p` specify an alternative port for the TCP connection on the QEMU instance. Mutually exclusive
+  with `-S`.
 
-* `-r` specify the name or address of the remote host running the QEMU instance
+* `-R` specify the number of connection attempts before giving up.
 
+* `-r` specify the name or address of the remote host running the QEMU instance. Mutually exclusive
+  with `-S`.
+
+* `-S` specify a connection string to the remote host running the QEMU instance, _e.g._
+  `tcp:localhost:8004` or `unix:/tmp/socket`. Mutually exclusive with `-r` and `-p`.
 * `-v` can be repeated to increase verbosity of the script, mostly for debug purpose.
 
 ### Examples

scripts/opentitan/spidevflash.py

@@ -5,7 +5,7 @@
    :author: Emmanuel Blot <eblot@rivosinc.com>
 """
 
-# Copyright (c) 2024 Rivos, Inc.
+# Copyright (c) 2024-2025 Rivos, Inc.
 # SPDX-License-Identifier: Apache2
 
 from argparse import ArgumentParser, FileType
@@ -14,6 +14,7 @@
 from os.path import dirname, join as joinpath, normpath
 from time import sleep, time as now
 from traceback import format_exc
+from typing import Optional
 import sys
 
 QEMU_PYPATH = joinpath(dirname(dirname(dirname(normpath(__file__)))),
@@ -35,9 +36,30 @@ def __init__(self):
         self._log = getLogger('spidev.flash')
         self._spidev = SpiDevice()
 
-    def connect(self, host: str, port: int):
-        """Connect to the remote SPI device and wait for sync."""
-        self._spidev.connect(host, port)
+    def connect(self, host: str, port: Optional[int], retry_count: int = 1,
+                sync_time: Optional[float] = None):
+        """Connect to the remote SPI device and wait for sync.
+
+           :param host: a hostname or a connection string
+           :param port: a TCP port, should be None if a connection string is
+                        defined
+           :param retry_count: how many attempts should be made at most to
+                               coonnect to the remote peer (once per second)
+           :param sync_time: max allowed synchronization time once a connection
+                             is established to receive a valid JEDEC ID.
+
+           Supported connection string format:
+            - tcp:<host>:<port>
+            - unix:<path>
+        """
+        while True:
+            try:
+                self._spidev.connect(host, port)
+                break
+            except TimeoutError:
+                retry_count -= 1
+                if not retry_count:
+                    raise
         self._wait_for_remote()
 
     def disconnect(self):
@@ -95,12 +117,14 @@ def main():
                                help='Binary file to flash')
         argparser.add_argument('-a', '--address', type=HexInt.parse,
                                default='0',
-                               help='Address in the SPI flash (default to 0)')
+                               help='Address in the SPI flash (default: 0)')
+        argparser.add_argument('-S', '--socket',
+                               help='connection string')
+        argparser.add_argument('-R', '--retry-count', type=int, default=1,
+                               help='connection retry count (default: 1)')
         argparser.add_argument('-r', '--host',
-                               default='127.0.0.1',
                                help='remote host name (default: localhost)')
         argparser.add_argument('-p', '--port', type=int,
-                               default=SpiDeviceFlasher.DEFAULT_PORT,
                                help=f'remote host TCP port (defaults to '
                                     f'{SpiDeviceFlasher.DEFAULT_PORT})')
         argparser.add_argument('-v', '--verbose', action='count',
@@ -113,7 +137,15 @@ def main():
         configure_loggers(args.verbose, 'spidev')
 
         flasher = SpiDeviceFlasher()
-        flasher.connect(args.host, args.port)
+        if args.socket:
+            if any((args.host, args.port)):
+                argparser.error('Connection string is mutually exclusive '
+                                'with host and port')
+            flasher.connect(args.socket, None, retry_count=args.retry_count)
+        else:
+            flasher.connect(args.host or 'localhost',
+                            args.port or SpiDeviceFlasher.DEFAULT_PORT,
+                            retry_count=args.retry_count)
         data = args.file.read()
         args.file.close()
         flasher.program(data, args.address)