src/add/pipeline.py

   1 """ Example 5: Making use of PyRTL and Introspection. """
   2
   3 from collections.abc import Sequence
   4
   5 from nmigen import Signal
   6 from nmigen.hdl.rec import Record
   7 from nmigen import tracer
   8 from nmigen.compat.fhdl.bitcontainer import value_bits_sign
   9 from contextlib import contextmanager
  10
  11 from singlepipe import eq, StageCls, ControlBase, BufferedPipeline
  12 from singlepipe import UnbufferedPipeline
  13
  14
  15 # The following example shows how pyrtl can be used to make some interesting
  16 # hardware structures using python introspection.  In particular, this example
  17 # makes a N-stage pipeline structure.  Any specific pipeline is then a derived
  18 # class of SimplePipeline where methods with names starting with "stage" are
  19 # stages, and new members with names not starting with "_" are to be registered
  20 # for the next stage.
  21
  22 def like(value, rname, pipe, pipemode=False):
  23     if isinstance(value, ObjectProxy):
  24         return ObjectProxy.like(pipe, value, pipemode=pipemode,
  25                                 name=rname, reset_less=True)
  26     else:
  27         return Signal(value_bits_sign(value), name=rname,
  28                              reset_less=True)
  29         return Signal.like(value, name=rname, reset_less=True)
  30
  31 def get_assigns(_assigns):
  32     assigns = []
  33     for e in _assigns:
  34         if isinstance(e, ObjectProxy):
  35             assigns += get_assigns(e._assigns)
  36         else:
  37             assigns.append(e)
  38     return assigns
  39
  40
  41 def get_eqs(_eqs):
  42     eqs = []
  43     for e in _eqs:
  44         if isinstance(e, ObjectProxy):
  45             eqs += get_eqs(e._eqs)
  46         else:
  47             eqs.append(e)
  48     return eqs
  49
  50
  51 class ObjectProxy:
  52     def __init__(self, m, name=None, pipemode=False):
  53         self._m = m
  54         if name is None:
  55             name = tracer.get_var_name(default=None)
  56         self.name = name
  57         self._pipemode = pipemode
  58         self._eqs = []
  59         self._assigns = []
  60         self._preg_map = {}
  61
  62     @classmethod
  63     def like(cls, m, value, pipemode=False, name=None, src_loc_at=0, **kwargs):
  64         name = name or tracer.get_var_name(depth=2 + src_loc_at,
  65                                             default="$like")
  66
  67         src_loc_at_1 = 1 + src_loc_at
  68         r = ObjectProxy(m, value.name, pipemode)
  69         #for a, aname in value._preg_map.items():
  70         #    r._preg_map[aname] = like(a, aname, m, pipemode)
  71         for a in value.ports():
  72             aname = a.name
  73             r._preg_map[aname] = like(a, aname, m, pipemode)
  74         return r
  75
  76     def __repr__(self):
  77         subobjs = []
  78         for a in self.ports():
  79             aname = a.name
  80             ai = self._preg_map[aname]
  81             subobjs.append(repr(ai))
  82         return "<OP %s>" % subobjs
  83
  84     def get_specs(self, liked=False):
  85         res = []
  86         for k, v in self._preg_map.items():
  87             #v = like(v, k, stage._m)
  88             res.append(v)
  89             if isinstance(v, ObjectProxy):
  90                 res += v.get_specs()
  91         return res
  92
  93     def eq(self, i):
  94         print ("ObjectProxy eq", self, i)
  95         res = []
  96         for a in self.ports():
  97             aname = a.name
  98             ai = i._preg_map[aname]
  99             res.append(a.eq(ai))
 100         return res
 101
 102     def ports(self):
 103         res = []
 104         for aname, a in self._preg_map.items():
 105             if isinstance(a, Signal) or isinstance(a, ObjectProxy) or \
 106                isinstance(a, Record):
 107                 res.append(a)
 108         #print ("ObjectPorts", res)
 109         return res
 110
 111     def __getattr__(self, name):
 112         try:
 113             v = self._preg_map[name]
 114             return v
 115             #return like(v, name, self._m)
 116         except KeyError:
 117             raise AttributeError(
 118                 'error, no pipeline register "%s" defined for OP %s'
 119                 % (name, self.name))
 120
 121     def __setattr__(self, name, value):
 122         if name.startswith('_') or name in ['name', 'ports', 'eq', 'like']:
 123             # do not do anything tricky with variables starting with '_'
 124             object.__setattr__(self, name, value)
 125             return
 126         #rname = "%s_%s" % (self.name, name)
 127         rname = name
 128         new_pipereg = like(value, rname, self._m, self._pipemode)
 129         self._preg_map[name] = new_pipereg
 130         #object.__setattr__(self, name, new_pipereg)
 131         if self._pipemode:
 132             print ("OP pipemode", new_pipereg, value)
 133             #self._m.d.comb += eq(new_pipereg, value)
 134             pass
 135         elif self._m:
 136             print ("OP !pipemode assign", new_pipereg, value, type(value))
 137             self._m.d.comb += eq(new_pipereg, value)
 138         else:
 139             print ("OP !pipemode !m", new_pipereg, value, type(value))
 140             self._assigns += eq(new_pipereg, value)
 141             if isinstance(value, ObjectProxy):
 142                 print ("OP, defer assigns:", value._assigns)
 143                 self._assigns += value._assigns
 144                 self._eqs.append(value._eqs)
 145
 146
 147 class PipelineStage:
 148     """ Pipeline builder stage with auto generation of pipeline registers.
 149     """
 150
 151     def __init__(self, name, m, prev=None, pipemode=False, ispec=None):
 152         self._m = m
 153         self._stagename = name
 154         self._preg_map = {'__nextstage__': {}}
 155         self._prev_stage = prev
 156         self._ispec = ispec
 157         if prev:
 158             print ("prev", prev._stagename, prev._preg_map)
 159             if prev._stagename in prev._preg_map:
 160                 m = prev._preg_map[prev._stagename]
 161                 self._preg_map[prev._stagename] = m
 162                 #for k, v in m.items():
 163                     #m[k] = like(v, k, self._m)
 164             if '__nextstage__' in prev._preg_map:
 165                 m = prev._preg_map['__nextstage__']
 166                 self._preg_map[self._stagename] = m
 167                 #for k, v in m.items():
 168                     #m[k] = like(v, k, self._m)
 169                 print ("make current", self._stagename, m)
 170         self._pipemode = pipemode
 171         self._eqs = []
 172         self._assigns = []
 173
 174     def __getattr__(self, name):
 175         #if name in self._preg_map['__nextstage__']:
 176         #    return self._preg_map['__nextstage__'][name]
 177         try:
 178             v = self._preg_map[self._stagename][name]
 179             return v
 180             #return like(v, name, self._m)
 181         except KeyError:
 182             raise AttributeError(
 183                 'error, no pipeline register "%s" defined for stage %s'
 184                 % (name, self._stagename))
 185
 186     def __setattr__(self, name, value):
 187         if name.startswith('_'):
 188             # do not do anything tricky with variables starting with '_'
 189             object.__setattr__(self, name, value)
 190             return
 191         pipereg_id = self._stagename
 192         rname = 'pipereg_' + pipereg_id + '_' + name
 193         new_pipereg = like(value, rname, self._m, self._pipemode)
 194         next_stage = '__nextstage__'
 195         if next_stage not in self._preg_map:
 196             self._preg_map[next_stage] = {}
 197         self._preg_map[next_stage][name] = new_pipereg
 198         if self._pipemode:
 199             self._eqs.append(new_pipereg)
 200             assign = eq(new_pipereg, value)
 201             print ("pipemode: append", new_pipereg, value, assign)
 202             if isinstance(value, ObjectProxy):
 203                 print ("OP, assigns:", value._assigns)
 204                 self._assigns += value._assigns
 205                 self._eqs += value._eqs
 206             #self._m.d.comb += assign
 207             self._assigns += assign
 208         elif self._m:
 209             print ("!pipemode: assign", new_pipereg, value)
 210             assign = eq(new_pipereg, value)
 211             self._m.d.sync += assign
 212         else:
 213             print ("!pipemode !m: defer assign", new_pipereg, value)
 214             assign = eq(new_pipereg, value)
 215             self._assigns += assign
 216             if isinstance(value, ObjectProxy):
 217                 print ("OP, defer assigns:", value._assigns)
 218                 self._assigns += value._assigns
 219                 self._eqs += value._eqs
 220
 221 def likelist(specs):
 222     res = []
 223     for v in specs:
 224         res.append(like(v, v.name, None, pipemode=True))
 225     return res
 226
 227
 228 class AutoStage(StageCls):
 229     def __init__(self, inspecs, outspecs, eqs, assigns):
 230         self.inspecs, self.outspecs = inspecs, outspecs
 231         self.eqs, self.assigns = eqs, assigns
 232         #self.o = self.ospec()
 233     def ispec(self): return likelist(self.inspecs)
 234     def ospec(self): return likelist(self.outspecs)
 235
 236     def process(self, i):
 237         print ("stage process", i)
 238         return self.outspecs
 239
 240     def setup(self, m, i):
 241         print ("stage setup i", i)
 242         print ("stage setup inspecs", self.inspecs)
 243         print ("stage setup outspecs", self.outspecs)
 244         print ("stage setup eqs", self.eqs)
 245         #self.o = self.ospec()
 246         m.d.comb += eq(self.eqs, i)
 247         #m.d.comb += eq(self.outspecs, self.eqs)
 248         #m.d.comb += eq(self.o, i)
 249
 250
 251 class AutoPipe(UnbufferedPipeline):
 252     def __init__(self, stage, assigns):
 253         UnbufferedPipeline.__init__(self, stage)
 254         self.assigns = assigns
 255
 256     def elaborate(self, platform):
 257         m = UnbufferedPipeline.elaborate(self, platform)
 258         m.d.comb += self.assigns
 259         print ("assigns", self.assigns)
 260         return m
 261
 262
 263 class PipeManager:
 264     def __init__(self, m, pipemode=False, pipetype=None):
 265         self.m = m
 266         self.pipemode = pipemode
 267         self.pipetype = pipetype
 268
 269     @contextmanager
 270     def Stage(self, name, prev=None, ispec=None):
 271         print ("start stage", name)
 272         if ispec:
 273             ispec = likelist(ispec)
 274         stage = PipelineStage(name, None, prev, self.pipemode, ispec=ispec)
 275         try:
 276             yield stage, self.m #stage._m
 277         finally:
 278             pass
 279         if self.pipemode:
 280             if stage._ispec:
 281                 print ("use ispec", stage._ispec)
 282                 inspecs = stage._ispec
 283             else:
 284                 inspecs = self.get_specs(stage, name)
 285                 inspecs = likelist(inspecs)
 286             outspecs = self.get_specs(stage, '__nextstage__', liked=True)
 287             eqs = get_eqs(stage._eqs)
 288             assigns = get_assigns(stage._assigns)
 289             print ("stage eqs", name, eqs)
 290             print ("stage assigns", name, assigns)
 291             s = AutoStage(inspecs, outspecs, eqs, assigns)
 292             self.stages.append(s)
 293         print ("end stage", name, self.pipemode, "\n")
 294
 295     def get_specs(self, stage, name, liked=False):
 296         if name in stage._preg_map:
 297             res = []
 298             for k, v in stage._preg_map[name].items():
 299                 #v = like(v, k, stage._m)
 300                 res.append(v)
 301                 #if isinstance(v, ObjectProxy):
 302                 #    res += v.get_specs()
 303             return res
 304         return []
 305
 306     def __enter__(self):
 307         self.stages = []
 308         return self
 309
 310     def __exit__(self, *args):
 311         print ("exit stage", args)
 312         pipes = []
 313         cb = ControlBase()
 314         for s in self.stages:
 315             print ("stage specs", s, s.inspecs, s.outspecs)
 316             if self.pipetype == 'buffered':
 317                 p = BufferedPipeline(s)
 318             else:
 319                 p = AutoPipe(s, s.assigns)
 320             pipes.append(p)
 321             self.m.submodules += p
 322
 323         self.m.d.comb += cb.connect(pipes)
 324
 325
 326 class SimplePipeline:
 327     """ Pipeline builder with auto generation of pipeline registers.
 328     """
 329
 330     def __init__(self, m):
 331         self._m = m
 332         self._pipeline_register_map = {}
 333         self._current_stage_num = 0
 334
 335     def _setup(self):
 336         stage_list = []
 337         for method in dir(self):
 338             if method.startswith('stage'):
 339                 stage_list.append(method)
 340         for stage in sorted(stage_list):
 341             stage_method = getattr(self, stage)
 342             stage_method()
 343             self._current_stage_num += 1
 344
 345     def __getattr__(self, name):
 346         try:
 347             return self._pipeline_register_map[self._current_stage_num][name]
 348         except KeyError:
 349             raise AttributeError(
 350                 'error, no pipeline register "%s" defined for stage %d'
 351                 % (name, self._current_stage_num))
 352
 353     def __setattr__(self, name, value):
 354         if name.startswith('_'):
 355             # do not do anything tricky with variables starting with '_'
 356             object.__setattr__(self, name, value)
 357             return
 358         next_stage = self._current_stage_num + 1
 359         pipereg_id = str(self._current_stage_num) + 'to' + str(next_stage)
 360         rname = 'pipereg_' + pipereg_id + '_' + name
 361         #new_pipereg = Signal(value_bits_sign(value), name=rname,
 362         #                     reset_less=True)
 363         if isinstance(value, ObjectProxy):
 364             new_pipereg = ObjectProxy.like(self._m, value,
 365                                            name=rname, reset_less = True)
 366         else:
 367             new_pipereg = Signal.like(value, name=rname, reset_less = True)
 368         if next_stage not in self._pipeline_register_map:
 369             self._pipeline_register_map[next_stage] = {}
 370         self._pipeline_register_map[next_stage][name] = new_pipereg
 371         self._m.d.sync += eq(new_pipereg, value)
 372