From 3a1aff2122316a1bdd264266c33461f7f5f0097b Mon Sep 17 00:00:00 2001
From: Luke Kenneth Casson Leighton <lkcl@lkcl.net>
Date: Mon, 9 Nov 2020 12:00:04 +0000
Subject: [PATCH] add code comments for ioring-to-niolib conversion of JSON
 pinspec files

---
 experiments9/doDesign.py | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/experiments9/doDesign.py b/experiments9/doDesign.py
index 13535f3..3f847f0 100644
--- a/experiments9/doDesign.py
+++ b/experiments9/doDesign.py
@@ -15,7 +15,7 @@ import plugins
 from   Hurricane  import DbU
 if True: # change this to False to get errors to "go away" so that
          # print / debug statements in generation of spec can be seen
-         # without the critical dependence of having to run via "cgt"
+         # without the hard dependence of having to run via "cgt"
     from   plugins.alpha.block.configuration import IoPin
     from   plugins.alpha.block.block         import Block
     from   plugins.alpha.block.configuration import GaugeConf
@@ -26,7 +26,8 @@ if True: # change this to False to get errors to "go away" so that
 
 af = CRL.AllianceFramework.get()
 
-
+# converts unicode strings to utf-8 because coriolis2 python code is expecting
+# str not unicode
 def _byteify(data, ignore_dicts = False):
     # if this is a unicode string, return its string representation
     if isinstance(data, unicode):
@@ -64,6 +65,20 @@ chip.update({ 'pads.ioPadGauge' : 'niolib',
           'chip.clockTree'  : True,
        })
 
+# this function is the equivalent of statically-declared io pad specs.
+# it is not ok to have io declared manually, duplicated in (literally) 5
+# different places, too many mistakes can be made and changes are a
+# nightmare.
+#
+# therefore the pinmux code takes responsibility for declaring the pinouts,
+# generates a JSON file which is read (above) and *creates* the list from
+# that auto-generated file.  the core, litex peripheral code, *and* the C4M
+# JTAG Boundary Scan code do *EXACTLY* the same thing and in this way they
+# all "match".
+#
+# here we do some weirdness to convert from the ioring.py pads list format over
+# to the new niolib format.
+
 def generate_spec():
     # convert old ioring format to ioPadsSpec
     ioPadsSpec = []
@@ -80,19 +95,26 @@ def generate_spec():
         #    sides[side] = {}
         for pinname in chip[side]:
             sides[pinname] = io_pin_spec
+
     # now go through pads.instances
     pprint (sides)
     for pad in chip['pads.instances']:
         padname = pad[0]
         padside = sides[padname]
         print ("padside", padname, padside)
+
+        # format here is ['padname', 'to core', 'from core', 'direction']
+        # where direction is "+" for out, "-" for in, "*" for bi-directionaly
         if len(pad) == 4:
+            print("4-long io", pad)
             if pad[-1] == '-':
                 en_sig = 'io_in'
             if pad[-1] == '+':
                 en_sig = 'io_out'
             padspec = [padside, None, padname, pad[1], pad[2], en_sig]
-            print("4-long io", pad)
+
+        # format here is:
+        # ['padname', 'something', 'to core', 'from core', 'en', 'direction']
         elif len(pad) == 6:
             print("6-long io", pad)
             padspec = [padside, None, padname] + pad[1:5]
@@ -101,6 +123,7 @@ def generate_spec():
             assert False
         print ("padspec", padspec)
         ioPadsSpec.append(tuple(padspec))
+
     return ioPadsSpec
 
 ioPadsSpec = generate_spec()
-- 
2.30.2