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