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, to create one giant combinatorial block.
 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
 353         * ... (etc. etc.)
 354         * the output of this class will be the output of the last stage
 355
 356         NOTE: whilst this is very similar to ControlBase.connect(), it is
 357         *really* important to appreciate that StageChain is pure
 358         combinatorial and bypasses (does not involve, at all, ready/valid
 359         signalling of any kind).
 360
 361         ControlBase.connect on the other hand respects, connects, and uses
 362         ready/valid signalling.
 363
 364         Arguments:
 365
 366         * :chain: a chain of combinatorial blocks conforming to the Stage API
 367                   NOTE: StageChain.ispec and ospect have to have something
 368                   to return (beginning and end specs of the chain),
 369                   therefore the chain argument must be non-zero length
 370
 371         * :specallocate: if set, new input and output data will be allocated
 372                          and connected (eq'd) to each chained Stage.
 373                          in some cases if this is not done, the nmigen warning
 374                          "driving from two sources, module is being flattened"
 375                          will be issued.
 376
 377         NOTE: do NOT use StageChain with combinatorial blocks that have
 378         side-effects (state-based / clock-based input) or conditional
 379         (inter-chain) dependencies, unless you really know what you are doing.
 380     """
 381     def __init__(self, chain, specallocate=False):
 382         assert len(chain) > 0, "stage chain must be non-zero length"
 383         self.chain = chain
 384         self.specallocate = specallocate
 385
 386     def ispec(self):
 387         """ returns the ispec of the first of the chain
 388         """
 389         return _spec(self.chain[0].ispec, "chainin")
 390
 391     def ospec(self):
 392         """ returns the ospec of the last of the chain
 393         """
 394         return _spec(self.chain[-1].ospec, "chainout")
 395
 396     def _specallocate_setup(self, m, i):
 397         o = i # in case chain is empty
 398         for (idx, c) in enumerate(self.chain):
 399             if hasattr(c, "setup"):
 400                 c.setup(m, i)               # stage may have some module stuff
 401             ofn = self.chain[idx].ospec     # last assignment survives
 402             o = _spec(ofn, 'chainin%d' % idx)
 403             m.d.comb += nmoperator.eq(o, c.process(i)) # process input into "o"
 404             if idx == len(self.chain)-1:
 405                 break
 406             ifn = self.chain[idx+1].ispec   # new input on next loop
 407             i = _spec(ifn, 'chainin%d' % (idx+1))
 408             m.d.comb += nmoperator.eq(i, o) # assign to next input
 409         return o                            # last loop is the output
 410
 411     def _noallocate_setup(self, m, i):
 412         o = i # in case chain is empty
 413         for (idx, c) in enumerate(self.chain):
 414             if hasattr(c, "setup"):
 415                 c.setup(m, i)               # stage may have some module stuff
 416             i = o = c.process(i)            # store input into "o"
 417         return o                            # last loop is the output
 418
 419     def setup(self, m, i):
 420         if self.specallocate:
 421             self.o = self._specallocate_setup(m, i)
 422         else:
 423             self.o = self._noallocate_setup(m, i)
 424
 425     def process(self, i):
 426         return self.o # conform to Stage API: return last-loop output
 427
 428
 429 class ControlBase(Elaboratable):
 430     """ Common functions for Pipeline API.  Note: a "pipeline stage" only
 431         exists (conceptually) when a ControlBase derivative is handed
 432         a Stage (combinatorial block)
 433     """
 434     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
 435         """ Base class containing ready/valid/data to previous and next stages
 436
 437             * p: contains ready/valid to the previous stage
 438             * n: contains ready/valid to the next stage
 439
 440             Except when calling Controlbase.connect(), user must also:
 441             * add data_i member to PrevControl (p) and
 442             * add data_o member to NextControl (n)
 443         """
 444         self.stage = stage
 445
 446         # set up input and output IO ACK (prev/next ready/valid)
 447         self.p = PrevControl(in_multi, stage_ctl)
 448         self.n = NextControl(stage_ctl)
 449
 450         # set up the input and output data
 451         if stage is not None:
 452             self.p.data_i = _spec(stage.ispec, "data_i") # input type
 453             self.n.data_o = _spec(stage.ospec, "data_o") # output type
 454
 455     def connect_to_next(self, nxt):
 456         """ helper function to connect to the next stage data/valid/ready.
 457         """
 458         return self.n.connect_to_next(nxt.p)
 459
 460     def _connect_in(self, prev):
 461         """ internal helper function to connect stage to an input source.
 462             do not use to connect stage-to-stage!
 463         """
 464         return self.p._connect_in(prev.p)
 465
 466     def _connect_out(self, nxt):
 467         """ internal helper function to connect stage to an output source.
 468             do not use to connect stage-to-stage!
 469         """
 470         return self.n._connect_out(nxt.n)
 471
 472     def connect(self, pipechain):
 473         """ connects a chain (list) of Pipeline instances together and
 474             links them to this ControlBase instance:
 475
 476                       in <----> self <---> out
 477                        |                   ^
 478                        v                   |
 479                     [pipe1, pipe2, pipe3, pipe4]
 480                        |    ^  |    ^  |     ^
 481                        v    |  v    |  v     |
 482                      out---in out--in out---in
 483
 484             Also takes care of allocating data_i/data_o, by looking up
 485             the data spec for each end of the pipechain.  i.e It is NOT
 486             necessary to allocate self.p.data_i or self.n.data_o manually:
 487             this is handled AUTOMATICALLY, here.
 488
 489             Basically this function is the direct equivalent of StageChain,
 490             except that unlike StageChain, the Pipeline logic is followed.
 491
 492             Just as StageChain presents an object that conforms to the
 493             Stage API from a list of objects that also conform to the
 494             Stage API, an object that calls this Pipeline connect function
 495             has the exact same pipeline API as the list of pipline objects
 496             it is called with.
 497
 498             Thus it becomes possible to build up larger chains recursively.
 499             More complex chains (multi-input, multi-output) will have to be
 500             done manually.
 501
 502             Argument:
 503
 504             * :pipechain: - a sequence of ControlBase-derived classes
 505                             (must be one or more in length)
 506
 507             Returns:
 508
 509             * a list of eq assignments that will need to be added in
 510               an elaborate() to m.d.comb
 511         """
 512         assert len(pipechain) > 0, "pipechain must be non-zero length"
 513         eqs = [] # collated list of assignment statements
 514
 515         # connect inter-chain
 516         for i in range(len(pipechain)-1):
 517             pipe1 = pipechain[i]
 518             pipe2 = pipechain[i+1]
 519             eqs += pipe1.connect_to_next(pipe2)
 520
 521         # connect front of chain to ourselves
 522         front = pipechain[0]
 523         self.p.data_i = _spec(front.stage.ispec, "chainin")
 524         eqs += front._connect_in(self)
 525
 526         # connect end of chain to ourselves
 527         end = pipechain[-1]
 528         self.n.data_o = _spec(end.stage.ospec, "chainout")
 529         eqs += end._connect_out(self)
 530
 531         return eqs
 532
 533     def _postprocess(self, i): # XXX DISABLED
 534         return i # RETURNS INPUT
 535         if hasattr(self.stage, "postprocess"):
 536             return self.stage.postprocess(i)
 537         return i
 538
 539     def set_input(self, i):
 540         """ helper function to set the input data
 541         """
 542         return nmoperator.eq(self.p.data_i, i)
 543
 544     def __iter__(self):
 545         yield from self.p
 546         yield from self.n
 547
 548     def ports(self):
 549         return list(self)
 550
 551     def elaborate(self, platform):
 552         """ handles case where stage has dynamic ready/valid functions
 553         """
 554         m = Module()
 555         m.submodules.p = self.p
 556         m.submodules.n = self.n
 557
 558         if self.stage is not None and hasattr(self.stage, "setup"):
 559             self.stage.setup(m, self.p.data_i)
 560
 561         if not self.p.stage_ctl:
 562             return m
 563
 564         # intercept the previous (outgoing) "ready", combine with stage ready
 565         m.d.comb += self.p.s_ready_o.eq(self.p._ready_o & self.stage.d_ready)
 566
 567         # intercept the next (incoming) "ready" and combine it with data valid
 568         sdv = self.stage.d_valid(self.n.ready_i)
 569         m.d.comb += self.n.d_valid.eq(self.n.ready_i & sdv)
 570
 571         return m
 572