src/bsv/interface_decl.py

   1 import os.path
   2
   3 try:
   4     from UserDict import UserDict
   5 except ImportError:
   6     from collections import UserDict
   7
   8 from bsv.wire_def import generic_io  # special case
   9 from bsv.wire_def import muxwire  # special case
  10 from ifacebase import InterfacesBase
  11 from bsv.peripheral_gen import PeripheralIface
  12 from bsv.peripheral_gen import PeripheralInterfaces
  13
  14
  15 class Pin(object):
  16     """ pin interface declaration.
  17         * name is the name of the pin
  18         * ready, enabled and io all create a (* .... *) prefix
  19         * action changes it to an "in" if true
  20     """
  21
  22     def __init__(self, name,
  23                  name_ = None,
  24                  ready=True,
  25                  enabled=True,
  26                  io=False,
  27                  action=False,
  28                  bitspec=None,
  29                  outenmode=False):
  30         self.name = name
  31         self.name_ = name_
  32         self.ready = ready
  33         self.enabled = enabled
  34         self.io = io
  35         self.action = action
  36         self.bitspec = bitspec if bitspec else 'Bit#(1)'
  37         self.outenmode = outenmode
  38
  39     # bsv will look like this (method declaration):
  40     """
  41     (*always_ready,always_enabled*) method Bit#(1) io0_cell_outen;
  42     (*always_ready,always_enabled,result="io"*) method
  43                        Action io0_inputval (Bit#(1) in);
  44     """
  45
  46     def ifacepfmt(self, fmtfn):
  47         res = '          '
  48         status = []
  49         res += "interface "
  50         name = fmtfn(self.name_)
  51         if self.action:
  52             res += "Put"
  53         else:
  54             res += "Get"
  55         res += "#(%s) %s;" % (self.bitspec, name)
  56         return res
  57
  58     def ifacefmt(self, fmtfn):
  59         res = '    '
  60         status = []
  61         if self.ready:
  62             status.append('always_ready')
  63         if self.enabled:
  64             status.append('always_enabled')
  65         if self.io:
  66             status.append('result="io"')
  67         if status:
  68             res += '(*'
  69             res += ','.join(status)
  70             res += '*)'
  71         res += " method "
  72         if self.io:
  73             res += "\n                      "
  74         name = fmtfn(self.name)
  75         if self.action:
  76             res += " Action "
  77             res += name
  78             res += ' (%s in)' % self.bitspec
  79         else:
  80             res += " %s " % self.bitspec
  81             res += name
  82         res += ";"
  83         return res
  84
  85     def ifacedef(self, fmtoutfn, fmtinfn, fmtdecfn):
  86         res = '      method '
  87         if self.action:
  88             fmtname = fmtinfn(self.name)
  89             res += "Action  "
  90             res += fmtdecfn(self.name)
  91             res += '(%s in);\n' % self.bitspec
  92             res += '         %s<=in;\n' % fmtname
  93             res += '      endmethod'
  94         else:
  95             fmtname = fmtoutfn(self.name)
  96             res += "%s=%s;" % (self.name, fmtname)
  97         return res
  98     # sample bsv method definition :
  99     """
 100     method Action  cell0_mux(Bit#(2) in);
 101         wrcell0_mux<=in;
 102     endmethod
 103     """
 104
 105     # sample bsv wire (wire definiton):
 106     """
 107     Wire#(Bit#(2)) wrcell0_mux<-mkDWire(0);
 108     """
 109
 110     def wirefmt(self, fmtoutfn, fmtinfn, fmtdecfn):
 111         res = '      Wire#(%s) ' % self.bitspec
 112         if self.action:
 113             res += '%s' % fmtinfn(self.name)
 114         else:
 115             res += '%s' % fmtoutfn(self.name)
 116         res += "<-mkDWire(0);"
 117         return res
 118
 119     def ifacedef2(self, fmtoutfn, fmtinfn, fmtdecfn):
 120         if self.action:
 121             fmtname = fmtinfn(self.name)
 122             res =  "            interface %s = interface Put\n" % self.name_
 123             res += '              method '
 124             res += "Action put"
 125             #res += fmtdecfn(self.name)
 126             res += '(%s in);\n' % self.bitspec
 127             res += '                %s<=in;\n' % fmtname
 128             res += '              endmethod\n'
 129             res += '            endinterface;'
 130         else:
 131             fmtname = fmtoutfn(self.name)
 132             res =  "            interface %s = interface Get\n" % self.name_
 133             res += '              method ActionValue#'
 134             res += '(%s) get;\n' % self.bitspec
 135             res += "                return %s;\n" % (fmtname)
 136             res += '              endmethod\n'
 137             res += '            endinterface;'
 138         return res
 139
 140 class Interface(PeripheralIface):
 141     """ create an interface from a list of pinspecs.
 142         each pinspec is a dictionary, see Pin class arguments
 143         single indicates that there is only one of these, and
 144         so the name must *not* be extended numerically (see pname)
 145     """
 146     # sample interface object:
 147     """
 148     twiinterface_decl = Interface('twi',
 149                                   [{'name': 'sda', 'outen': True},
 150                                    {'name': 'scl', 'outen': True},
 151                                    ])
 152     """
 153
 154     def __init__(self, ifacename, pinspecs, ganged=None, single=False):
 155         PeripheralIface.__init__(self, ifacename)
 156         self.ifacename = ifacename
 157         self.ganged = ganged or {}
 158         self.pins = []  # a list of instances of class Pin
 159         self.pinspecs = pinspecs  # a list of dictionary
 160         self.single = single
 161
 162         for p in pinspecs:
 163             _p = {}
 164             _p.update(p)
 165             if 'type' in _p:
 166                 del _p['type']
 167             if p.get('outen') is True:  # special case, generate 3 pins
 168                 del _p['outen']
 169                 for psuffix in ['out', 'outen', 'in']:
 170                     # changing the name (like sda) to (twi_sda_out)
 171                     _p['name_'] = "%s_%s" % (p['name'], psuffix)
 172                     _p['name'] = "%s_%s" % (self.pname(p['name']), psuffix)
 173                     _p['action'] = psuffix != 'in'
 174                     self.pins.append(Pin(**_p))
 175                     # will look like {'name': 'twi_sda_out', 'action': True}
 176                     # {'name': 'twi_sda_outen', 'action': True}
 177                     #{'name': 'twi_sda_in', 'action': False}
 178                     # NOTice - outen key is removed
 179             else:
 180                 name = p['name']
 181                 if name.isdigit(): # HACK!  deals with EINT case
 182                     name = self.pname(name)
 183                 _p['name_'] = name
 184                 _p['name'] = self.pname(p['name'])
 185                 self.pins.append(Pin(**_p))
 186
 187     # sample interface object:
 188     """
 189         uartinterface_decl = Interface('uart',
 190                                    [{'name': 'rx'},
 191                                     {'name': 'tx', 'action': True},
 192                                     ])
 193     """
 194     """
 195     getifacetype is called multiple times in actual_pinmux.py
 196     x = ifaces.getifacetype(temp), where temp is uart_rx, spi_mosi
 197     Purpose is to identify is function : input/output/inout
 198     """
 199
 200     def getifacetype(self, name):
 201         for p in self.pinspecs:
 202             fname = "%s_%s" % (self.ifacename, p['name'])
 203             # print "search", self.ifacename, name, fname
 204             if fname == name:
 205                 if p.get('action'):
 206                     return 'out'
 207                 elif p.get('outen'):
 208                     return 'inout'
 209                 return 'input'
 210         return None
 211
 212     def iname(self):
 213         """ generates the interface spec e.g. flexbus_ale
 214             if there is only one flexbus interface, or
 215             sd{0}_cmd if there are several.  string format
 216             function turns this into sd0_cmd, sd1_cmd as
 217             appropriate.  single mode stops the numerical extension.
 218         """
 219         if self.single:
 220             return self.ifacename
 221         return '%s{0}' % self.ifacename
 222
 223     def pname(self, name):
 224         """ generates the interface spec e.g. flexbus_ale
 225             if there is only one flexbus interface, or
 226             sd{0}_cmd if there are several.  string format
 227             function turns this into sd0_cmd, sd1_cmd as
 228             appropriate.  single mode stops the numerical extension.
 229         """
 230         return "%s_%s" % (self.iname(), name)
 231
 232     def busfmt(self, *args):
 233         """ this function creates a bus "ganging" system based
 234             on input from the {interfacename}.txt file.
 235             only inout pins that are under the control of the
 236             interface may be "ganged" together.
 237         """
 238         if not self.ganged:
 239             return ''  # when self.ganged is None
 240         # print self.ganged
 241         res = []
 242         for (k, pnames) in self.ganged.items():
 243             name = self.pname('%senable' % k).format(*args)
 244             decl = 'Bit#(1) %s = 0;' % name
 245             res.append(decl)
 246             ganged = []
 247             for p in self.pinspecs:
 248                 if p['name'] not in pnames:
 249                     continue
 250                 pname = self.pname(p['name']).format(*args)
 251                 if p.get('outen') is True:
 252                     outname = self.ifacefmtoutfn(pname)
 253                     ganged.append("%s_outen" % outname)  # match wirefmt
 254
 255             gangedfmt = '{%s} = duplicate(%s);'
 256             res.append(gangedfmt % (',\n  '.join(ganged), name))
 257         return '\n'.join(res) + '\n\n'
 258
 259     def wirefmt(self, *args):
 260         res = '\n'.join(map(self.wirefmtpin, self.pins)).format(*args)
 261         res += '\n'
 262         return '\n' + res
 263
 264     def ifacepfmt(self, *args):
 265         res = '\n'.join(map(self.ifacepfmtdecpin, self.pins)).format(*args)
 266         return '\n' + res  # pins is a list
 267
 268     def ifacefmt(self, *args):
 269         res = '\n'.join(map(self.ifacefmtdecpin, self.pins)).format(*args)
 270         return '\n' + res  # pins is a list
 271
 272     def ifacepfmtdecfn(self, name):
 273         return name
 274
 275     def ifacefmtdecfn(self, name):
 276         return name  # like: uart
 277
 278     def ifacefmtdecfn2(self, name):
 279         return name  # like: uart
 280
 281     def ifacefmtdecfn3(self, name):
 282         """ HACK! """
 283         return "%s_outen" % name  # like uart_outen
 284
 285     def ifacefmtoutfn(self, name):
 286         return "wr%s" % name  # like wruart
 287
 288     def ifacefmtinfn(self, name):
 289         return "wr%s" % name
 290
 291     def wirefmtpin(self, pin):
 292         return pin.wirefmt(self.ifacefmtoutfn, self.ifacefmtinfn,
 293                            self.ifacefmtdecfn2)
 294
 295     def ifacepfmtdecpin(self, pin):
 296         return pin.ifacepfmt(self.ifacepfmtdecfn)
 297
 298     def ifacefmtdecpin(self, pin):
 299         return pin.ifacefmt(self.ifacefmtdecfn)
 300
 301     def ifacefmtpin(self, pin):
 302         decfn = self.ifacefmtdecfn2
 303         outfn = self.ifacefmtoutfn
 304         # print pin, pin.outenmode
 305         if pin.outenmode:
 306             decfn = self.ifacefmtdecfn3
 307             outfn = self.ifacefmtoutenfn
 308         return pin.ifacedef(outfn, self.ifacefmtinfn,
 309                             decfn)
 310
 311     def ifacedef2pin(self, pin):
 312         decfn = self.ifacefmtdecfn2
 313         outfn = self.ifacefmtoutfn
 314         # print pin, pin.outenmode
 315         if pin.outenmode:
 316             decfn = self.ifacefmtdecfn3
 317             outfn = self.ifacefmtoutenfn
 318         return pin.ifacedef2(outfn, self.ifacefmtinfn,
 319                             decfn)
 320
 321     def ifacedef(self, *args):
 322         res = '\n'.join(map(self.ifacefmtpin, self.pins))
 323         res = res.format(*args)
 324         return '\n' + res + '\n'
 325
 326     def ifacedef2(self, *args):
 327         res = '\n'.join(map(self.ifacedef2pin, self.pins))
 328         res = res.format(*args)
 329         return '\n' + res + '\n'
 330
 331
 332 class MuxInterface(Interface):
 333
 334     def wirefmt(self, *args):
 335         return muxwire.format(*args)
 336
 337
 338 class IOInterface(Interface):
 339
 340     def ifacefmtoutenfn(self, name):
 341         return "cell{0}_mux_outen"
 342
 343     def ifacefmtoutfn(self, name):
 344         """ for now strip off io{0}_ part """
 345         return "cell{0}_mux_out"
 346
 347     def ifacefmtinfn(self, name):
 348         return "cell{0}_mux_in"
 349
 350     def wirefmt(self, *args):
 351         return generic_io.format(*args)
 352
 353
 354 class Interfaces(InterfacesBase, PeripheralInterfaces):
 355     """ contains a list of interface definitions
 356     """
 357
 358     def __init__(self, pth=None):
 359         InterfacesBase.__init__(self, Interface, pth)
 360         PeripheralInterfaces.__init__(self)
 361
 362     def ifacedef(self, f, *args):
 363         for (name, count) in self.ifacecount:
 364             for i in range(count):
 365                 f.write(self.data[name].ifacedef(i))
 366
 367     def ifacedef2(self, f, *args):
 368         c = "        interface {0} = interface PeripheralSide{1}"
 369         for (name, count) in self.ifacecount:
 370             for i in range(count):
 371                 iname = self.data[name].iname().format(i)
 372                 f.write(c.format(iname, name.upper()))
 373                 f.write(self.data[name].ifacedef2(i))
 374                 f.write("        endinterface;\n\n")
 375
 376     def busfmt(self, f, *args):
 377         f.write("import BUtils::*;\n\n")
 378         for (name, count) in self.ifacecount:
 379             for i in range(count):
 380                 bf = self.data[name].busfmt(i)
 381                 f.write(bf)
 382
 383     def ifacepfmt(self, f, *args):
 384         comment = '''
 385       // interface declaration between {0} and pinmux
 386       (*always_ready,always_enabled*)
 387       interface PeripheralSide{0};'''
 388         for (name, count) in self.ifacecount:
 389             f.write(comment.format(name.upper()))
 390             f.write(self.data[name].ifacepfmt(0))
 391             f.write("\n      endinterface\n")
 392
 393     def ifacefmt(self, f, *args):
 394         comment = '''
 395           // interface declaration between %s-{0} and pinmux'''
 396         for (name, count) in self.ifacecount:
 397             for i in range(count):
 398                 c = comment % name.upper()
 399                 f.write(c.format(i))
 400                 f.write(self.data[name].ifacefmt(i))
 401
 402     def ifacefmt2(self, f, *args):
 403         comment = '''
 404             interface PeripheralSide{0} {1};'''
 405         for (name, count) in self.ifacecount:
 406             for i in range(count):
 407                 iname = self.data[name].iname().format(i)
 408                 f.write(comment.format(name.upper(), iname))
 409
 410     def wirefmt(self, f, *args):
 411         comment = '\n      // following wires capture signals ' \
 412                   'to IO CELL if %s-{0} is\n' \
 413                   '      // allotted to it'
 414         for (name, count) in self.ifacecount:
 415             for i in range(count):
 416                 c = comment % name
 417                 f.write(c.format(i))
 418                 f.write(self.data[name].wirefmt(i))
 419
 420
 421 # ========= Interface declarations ================ #
 422
 423 mux_interface = MuxInterface('cell',
 424                              [{'name': 'mux', 'ready': False, 'enabled': False,
 425                                'bitspec': '{1}', 'action': True}])
 426
 427 io_interface = IOInterface(
 428     'io',
 429     [{'name': 'cell_out', 'enabled': True, },
 430      {'name': 'cell_outen', 'enabled': True, 'outenmode': True, },
 431      {'name': 'cell_in', 'action': True, 'io': True}, ])
 432
 433 # == Peripheral Interface definitions == #
 434 # these are the interface of the peripherals to the pin mux
 435 # Outputs from the peripherals will be inputs to the pinmux
 436 # module. Hence the change in direction for most pins
 437
 438 # ======================================= #
 439
 440 # basic test
 441 if __name__ == '__main__':
 442
 443     uartinterface_decl = Interface('uart',
 444                                    [{'name': 'rx'},
 445                                     {'name': 'tx', 'action': True},
 446                                     ])
 447
 448     twiinterface_decl = Interface('twi',
 449                                   [{'name': 'sda', 'outen': True},
 450                                    {'name': 'scl', 'outen': True},
 451                                    ])
 452
 453     def _pinmunge(p, sep, repl, dedupe=True):
 454         """ munges the text so it's easier to compare.
 455             splits by separator, strips out blanks, re-joins.
 456         """
 457         p = p.strip()
 458         p = p.split(sep)
 459         if dedupe:
 460             p = filter(lambda x: x, p)  # filter out blanks
 461         return repl.join(p)
 462
 463     def pinmunge(p):
 464         """ munges the text so it's easier to compare.
 465         """
 466         # first join lines by semicolons, strip out returns
 467         p = p.split(";")
 468         p = map(lambda x: x.replace('\n', ''), p)
 469         p = '\n'.join(p)
 470         # now split first by brackets, then spaces (deduping on spaces)
 471         p = _pinmunge(p, "(", " ( ", False)
 472         p = _pinmunge(p, ")", " ) ", False)
 473         p = _pinmunge(p, " ", " ")
 474         return p
 475
 476     def zipcmp(l1, l2):
 477         l1 = l1.split("\n")
 478         l2 = l2.split("\n")
 479         for p1, p2 in zip(l1, l2):
 480             print (repr(p1))
 481             print (repr(p2))
 482             print ()
 483             assert p1 == p2
 484
 485     ifaces = Interfaces()
 486
 487     ifaceuart = ifaces['uart']
 488     print (ifaceuart.ifacedef(0))
 489     print (uartinterface_decl.ifacedef(0))
 490     assert ifaceuart.ifacedef(0) == uartinterface_decl.ifacedef(0)
 491
 492     ifacetwi = ifaces['twi']
 493     print (ifacetwi.ifacedef(0))
 494     print (twiinterface_decl.ifacedef(0))
 495     assert ifacetwi.ifacedef(0) == twiinterface_decl.ifacedef(0)