From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Thu, 24 Sep 2020 20:00:56 +0000 (+0100)
Subject: add comments
X-Git-Tag: 24jan2021_ls180~327
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=0596c8f65bba6f87300c1eb422cb1c6f06203e42;p=soc.git

add comments
---

diff --git a/src/soc/debug/jtag.py b/src/soc/debug/jtag.py
index b1091dac..e920b1ac 100644
--- a/src/soc/debug/jtag.py
+++ b/src/soc/debug/jtag.py
@@ -14,11 +14,12 @@ iotypes = {'-': IOType.In,
            '+': IOType.Out,
            '*': IOType.InTriOut}
 
+
 # TODO: move to suitable location
 class Pins:
-
+    """declare a list of pins, including name and direction.  grouped by fn
+    """
     def __init__(self):
-
         # sigh this needs to come from pinmux.
         gpios = []
         for i in range(16):
@@ -26,7 +27,7 @@ class Pins:
         self.io_names = {'serial': ['tx+', 'rx-'], 'gpio': gpios}
 
     def __iter__(self):
-        # start parsing io_names and create IOConn Records
+        # start parsing io_names and enumerate them to return pin specs
         for fn, pins in self.io_names.items():
             for pin in pins:
                 # decode the pin name and determine the c4m jtag io type
@@ -35,19 +36,14 @@ class Pins:
                 pin_name = "%s_%s" % (fn, name)
                 yield (fn, name, iotype, pin_name)
 
+
 class JTAG(DMITAP, Pins):
     def __init__(self):
         DMITAP.__init__(self, ir_width=4)
         Pins.__init__(self)
 
-        # sigh this needs to come from pinmux.
-        gpios = []
-        for i in range(16):
-            gpios.append("gpio%d*" % i)
-        self.io_names = {'serial': ['tx+', 'rx-'], 'gpio': gpios}
-
-        # start parsing io_names and create IOConn Records
-        self.ios = []
+        # enumerate pin specs and create IOConn Records.
+        self.ios = [] # these are enumerated in external_ports
         for fn, pin, iotype, pin_name in list(self):
             self.ios.append(self.add_io(iotype=iotype, name=pin_name))
 
@@ -68,11 +64,13 @@ class JTAG(DMITAP, Pins):
         return m
 
     def external_ports(self):
-        ports = super().external_ports()
-        ports += list(self.wb.fields.values())
+        """create a list of ports that goes into the top level il (or verilog)
+        """
+        ports = super().external_ports()           # gets JTAG signal names
+        ports += list(self.wb.fields.values())     # wishbone signals
         for io in self.ios:
-            ports += list(io.core.fields.values())
-            ports += list(io.pad.fields.values())
+            ports += list(io.core.fields.values()) # io "core" signals
+            ports += list(io.pad.fields.values())  # io "pad" signals"
         return ports