Adding comments to interface_decl.py

diff --git a/src/bsv/interface_decl.py b/src/bsv/interface_decl.py
index 9405c8dd2f99ac6a1d98be37b0ce9bac6853fda9..b63d48782fbcd4705c17d9f596692ded0d156820 100644 (file)
--- a/src/bsv/interface_decl.py
+++ b/src/bsv/interface_decl.py
@@ -31,6 +31,12 @@ class Pin(object):
         self.bitspec = bitspec if bitspec else 'Bit#(1)'
         self.outenmode = outenmode
 
+    # bsv will look like this (method declaration):
+    """
+    (*always_ready,always_enabled*) method Bit#(1) io0_cell_outen;
+    (*always_ready,always_enabled,result="io"*) method
+                       Action io0_inputval (Bit#(1) in);
+    """
     def ifacefmt(self, fmtfn):
         res = '    '
         status = []
@@ -58,6 +64,12 @@ class Pin(object):
         res += ";"
         return res
 
+    # sample bsv method definition :
+    """
+    method Action  cell0_mux(Bit#(2) in);
+        wrcell0_mux<=in;
+    endmethod
+    """
     def ifacedef(self, fmtoutfn, fmtinfn, fmtdecfn):
         res = '      method '
         if self.action:
@@ -71,7 +83,10 @@ class Pin(object):
             fmtname = fmtoutfn(self.name)
             res += "%s=%s;" % (self.name, fmtname)
         return res
-
+    #sample bsv wire (wire definiton):
+    """
+    Wire#(Bit#(2)) wrcell0_mux<-mkDWire(0);
+    """
     def wirefmt(self, fmtoutfn, fmtinfn, fmtdecfn):
         res = '      Wire#(%s) ' % self.bitspec
         if self.action:
@@ -88,12 +103,18 @@ class Interface(object):
         single indicates that there is only one of these, and
         so the name must *not* be extended numerically (see pname)
     """
-
+    #sample interface object:
+    """
+    twiinterface_decl = Interface('twi',
+                                  [{'name': 'sda', 'outen': True},
+                                   {'name': 'scl', 'outen': True},
+                                   ])
+    """
     def __init__(self, ifacename, pinspecs, ganged=None, single=False):
         self.ifacename = ifacename
         self.ganged = ganged or {}
-        self.pins = []
-        self.pinspecs = pinspecs
+        self.pins = [] # a list of instances of class Pin
+        self.pinspecs = pinspecs # a list of dictionary
         self.single = single
         for p in pinspecs:
             _p = {}
@@ -101,13 +122,30 @@ class Interface(object):
             if p.get('outen') is True:  # special case, generate 3 pins
                 del _p['outen']
                 for psuffix in ['out', 'outen', 'in']:
+                    # changing the name (like sda) to (twi_sda_out)
                     _p['name'] = "%s_%s" % (self.pname(p['name']), psuffix)
                     _p['action'] = psuffix != 'in'
                     self.pins.append(Pin(**_p))
+                    #will look like {'name': 'twi_sda_out', 'action': True}
+                    # {'name': 'twi_sda_outen', 'action': True}
+                    #{'name': 'twi_sda_in', 'action': False}
+                    # NOTice - outen key is removed
             else:
                 _p['name'] = self.pname(p['name'])
                 self.pins.append(Pin(**_p))
 
+    # sample interface object:
+    """
+        uartinterface_decl = Interface('uart',
+                                   [{'name': 'rx'},
+                                    {'name': 'tx', 'action': True},
+                                    ])
+    """
+    """
+    getifacetype is called multiple times in actual_pinmux.py
+    x = ifaces.getifacetype(temp), where temp is uart_rx, spi_mosi
+    Purpose is to identify is function : input/output/inout
+    """
     def getifacetype(self, name):
         for p in self.pinspecs:
             fname = "%s_%s" % (self.ifacename, p['name'])
@@ -138,7 +176,7 @@ class Interface(object):
             interface may be "ganged" together.
         """
         if not self.ganged:
-            return ''
+            return '' # when self.ganged is None
         #print self.ganged
         res = []
         for (k, pnames) in self.ganged.items():
@@ -165,20 +203,20 @@ class Interface(object):
 
     def ifacefmt(self, *args):
         res = '\n'.join(map(self.ifacefmtdecpin, self.pins)).format(*args)
-        return '\n' + res
+        return '\n' + res # pins is a list
 
     def ifacefmtdecfn(self, name):
-        return name
+        return name # like: uart
 
     def ifacefmtdecfn2(self, name):
-        return name
+        return name # like: uart
 
     def ifacefmtdecfn3(self, name):
         """ HACK! """
-        return "%s_outen" % name
+        return "%s_outen" % name #like uart_outen
 
     def ifacefmtoutfn(self, name):
-        return "wr%s" % name
+        return "wr%s" % name #like wruart
 
     def ifacefmtinfn(self, name):
         return "wr%s" % name
@@ -245,8 +283,14 @@ class Interfaces(UserDict):
             for ln in ifile.readlines():
                 ln = ln.strip()
                 ln = ln.split("\t")
-                name = ln[0]
-                count = int(ln[1])
+                name = ln[0] # will have uart
+                count = int(ln[1]) # will have count of uart
+                #spec looks like this:
+                """
+                [{'name': 'sda', 'outen': True},
+                 {'name': 'scl', 'outen': True},
+                ]
+                """
                 spec, ganged = self.read_spec(pth, name)
                 iface = Interface(name, spec, ganged, count == 1)
                 self.ifaceadd(name, count, iface)
@@ -261,10 +305,12 @@ class Interfaces(UserDict):
 
     def ifaceadd(self, name, count, iface, at=None):
         if at is None:
-            at = len(self.ifacecount)
-        self.ifacecount.insert(at, (name, count))
+            at = len(self.ifacecount)# ifacecount is a list
+        self.ifacecount.insert(at, (name, count))# appends the list
+        # with (name,count) *at* times
         self[name] = iface
 
+    # will check specific peripheral.txt files like spi.txt
     def read_spec(self, pth, name):
         spec = []
         ganged = {}
@@ -276,9 +322,9 @@ class Interfaces(UserDict):
                 ln = ln.strip()
                 ln = ln.split("\t")
                 name = ln[0]
-                d = {'name': name}
+                d = {'name': name}# here we start to make the dictionary
                 if ln[1] == 'out':
-                    d['action'] = True
+                    d['action'] = True # adding element to the dict
                 elif ln[1] == 'inout':
                     d['outen'] = True
                     if len(ln) == 3: