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