applet.{memory.25x,interface.qspi_controller}: improve pins help mess…

…age.

It was unclear how the IO0-3 pins correspond to COPI/CIPO/WP/HOLD pins.
Add the IO pin names to the pinout drawings for memory-25x, and add the
correspondence to `--pins-io` help message.

software/glasgow/access/direct/arguments.py

@@ -53,8 +53,9 @@ def _optional_pin_number(self, arg):
             return None
         return self._mandatory_pin_number(arg)
 
-    def _add_pin_argument(self, parser, name, default, required):
-        help = f"bind the applet I/O line {name!r} to pin NUM"
+    def _add_pin_argument(self, parser, name, default, required, help):
+        if help is None:
+            help = f"bind the applet I/O line {name!r} to pin NUM"
         if default is not None:
             default = PinArgument(default)
             help += f" (default: {default})"
@@ -91,8 +92,9 @@ def _pin_set(self, width, arg):
                             f"{width_desc} pins are required")
         return pin_args
 
-    def _add_pin_set_argument(self, parser, name, width, default, required):
-        help = f"bind the applet I/O lines {name!r} to pins SET"
+    def _add_pin_set_argument(self, parser, name, width, default, required, help):
+        if help is None:
+            help = f"bind the applet I/O lines {name!r} to pins SET"
         if default is not None:
             default = [PinArgument(number) for number in default]
             if default:
@@ -126,19 +128,19 @@ def _get_free(free_list):
     def add_build_arguments(self, parser):
         self._add_port_argument(parser, self._default_port)
 
-    def add_pin_argument(self, parser, name, default=None, required=False):
+    def add_pin_argument(self, parser, name, default=None, required=False, help=None):
         if default is True:
             default = self._get_free(self._free_pins)
-        self._add_pin_argument(parser, name, default, required)
+        self._add_pin_argument(parser, name, default, required, help)
 
-    def add_pin_set_argument(self, parser, name, width, default=None, required=False):
+    def add_pin_set_argument(self, parser, name, width, default=None, required=False, help=None):
         if isinstance(width, int):
             width = range(width, width + 1)
         if default is True and len(self._free_pins) >= width.start:
             default = [self._get_free(self._free_pins) for _ in range(width.start)]
         elif isinstance(default, int) and len(self._free_pins) >= default:
             default = [self._get_free(self._free_pins) for _ in range(default)]
-        self._add_pin_set_argument(parser, name, width, default, required)
+        self._add_pin_set_argument(parser, name, width, default, required, help)
 
     def add_run_arguments(self, parser):
         self._add_port_voltage_arguments(parser, default=None)

software/glasgow/access/simulation/arguments.py

@@ -18,8 +18,9 @@ def _optional_pin_number(self, arg):
             return None
         return self._mandatory_pin_number(arg)
 
-    def _add_pin_argument(self, parser, name, default, required):
-        help = f"bind the applet I/O line {name!r} to pin NUM"
+    def _add_pin_argument(self, parser, name, default, required, help):
+        if help is None:
+            help = f"bind the applet I/O line {name!r} to pin NUM"
         if default is not None:
             help += " (default: %(default)s)"
 
@@ -52,8 +53,9 @@ def _pin_set(self, width, arg):
             self._arg_error(f"set {arg} includes {len(numbers)} pins, but {width_desc} pins are required")
         return numbers
 
-    def _add_pin_set_argument(self, parser, name, width, default, required):
-        help = f"bind the applet I/O lines {name!r} to pins SET"
+    def _add_pin_set_argument(self, parser, name, width, default, required, help):
+        if help is None:
+            help = f"bind the applet I/O lines {name!r} to pins SET"
         if default is not None:
             if default:
                 help += " (default: %(default)s)"
@@ -76,19 +78,19 @@ def __init__(self, applet_name):
     def add_build_arguments(self, parser):
         pass
 
-    def add_pin_argument(self, parser, name, default=None, required=False):
+    def add_pin_argument(self, parser, name, default=None, required=False, help=None):
         if default is True:
             default = str(next(self._pin_iter))
-        self._add_pin_argument(parser, name, default, required)
+        self._add_pin_argument(parser, name, default, required, help)
 
-    def add_pin_set_argument(self, parser, name, width, default=None, required=False):
+    def add_pin_set_argument(self, parser, name, width, default=None, required=False, help=None):
         if isinstance(width, int):
             width = range(width, width + 1)
         if default is True:
             default = ",".join([str(next(self._pin_iter)) for _ in range(width.start)])
         elif isinstance(default, int):
             default = ",".join([str(next(self._pin_iter)) for _ in range(default)])
-        self._add_pin_set_argument(parser, name, width, default, required)
+        self._add_pin_set_argument(parser, name, width, default, required, help)
 
     def add_run_arguments(self, parser):
         pass

software/glasgow/applet/interface/qspi_controller/__init__.py

@@ -240,7 +240,8 @@ def add_build_arguments(cls, parser, access, *, include_pins=True):
 
         if include_pins:
             access.add_pin_argument(parser, "sck", default=True)
-            access.add_pin_set_argument(parser, "io", width=4, default=True)
+            access.add_pin_set_argument(parser, "io", width=4, default=True,
+                                        help="bind the applet I/O lines io (copi, cipo, io2, io3) to pins SET")
             access.add_pin_set_argument(parser, "cs", width=1, default=True)
 
         # Most devices that advertise QSPI support should work at 1 MHz.

software/glasgow/applet/memory/_25x/__init__.py

@@ -251,15 +251,15 @@ class Memory25xApplet(QSPIControllerApplet):
     The pinout of a typical 25-series IC is as follows:
 
     ::
-            16-pin             8-pin
-        HOLD# @ * SCK       CS# @ * VCC
-          VCC * * COPI     CIPO * * HOLD#
-          N/C * * N/C       WP# * * SCK
-          N/C * * N/C       GND * * COPI
-          N/C * * N/C
-          N/C * * N/C
-          CS# * * GND
-         CIPO * * WP#
+                16-pin                     8-pin
+        IO3/HOLD# @ * SCK               CS# @ * VCC
+              VCC * * IO0/COPI     IO1/CIPO * * IO3/HOLD#
+              N/C * * N/C           IO2/WP# * * SCK
+              N/C * * N/C               GND * * IO0/COPI
+              N/C * * N/C
+              N/C * * N/C
+              CS# * * GND
+         IO1/CIPO * * IO2/WP#
 
     The default pin assignment follows the pinouts above in the clockwise direction, making it easy
     to connect the memory with probes or, alternatively, crimp an IDC cable wired to a SOIC clip.
@@ -275,7 +275,8 @@ def add_build_arguments(cls, parser, access):
         super().add_build_arguments(parser, access, include_pins=False)
 
         access.add_pin_set_argument(parser, "cs",  width=1, required=True, default=[5])
-        access.add_pin_set_argument(parser, "io",  width=4, required=True, default=[2, 4, 3, 0])
+        access.add_pin_set_argument(parser, "io",  width=4, required=True, default=[2, 4, 3, 0],
+                                    help="bind the applet I/O lines io (copi, cipo, wp, hold) to pins SET")
         access.add_pin_argument(    parser, "sck",          required=True, default=1)
 
     async def run(self, device, args):