src/add/iocontrol.py

   1 """ IO Control API
   2
   3     Associated development bugs:
   4     * http://bugs.libre-riscv.org/show_bug.cgi?id=64
   5     * http://bugs.libre-riscv.org/show_bug.cgi?id=57
   6
   7     Stage API:
   8     ---------
   9
  10     stage requires compliance with a strict API that may be
  11     implemented in several means, including as a static class.
  12     the methods of a stage instance must be as follows:
  13
  14     * ispec() - Input data format specification
  15                 returns an object or a list or tuple of objects, or
  16                 a Record, each object having an "eq" function which
  17                 takes responsibility for copying by assignment all
  18                 sub-objects
  19     * ospec() - Output data format specification
  20                 requirements as for ospec
  21     * process(m, i) - Processes an ispec-formatted object
  22                 returns a combinatorial block of a result that
  23                 may be assigned to the output, by way of the "eq"
  24                 function
  25     * setup(m, i) - Optional function for setting up submodules
  26                 may be used for more complex stages, to link
  27                 the input (i) to submodules.  must take responsibility
  28                 for adding those submodules to the module (m).
  29                 the submodules must be combinatorial blocks and
  30                 must have their inputs and output linked combinatorially.
  31
  32     Both StageCls (for use with non-static classes) and Stage (for use
  33     by static classes) are abstract classes from which, for convenience
  34     and as a courtesy to other developers, anything conforming to the
  35     Stage API may *choose* to derive.
  36
  37     StageChain:
  38     ----------
  39
  40     A useful combinatorial wrapper around stages that chains them together
  41     and then presents a Stage-API-conformant interface.  By presenting
  42     the same API as the stages it wraps, it can clearly be used recursively.
  43
  44     ControlBase:
  45     -----------
  46
  47     The base class for pipelines.  Contains previous and next ready/valid/data.
  48     Also has an extremely useful "connect" function that can be used to
  49     connect a chain of pipelines and present the exact same prev/next
  50     ready/valid/data API.
  51 """
  52
  53 from nmigen import Signal, Cat, Const, Mux, Module, Value, Elaboratable
  54 from nmigen.cli import verilog, rtlil
  55 from nmigen.hdl.rec import Record
  56
  57 from abc import ABCMeta, abstractmethod
  58 from collections.abc import Sequence, Iterable
  59 from collections import OrderedDict
  60 import inspect
  61
  62 from nmoperator import eq, cat, shape
  63
  64
  65 class Object:
  66     def __init__(self):
  67         self.fields = OrderedDict()
  68
  69     def __setattr__(self, k, v):
  70         print ("kv", k, v)
  71         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
  72            k in dir(Object) or "fields" not in self.__dict__):
  73             return object.__setattr__(self, k, v)
  74         self.fields[k] = v
  75
  76     def __getattr__(self, k):
  77         if k in self.__dict__:
  78             return object.__getattr__(self, k)
  79         try:
  80             return self.fields[k]
  81         except KeyError as e:
  82             raise AttributeError(e)
  83
  84     def __iter__(self):
  85         for x in self.fields.values():
  86             if isinstance(x, Iterable):
  87                 yield from x
  88             else:
  89                 yield x
  90
  91     def eq(self, inp):
  92         res = []
  93         for (k, o) in self.fields.items():
  94             i = getattr(inp, k)
  95             print ("eq", o, i)
  96             rres = o.eq(i)
  97             if isinstance(rres, Sequence):
  98                 res += rres
  99             else:
 100                 res.append(rres)
 101         print (res)
 102         return res
 103
 104     def ports(self):
 105         return list(self)
 106
 107
 108 class RecordObject(Record):
 109     def __init__(self, layout=None, name=None):
 110         Record.__init__(self, layout=layout or [], name=None)
 111
 112     def __setattr__(self, k, v):
 113         #print (dir(Record))
 114         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
 115            k in dir(Record) or "fields" not in self.__dict__):
 116             return object.__setattr__(self, k, v)
 117         self.fields[k] = v
 118         #print ("RecordObject setattr", k, v)
 119         if isinstance(v, Record):
 120             newlayout = {k: (k, v.layout)}
 121         elif isinstance(v, Value):
 122             newlayout = {k: (k, v.shape())}
 123         else:
 124             newlayout = {k: (k, shape(v))}
 125         self.layout.fields.update(newlayout)
 126
 127     def __iter__(self):
 128         for x in self.fields.values():
 129             if isinstance(x, Iterable):
 130                 yield from x
 131             else:
 132                 yield x
 133
 134     def ports(self):
 135         return list(self)
 136
 137
 138 def _spec(fn, name=None):
 139     if name is None:
 140         return fn()
 141     varnames = dict(inspect.getmembers(fn.__code__))['co_varnames']
 142     if 'name' in varnames:
 143         return fn(name=name)
 144     return fn()
 145
 146
 147 class PrevControl(Elaboratable):
 148     """ contains signals that come *from* the previous stage (both in and out)
 149         * valid_i: previous stage indicating all incoming data is valid.
 150                    may be a multi-bit signal, where all bits are required
 151                    to be asserted to indicate "valid".
 152         * ready_o: output to next stage indicating readiness to accept data
 153         * data_i : an input - added by the user of this class
 154     """
 155
 156     def __init__(self, i_width=1, stage_ctl=False):
 157         self.stage_ctl = stage_ctl
 158         self.valid_i = Signal(i_width, name="p_valid_i") # prev   >>in  self
 159         self._ready_o = Signal(name="p_ready_o") # prev   <<out self
 160         self.data_i = None # XXX MUST BE ADDED BY USER
 161         if stage_ctl:
 162             self.s_ready_o = Signal(name="p_s_o_rdy") # prev   <<out self
 163         self.trigger = Signal(reset_less=True)
 164
 165     @property
 166     def ready_o(self):
 167         """ public-facing API: indicates (externally) that stage is ready
 168         """
 169         if self.stage_ctl:
 170             return self.s_ready_o # set dynamically by stage
 171         return self._ready_o      # return this when not under dynamic control
 172
 173     def _connect_in(self, prev, direct=False, fn=None):
 174         """ internal helper function to connect stage to an input source.
 175             do not use to connect stage-to-stage!
 176         """
 177         valid_i = prev.valid_i if direct else prev.valid_i_test
 178         data_i = fn(prev.data_i) if fn is not None else prev.data_i
 179         return [self.valid_i.eq(valid_i),
 180                 prev.ready_o.eq(self.ready_o),
 181                 eq(self.data_i, data_i),
 182                ]
 183
 184     @property
 185     def valid_i_test(self):
 186         vlen = len(self.valid_i)
 187         if vlen > 1:
 188             # multi-bit case: valid only when valid_i is all 1s
 189             all1s = Const(-1, (len(self.valid_i), False))
 190             valid_i = (self.valid_i == all1s)
 191         else:
 192             # single-bit valid_i case
 193             valid_i = self.valid_i
 194
 195         # when stage indicates not ready, incoming data
 196         # must "appear" to be not ready too
 197         if self.stage_ctl:
 198             valid_i = valid_i & self.s_ready_o
 199
 200         return valid_i
 201
 202     def elaborate(self, platform):
 203         m = Module()
 204         m.d.comb += self.trigger.eq(self.valid_i_test & self.ready_o)
 205         return m
 206
 207     def eq(self, i):
 208         return [self.data_i.eq(i.data_i),
 209                 self.ready_o.eq(i.ready_o),
 210                 self.valid_i.eq(i.valid_i)]
 211
 212     def __iter__(self):
 213         yield self.valid_i
 214         yield self.ready_o
 215         if hasattr(self.data_i, "ports"):
 216             yield from self.data_i.ports()
 217         elif isinstance(self.data_i, Sequence):
 218             yield from self.data_i
 219         else:
 220             yield self.data_i
 221
 222     def ports(self):
 223         return list(self)
 224
 225
 226 class NextControl(Elaboratable):
 227     """ contains the signals that go *to* the next stage (both in and out)
 228         * valid_o: output indicating to next stage that data is valid
 229         * ready_i: input from next stage indicating that it can accept data
 230         * data_o : an output - added by the user of this class
 231     """
 232     def __init__(self, stage_ctl=False):
 233         self.stage_ctl = stage_ctl
 234         self.valid_o = Signal(name="n_valid_o") # self out>>  next
 235         self.ready_i = Signal(name="n_ready_i") # self <<in   next
 236         self.data_o = None # XXX MUST BE ADDED BY USER
 237         #if self.stage_ctl:
 238         self.d_valid = Signal(reset=1) # INTERNAL (data valid)
 239         self.trigger = Signal(reset_less=True)
 240
 241     @property
 242     def ready_i_test(self):
 243         if self.stage_ctl:
 244             return self.ready_i & self.d_valid
 245         return self.ready_i
 246
 247     def connect_to_next(self, nxt):
 248         """ helper function to connect to the next stage data/valid/ready.
 249             data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
 250             use this when connecting stage-to-stage
 251         """
 252         return [nxt.valid_i.eq(self.valid_o),
 253                 self.ready_i.eq(nxt.ready_o),
 254                 eq(nxt.data_i, self.data_o),
 255                ]
 256
 257     def _connect_out(self, nxt, direct=False, fn=None):
 258         """ internal helper function to connect stage to an output source.
 259             do not use to connect stage-to-stage!
 260         """
 261         ready_i = nxt.ready_i if direct else nxt.ready_i_test
 262         data_o = fn(nxt.data_o) if fn is not None else nxt.data_o
 263         return [nxt.valid_o.eq(self.valid_o),
 264                 self.ready_i.eq(ready_i),
 265                 eq(data_o, self.data_o),
 266                ]
 267
 268     def elaborate(self, platform):
 269         m = Module()
 270         m.d.comb += self.trigger.eq(self.ready_i_test & self.valid_o)
 271         return m
 272
 273     def __iter__(self):
 274         yield self.ready_i
 275         yield self.valid_o
 276         if hasattr(self.data_o, "ports"):
 277             yield from self.data_o.ports()
 278         elif isinstance(self.data_o, Sequence):
 279             yield from self.data_o
 280         else:
 281             yield self.data_o
 282
 283     def ports(self):
 284         return list(self)
 285
 286
 287 class StageCls(metaclass=ABCMeta):
 288     """ Class-based "Stage" API.  requires instantiation (after derivation)
 289
 290         see "Stage API" above..  Note: python does *not* require derivation
 291         from this class.  All that is required is that the pipelines *have*
 292         the functions listed in this class.  Derivation from this class
 293         is therefore merely a "courtesy" to maintainers.
 294     """
 295     @abstractmethod
 296     def ispec(self): pass       # REQUIRED
 297     @abstractmethod
 298     def ospec(self): pass       # REQUIRED
 299     #@abstractmethod
 300     #def setup(self, m, i): pass # OPTIONAL
 301     @abstractmethod
 302     def process(self, i): pass  # REQUIRED
 303
 304
 305 class Stage(metaclass=ABCMeta):
 306     """ Static "Stage" API.  does not require instantiation (after derivation)
 307
 308         see "Stage API" above.  Note: python does *not* require derivation
 309         from this class.  All that is required is that the pipelines *have*
 310         the functions listed in this class.  Derivation from this class
 311         is therefore merely a "courtesy" to maintainers.
 312     """
 313     @staticmethod
 314     @abstractmethod
 315     def ispec(): pass
 316
 317     @staticmethod
 318     @abstractmethod
 319     def ospec(): pass
 320
 321     #@staticmethod
 322     #@abstractmethod
 323     #def setup(m, i): pass
 324
 325     @staticmethod
 326     @abstractmethod
 327     def process(i): pass
 328
 329
 330 class StageChain(StageCls):
 331     """ pass in a list of stages, and they will automatically be
 332         chained together via their input and output specs into a
 333         combinatorial chain.
 334
 335         the end result basically conforms to the exact same Stage API.
 336
 337         * input to this class will be the input of the first stage
 338         * output of first stage goes into input of second
 339         * output of second goes into input into third (etc. etc.)
 340         * the output of this class will be the output of the last stage
 341     """
 342     def __init__(self, chain, specallocate=False):
 343         self.chain = chain
 344         self.specallocate = specallocate
 345
 346     def ispec(self):
 347         return _spec(self.chain[0].ispec, "chainin")
 348
 349     def ospec(self):
 350         return _spec(self.chain[-1].ospec, "chainout")
 351
 352     def _specallocate_setup(self, m, i):
 353         for (idx, c) in enumerate(self.chain):
 354             if hasattr(c, "setup"):
 355                 c.setup(m, i)               # stage may have some module stuff
 356             ofn = self.chain[idx].ospec     # last assignment survives
 357             o = _spec(ofn, 'chainin%d' % idx)
 358             m.d.comb += eq(o, c.process(i)) # process input into "o"
 359             if idx == len(self.chain)-1:
 360                 break
 361             ifn = self.chain[idx+1].ispec   # new input on next loop
 362             i = _spec(ifn, 'chainin%d' % (idx+1))
 363             m.d.comb += eq(i, o)            # assign to next input
 364         return o                            # last loop is the output
 365
 366     def _noallocate_setup(self, m, i):
 367         for (idx, c) in enumerate(self.chain):
 368             if hasattr(c, "setup"):
 369                 c.setup(m, i)               # stage may have some module stuff
 370             i = o = c.process(i)            # store input into "o"
 371         return o                            # last loop is the output
 372
 373     def setup(self, m, i):
 374         if self.specallocate:
 375             self.o = self._specallocate_setup(m, i)
 376         else:
 377             self.o = self._noallocate_setup(m, i)
 378
 379     def process(self, i):
 380         return self.o # conform to Stage API: return last-loop output
 381
 382
 383 class ControlBase(Elaboratable):
 384     """ Common functions for Pipeline API
 385     """
 386     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
 387         """ Base class containing ready/valid/data to previous and next stages
 388
 389             * p: contains ready/valid to the previous stage
 390             * n: contains ready/valid to the next stage
 391
 392             Except when calling Controlbase.connect(), user must also:
 393             * add data_i member to PrevControl (p) and
 394             * add data_o member to NextControl (n)
 395         """
 396         self.stage = stage
 397
 398         # set up input and output IO ACK (prev/next ready/valid)
 399         self.p = PrevControl(in_multi, stage_ctl)
 400         self.n = NextControl(stage_ctl)
 401
 402         # set up the input and output data
 403         if stage is not None:
 404             self.p.data_i = _spec(stage.ispec, "data_i") # input type
 405             self.n.data_o = _spec(stage.ospec, "data_o") # output type
 406
 407     def connect_to_next(self, nxt):
 408         """ helper function to connect to the next stage data/valid/ready.
 409         """
 410         return self.n.connect_to_next(nxt.p)
 411
 412     def _connect_in(self, prev):
 413         """ internal helper function to connect stage to an input source.
 414             do not use to connect stage-to-stage!
 415         """
 416         return self.p._connect_in(prev.p)
 417
 418     def _connect_out(self, nxt):
 419         """ internal helper function to connect stage to an output source.
 420             do not use to connect stage-to-stage!
 421         """
 422         return self.n._connect_out(nxt.n)
 423
 424     def connect(self, pipechain):
 425         """ connects a chain (list) of Pipeline instances together and
 426             links them to this ControlBase instance:
 427
 428                       in <----> self <---> out
 429                        |                   ^
 430                        v                   |
 431                     [pipe1, pipe2, pipe3, pipe4]
 432                        |    ^  |    ^  |     ^
 433                        v    |  v    |  v     |
 434                      out---in out--in out---in
 435
 436             Also takes care of allocating data_i/data_o, by looking up
 437             the data spec for each end of the pipechain.  i.e It is NOT
 438             necessary to allocate self.p.data_i or self.n.data_o manually:
 439             this is handled AUTOMATICALLY, here.
 440
 441             Basically this function is the direct equivalent of StageChain,
 442             except that unlike StageChain, the Pipeline logic is followed.
 443
 444             Just as StageChain presents an object that conforms to the
 445             Stage API from a list of objects that also conform to the
 446             Stage API, an object that calls this Pipeline connect function
 447             has the exact same pipeline API as the list of pipline objects
 448             it is called with.
 449
 450             Thus it becomes possible to build up larger chains recursively.
 451             More complex chains (multi-input, multi-output) will have to be
 452             done manually.
 453         """
 454         eqs = [] # collated list of assignment statements
 455
 456         # connect inter-chain
 457         for i in range(len(pipechain)-1):
 458             pipe1 = pipechain[i]
 459             pipe2 = pipechain[i+1]
 460             eqs += pipe1.connect_to_next(pipe2)
 461
 462         # connect front of chain to ourselves
 463         front = pipechain[0]
 464         self.p.data_i = _spec(front.stage.ispec, "chainin")
 465         eqs += front._connect_in(self)
 466
 467         # connect end of chain to ourselves
 468         end = pipechain[-1]
 469         self.n.data_o = _spec(end.stage.ospec, "chainout")
 470         eqs += end._connect_out(self)
 471
 472         return eqs
 473
 474     def _postprocess(self, i): # XXX DISABLED
 475         return i # RETURNS INPUT
 476         if hasattr(self.stage, "postprocess"):
 477             return self.stage.postprocess(i)
 478         return i
 479
 480     def set_input(self, i):
 481         """ helper function to set the input data
 482         """
 483         return eq(self.p.data_i, i)
 484
 485     def __iter__(self):
 486         yield from self.p
 487         yield from self.n
 488
 489     def ports(self):
 490         return list(self)
 491
 492     def elaborate(self, platform):
 493         """ handles case where stage has dynamic ready/valid functions
 494         """
 495         m = Module()
 496         m.submodules.p = self.p
 497         m.submodules.n = self.n
 498
 499         if self.stage is not None and hasattr(self.stage, "setup"):
 500             self.stage.setup(m, self.p.data_i)
 501
 502         if not self.p.stage_ctl:
 503             return m
 504
 505         # intercept the previous (outgoing) "ready", combine with stage ready
 506         m.d.comb += self.p.s_ready_o.eq(self.p._ready_o & self.stage.d_ready)
 507
 508         # intercept the next (incoming) "ready" and combine it with data valid
 509         sdv = self.stage.d_valid(self.n.ready_i)
 510         m.d.comb += self.n.d_valid.eq(self.n.ready_i & sdv)
 511
 512         return m
 513
 514