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