src/add/singlepipe.py

   1 """ Pipeline API.  For multi-input and multi-output variants, see multipipe.
   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     Important: see Stage API (stageapi.py) in combination with below
   8
   9     RecordBasedStage:
  10     ----------------
  11
  12     A convenience class that takes an input shape, output shape, a
  13     "processing" function and an optional "setup" function.  Honestly
  14     though, there's not much more effort to just... create a class
  15     that returns a couple of Records (see ExampleAddRecordStage in
  16     examples).
  17
  18     PassThroughStage:
  19     ----------------
  20
  21     A convenience class that takes a single function as a parameter,
  22     that is chain-called to create the exact same input and output spec.
  23     It has a process() function that simply returns its input.
  24
  25     Instances of this class are completely redundant if handed to
  26     StageChain, however when passed to UnbufferedPipeline they
  27     can be used to introduce a single clock delay.
  28
  29     ControlBase:
  30     -----------
  31
  32     The base class for pipelines.  Contains previous and next ready/valid/data.
  33     Also has an extremely useful "connect" function that can be used to
  34     connect a chain of pipelines and present the exact same prev/next
  35     ready/valid/data API.
  36
  37     Note: pipelines basically do not become pipelines as such until
  38     handed to a derivative of ControlBase.  ControlBase itself is *not*
  39     strictly considered a pipeline class.  Wishbone and AXI4 (master or
  40     slave) could be derived from ControlBase, for example.
  41     UnbufferedPipeline:
  42     ------------------
  43
  44     A simple stalling clock-synchronised pipeline that has no buffering
  45     (unlike BufferedHandshake).  Data flows on *every* clock cycle when
  46     the conditions are right (this is nominally when the input is valid
  47     and the output is ready).
  48
  49     A stall anywhere along the line will result in a stall back-propagating
  50     down the entire chain.  The BufferedHandshake by contrast will buffer
  51     incoming data, allowing previous stages one clock cycle's grace before
  52     also having to stall.
  53
  54     An advantage of the UnbufferedPipeline over the Buffered one is
  55     that the amount of logic needed (number of gates) is greatly
  56     reduced (no second set of buffers basically)
  57
  58     The disadvantage of the UnbufferedPipeline is that the valid/ready
  59     logic, if chained together, is *combinatorial*, resulting in
  60     progressively larger gate delay.
  61
  62     PassThroughHandshake:
  63     ------------------
  64
  65     A Control class that introduces a single clock delay, passing its
  66     data through unaltered.  Unlike RegisterPipeline (which relies
  67     on UnbufferedPipeline and PassThroughStage) it handles ready/valid
  68     itself.
  69
  70     RegisterPipeline:
  71     ----------------
  72
  73     A convenience class that, because UnbufferedPipeline introduces a single
  74     clock delay, when its stage is a PassThroughStage, it results in a Pipeline
  75     stage that, duh, delays its (unmodified) input by one clock cycle.
  76
  77     BufferedHandshake:
  78     ----------------
  79
  80     nmigen implementation of buffered pipeline stage, based on zipcpu:
  81     https://zipcpu.com/blog/2017/08/14/strategies-for-pipelining.html
  82
  83     this module requires quite a bit of thought to understand how it works
  84     (and why it is needed in the first place).  reading the above is
  85     *strongly* recommended.
  86
  87     unlike john dawson's IEEE754 FPU STB/ACK signalling, which requires
  88     the STB / ACK signals to raise and lower (on separate clocks) before
  89     data may proceeed (thus only allowing one piece of data to proceed
  90     on *ALTERNATE* cycles), the signalling here is a true pipeline
  91     where data will flow on *every* clock when the conditions are right.
  92
  93     input acceptance conditions are when:
  94         * incoming previous-stage strobe (p.valid_i) is HIGH
  95         * outgoing previous-stage ready   (p.ready_o) is LOW
  96
  97     output transmission conditions are when:
  98         * outgoing next-stage strobe (n.valid_o) is HIGH
  99         * outgoing next-stage ready   (n.ready_i) is LOW
 100
 101     the tricky bit is when the input has valid data and the output is not
 102     ready to accept it.  if it wasn't for the clock synchronisation, it
 103     would be possible to tell the input "hey don't send that data, we're
 104     not ready".  unfortunately, it's not possible to "change the past":
 105     the previous stage *has no choice* but to pass on its data.
 106
 107     therefore, the incoming data *must* be accepted - and stored: that
 108     is the responsibility / contract that this stage *must* accept.
 109     on the same clock, it's possible to tell the input that it must
 110     not send any more data.  this is the "stall" condition.
 111
 112     we now effectively have *two* possible pieces of data to "choose" from:
 113     the buffered data, and the incoming data.  the decision as to which
 114     to process and output is based on whether we are in "stall" or not.
 115     i.e. when the next stage is no longer ready, the output comes from
 116     the buffer if a stall had previously occurred, otherwise it comes
 117     direct from processing the input.
 118
 119     this allows us to respect a synchronous "travelling STB" with what
 120     dan calls a "buffered handshake".
 121
 122     it's quite a complex state machine!
 123
 124     SimpleHandshake
 125     ---------------
 126
 127     Synchronised pipeline, Based on:
 128     https://github.com/ZipCPU/dbgbus/blob/master/hexbus/rtl/hbdeword.v
 129 """
 130
 131 from nmigen import Signal, Mux, Module, Elaboratable
 132 from nmigen.cli import verilog, rtlil
 133 from nmigen.lib.fifo import SyncFIFOBuffered
 134 from nmigen.hdl.rec import Record
 135
 136 from queue import Queue
 137 import inspect
 138
 139 from iocontrol import (PrevControl, NextControl, Object, RecordObject)
 140 from stageapi import (_spec, StageCls, Stage, StageChain, StageHelper)
 141 import nmoperator
 142
 143
 144 class RecordBasedStage(Stage):
 145     """ convenience class which provides a Records-based layout.
 146         honestly it's a lot easier just to create a direct Records-based
 147         class (see ExampleAddRecordStage)
 148     """
 149     def __init__(self, in_shape, out_shape, processfn, setupfn=None):
 150         self.in_shape = in_shape
 151         self.out_shape = out_shape
 152         self.__process = processfn
 153         self.__setup = setupfn
 154     def ispec(self): return Record(self.in_shape)
 155     def ospec(self): return Record(self.out_shape)
 156     def process(seif, i): return self.__process(i)
 157     def setup(seif, m, i): return self.__setup(m, i)
 158
 159
 160 class PassThroughStage(StageCls):
 161     """ a pass-through stage with its input data spec identical to its output,
 162         and "passes through" its data from input to output (does nothing).
 163
 164         use this basically to explicitly make any data spec Stage-compliant.
 165         (many APIs would potentially use a static "wrap" method in e.g.
 166          StageCls to achieve a similar effect)
 167     """
 168     def __init__(self, iospecfn): self.iospecfn = iospecfn
 169     def ispec(self): return self.iospecfn()
 170     def ospec(self): return self.iospecfn()
 171
 172
 173 class ControlBase(StageHelper, Elaboratable):
 174     """ Common functions for Pipeline API.  Note: a "pipeline stage" only
 175         exists (conceptually) when a ControlBase derivative is handed
 176         a Stage (combinatorial block)
 177
 178         NOTE: ControlBase derives from StageHelper, making it accidentally
 179         compliant with the Stage API.  Using those functions directly
 180         *BYPASSES* a ControlBase instance ready/valid signalling, which
 181         clearly should not be done without a really, really good reason.
 182     """
 183     def __init__(self, stage=None, in_multi=None, stage_ctl=False):
 184         """ Base class containing ready/valid/data to previous and next stages
 185
 186             * p: contains ready/valid to the previous stage
 187             * n: contains ready/valid to the next stage
 188
 189             Except when calling Controlbase.connect(), user must also:
 190             * add data_i member to PrevControl (p) and
 191             * add data_o member to NextControl (n)
 192             Calling ControlBase._new_data is a good way to do that.
 193         """
 194         StageHelper.__init__(self, stage)
 195
 196         # set up input and output IO ACK (prev/next ready/valid)
 197         self.p = PrevControl(in_multi, stage_ctl)
 198         self.n = NextControl(stage_ctl)
 199
 200         # set up the input and output data
 201         if stage is not None:
 202             self._new_data(self, self, "data")
 203
 204     def _new_data(self, p, n, name):
 205         """ allocates new data_i and data_o
 206         """
 207         self.p.data_i = _spec(p.stage.ispec, "%s_i" % name)
 208         self.n.data_o = _spec(n.stage.ospec, "%s_o" % name)
 209
 210     @property
 211     def data_r(self):
 212         return self.process(self.p.data_i)
 213
 214     def connect_to_next(self, nxt):
 215         """ helper function to connect to the next stage data/valid/ready.
 216         """
 217         return self.n.connect_to_next(nxt.p)
 218
 219     def _connect_in(self, prev):
 220         """ internal helper function to connect stage to an input source.
 221             do not use to connect stage-to-stage!
 222         """
 223         return self.p._connect_in(prev.p)
 224
 225     def _connect_out(self, nxt):
 226         """ internal helper function to connect stage to an output source.
 227             do not use to connect stage-to-stage!
 228         """
 229         return self.n._connect_out(nxt.n)
 230
 231     def connect(self, pipechain):
 232         """ connects a chain (list) of Pipeline instances together and
 233             links them to this ControlBase instance:
 234
 235                       in <----> self <---> out
 236                        |                   ^
 237                        v                   |
 238                     [pipe1, pipe2, pipe3, pipe4]
 239                        |    ^  |    ^  |     ^
 240                        v    |  v    |  v     |
 241                      out---in out--in out---in
 242
 243             Also takes care of allocating data_i/data_o, by looking up
 244             the data spec for each end of the pipechain.  i.e It is NOT
 245             necessary to allocate self.p.data_i or self.n.data_o manually:
 246             this is handled AUTOMATICALLY, here.
 247
 248             Basically this function is the direct equivalent of StageChain,
 249             except that unlike StageChain, the Pipeline logic is followed.
 250
 251             Just as StageChain presents an object that conforms to the
 252             Stage API from a list of objects that also conform to the
 253             Stage API, an object that calls this Pipeline connect function
 254             has the exact same pipeline API as the list of pipline objects
 255             it is called with.
 256
 257             Thus it becomes possible to build up larger chains recursively.
 258             More complex chains (multi-input, multi-output) will have to be
 259             done manually.
 260
 261             Argument:
 262
 263             * :pipechain: - a sequence of ControlBase-derived classes
 264                             (must be one or more in length)
 265
 266             Returns:
 267
 268             * a list of eq assignments that will need to be added in
 269               an elaborate() to m.d.comb
 270         """
 271         assert len(pipechain) > 0, "pipechain must be non-zero length"
 272         assert self.stage is None, "do not use connect with a stage"
 273         eqs = [] # collated list of assignment statements
 274
 275         # connect inter-chain
 276         for i in range(len(pipechain)-1):
 277             pipe1 = pipechain[i]                # earlier
 278             pipe2 = pipechain[i+1]              # later (by 1)
 279             eqs += pipe1.connect_to_next(pipe2) # earlier n to later p
 280
 281         # connect front and back of chain to ourselves
 282         front = pipechain[0]                # first in chain
 283         end = pipechain[-1]                 # last in chain
 284         self._new_data(front, end, "chain") # NOTE: REPLACES existing data
 285         eqs += front._connect_in(self)      # front p to our p
 286         eqs += end._connect_out(self)       # end n   to out n
 287
 288         return eqs
 289
 290     def set_input(self, i):
 291         """ helper function to set the input data (used in unit tests)
 292         """
 293         return nmoperator.eq(self.p.data_i, i)
 294
 295     def __iter__(self):
 296         yield from self.p # yields ready/valid/data (data also gets yielded)
 297         yield from self.n # ditto
 298
 299     def ports(self):
 300         return list(self)
 301
 302     def elaborate(self, platform):
 303         """ handles case where stage has dynamic ready/valid functions
 304         """
 305         m = Module()
 306         m.submodules.p = self.p
 307         m.submodules.n = self.n
 308
 309         self.setup(m, self.p.data_i)
 310
 311         if not self.p.stage_ctl:
 312             return m
 313
 314         # intercept the previous (outgoing) "ready", combine with stage ready
 315         m.d.comb += self.p.s_ready_o.eq(self.p._ready_o & self.stage.d_ready)
 316
 317         # intercept the next (incoming) "ready" and combine it with data valid
 318         sdv = self.stage.d_valid(self.n.ready_i)
 319         m.d.comb += self.n.d_valid.eq(self.n.ready_i & sdv)
 320
 321         return m
 322
 323
 324 class BufferedHandshake(ControlBase):
 325     """ buffered pipeline stage.  data and strobe signals travel in sync.
 326         if ever the input is ready and the output is not, processed data
 327         is shunted in a temporary register.
 328
 329         Argument: stage.  see Stage API above
 330
 331         stage-1   p.valid_i >>in   stage   n.valid_o out>>   stage+1
 332         stage-1   p.ready_o <<out  stage   n.ready_i <<in    stage+1
 333         stage-1   p.data_i  >>in   stage   n.data_o  out>>   stage+1
 334                               |             |
 335                             process --->----^
 336                               |             |
 337                               +-- r_data ->-+
 338
 339         input data p.data_i is read (only), is processed and goes into an
 340         intermediate result store [process()].  this is updated combinatorially.
 341
 342         in a non-stall condition, the intermediate result will go into the
 343         output (update_output).  however if ever there is a stall, it goes
 344         into r_data instead [update_buffer()].
 345
 346         when the non-stall condition is released, r_data is the first
 347         to be transferred to the output [flush_buffer()], and the stall
 348         condition cleared.
 349
 350         on the next cycle (as long as stall is not raised again) the
 351         input may begin to be processed and transferred directly to output.
 352     """
 353
 354     def elaborate(self, platform):
 355         self.m = ControlBase.elaborate(self, platform)
 356
 357         result = _spec(self.stage.ospec, "r_tmp")
 358         r_data = _spec(self.stage.ospec, "r_data")
 359
 360         # establish some combinatorial temporaries
 361         o_n_validn = Signal(reset_less=True)
 362         n_ready_i = Signal(reset_less=True, name="n_i_rdy_data")
 363         nir_por = Signal(reset_less=True)
 364         nir_por_n = Signal(reset_less=True)
 365         p_valid_i = Signal(reset_less=True)
 366         nir_novn = Signal(reset_less=True)
 367         nirn_novn = Signal(reset_less=True)
 368         por_pivn = Signal(reset_less=True)
 369         npnn = Signal(reset_less=True)
 370         self.m.d.comb += [p_valid_i.eq(self.p.valid_i_test),
 371                      o_n_validn.eq(~self.n.valid_o),
 372                      n_ready_i.eq(self.n.ready_i_test),
 373                      nir_por.eq(n_ready_i & self.p._ready_o),
 374                      nir_por_n.eq(n_ready_i & ~self.p._ready_o),
 375                      nir_novn.eq(n_ready_i | o_n_validn),
 376                      nirn_novn.eq(~n_ready_i & o_n_validn),
 377                      npnn.eq(nir_por | nirn_novn),
 378                      por_pivn.eq(self.p._ready_o & ~p_valid_i)
 379         ]
 380
 381         # store result of processing in combinatorial temporary
 382         self.m.d.comb += nmoperator.eq(result, self.data_r)
 383
 384         # if not in stall condition, update the temporary register
 385         with self.m.If(self.p.ready_o): # not stalled
 386             self.m.d.sync += nmoperator.eq(r_data, result) # update buffer
 387
 388         # data pass-through conditions
 389         with self.m.If(npnn):
 390             data_o = self._postprocess(result) # XXX TBD, does nothing right now
 391             self.m.d.sync += [self.n.valid_o.eq(p_valid_i), # valid if p_valid
 392                               nmoperator.eq(self.n.data_o, data_o), # update out
 393                              ]
 394         # buffer flush conditions (NOTE: can override data passthru conditions)
 395         with self.m.If(nir_por_n): # not stalled
 396             # Flush the [already processed] buffer to the output port.
 397             data_o = self._postprocess(r_data) # XXX TBD, does nothing right now
 398             self.m.d.sync += [self.n.valid_o.eq(1),  # reg empty
 399                               nmoperator.eq(self.n.data_o, data_o), # flush
 400                              ]
 401         # output ready conditions
 402         self.m.d.sync += self.p._ready_o.eq(nir_novn | por_pivn)
 403
 404         return self.m
 405
 406
 407 class SimpleHandshake(ControlBase):
 408     """ simple handshake control.  data and strobe signals travel in sync.
 409         implements the protocol used by Wishbone and AXI4.
 410
 411         Argument: stage.  see Stage API above
 412
 413         stage-1   p.valid_i >>in   stage   n.valid_o out>>   stage+1
 414         stage-1   p.ready_o <<out  stage   n.ready_i <<in    stage+1
 415         stage-1   p.data_i  >>in   stage   n.data_o  out>>   stage+1
 416                               |             |
 417                               +--process->--^
 418         Truth Table
 419
 420         Inputs   Temporary  Output Data
 421         -------  ---------- -----  ----
 422         P P N N  PiV& ~NiR&  N P
 423         i o i o  PoR  NoV    o o
 424         V R R V              V R
 425
 426         -------   -    -     - -
 427         0 0 0 0   0    0    >0 0    reg
 428         0 0 0 1   0    1    >1 0    reg
 429         0 0 1 0   0    0     0 1    process(data_i)
 430         0 0 1 1   0    0     0 1    process(data_i)
 431         -------   -    -     - -
 432         0 1 0 0   0    0    >0 0    reg
 433         0 1 0 1   0    1    >1 0    reg
 434         0 1 1 0   0    0     0 1    process(data_i)
 435         0 1 1 1   0    0     0 1    process(data_i)
 436         -------   -    -     - -
 437         1 0 0 0   0    0    >0 0    reg
 438         1 0 0 1   0    1    >1 0    reg
 439         1 0 1 0   0    0     0 1    process(data_i)
 440         1 0 1 1   0    0     0 1    process(data_i)
 441         -------   -    -     - -
 442         1 1 0 0   1    0     1 0    process(data_i)
 443         1 1 0 1   1    1     1 0    process(data_i)
 444         1 1 1 0   1    0     1 1    process(data_i)
 445         1 1 1 1   1    0     1 1    process(data_i)
 446         -------   -    -     - -
 447     """
 448
 449     def elaborate(self, platform):
 450         self.m = m = ControlBase.elaborate(self, platform)
 451
 452         r_busy = Signal()
 453         result = _spec(self.stage.ospec, "r_tmp")
 454
 455         # establish some combinatorial temporaries
 456         n_ready_i = Signal(reset_less=True, name="n_i_rdy_data")
 457         p_valid_i_p_ready_o = Signal(reset_less=True)
 458         p_valid_i = Signal(reset_less=True)
 459         m.d.comb += [p_valid_i.eq(self.p.valid_i_test),
 460                      n_ready_i.eq(self.n.ready_i_test),
 461                      p_valid_i_p_ready_o.eq(p_valid_i & self.p.ready_o),
 462         ]
 463
 464         # store result of processing in combinatorial temporary
 465         m.d.comb += nmoperator.eq(result, self.data_r)
 466
 467         # previous valid and ready
 468         with m.If(p_valid_i_p_ready_o):
 469             data_o = self._postprocess(result) # XXX TBD, does nothing right now
 470             m.d.sync += [r_busy.eq(1),      # output valid
 471                          nmoperator.eq(self.n.data_o, data_o), # update output
 472                         ]
 473         # previous invalid or not ready, however next is accepting
 474         with m.Elif(n_ready_i):
 475             data_o = self._postprocess(result) # XXX TBD, does nothing right now
 476             m.d.sync += [nmoperator.eq(self.n.data_o, data_o)]
 477             # TODO: could still send data here (if there was any)
 478             #m.d.sync += self.n.valid_o.eq(0) # ...so set output invalid
 479             m.d.sync += r_busy.eq(0) # ...so set output invalid
 480
 481         m.d.comb += self.n.valid_o.eq(r_busy)
 482         # if next is ready, so is previous
 483         m.d.comb += self.p._ready_o.eq(n_ready_i)
 484
 485         return self.m
 486
 487
 488 class UnbufferedPipeline(ControlBase):
 489     """ A simple pipeline stage with single-clock synchronisation
 490         and two-way valid/ready synchronised signalling.
 491
 492         Note that a stall in one stage will result in the entire pipeline
 493         chain stalling.
 494
 495         Also that unlike BufferedHandshake, the valid/ready signalling does NOT
 496         travel synchronously with the data: the valid/ready signalling
 497         combines in a *combinatorial* fashion.  Therefore, a long pipeline
 498         chain will lengthen propagation delays.
 499
 500         Argument: stage.  see Stage API, above
 501
 502         stage-1   p.valid_i >>in   stage   n.valid_o out>>   stage+1
 503         stage-1   p.ready_o <<out  stage   n.ready_i <<in    stage+1
 504         stage-1   p.data_i  >>in   stage   n.data_o  out>>   stage+1
 505                               |             |
 506                             r_data        result
 507                               |             |
 508                               +--process ->-+
 509
 510         Attributes:
 511         -----------
 512         p.data_i : StageInput, shaped according to ispec
 513             The pipeline input
 514         p.data_o : StageOutput, shaped according to ospec
 515             The pipeline output
 516         r_data : input_shape according to ispec
 517             A temporary (buffered) copy of a prior (valid) input.
 518             This is HELD if the output is not ready.  It is updated
 519             SYNCHRONOUSLY.
 520         result: output_shape according to ospec
 521             The output of the combinatorial logic.  it is updated
 522             COMBINATORIALLY (no clock dependence).
 523
 524         Truth Table
 525
 526         Inputs  Temp  Output  Data
 527         -------   -   -----   ----
 528         P P N N ~NiR&  N P
 529         i o i o  NoV   o o
 530         V R R V        V R
 531
 532         -------   -    - -
 533         0 0 0 0   0    0 1    reg
 534         0 0 0 1   1    1 0    reg
 535         0 0 1 0   0    0 1    reg
 536         0 0 1 1   0    0 1    reg
 537         -------   -    - -
 538         0 1 0 0   0    0 1    reg
 539         0 1 0 1   1    1 0    reg
 540         0 1 1 0   0    0 1    reg
 541         0 1 1 1   0    0 1    reg
 542         -------   -    - -
 543         1 0 0 0   0    1 1    reg
 544         1 0 0 1   1    1 0    reg
 545         1 0 1 0   0    1 1    reg
 546         1 0 1 1   0    1 1    reg
 547         -------   -    - -
 548         1 1 0 0   0    1 1    process(data_i)
 549         1 1 0 1   1    1 0    process(data_i)
 550         1 1 1 0   0    1 1    process(data_i)
 551         1 1 1 1   0    1 1    process(data_i)
 552         -------   -    - -
 553
 554         Note: PoR is *NOT* involved in the above decision-making.
 555     """
 556
 557     def elaborate(self, platform):
 558         self.m = m = ControlBase.elaborate(self, platform)
 559
 560         data_valid = Signal() # is data valid or not
 561         r_data = _spec(self.stage.ospec, "r_tmp") # output type
 562
 563         # some temporaries
 564         p_valid_i = Signal(reset_less=True)
 565         pv = Signal(reset_less=True)
 566         buf_full = Signal(reset_less=True)
 567         m.d.comb += p_valid_i.eq(self.p.valid_i_test)
 568         m.d.comb += pv.eq(self.p.valid_i & self.p.ready_o)
 569         m.d.comb += buf_full.eq(~self.n.ready_i_test & data_valid)
 570
 571         m.d.comb += self.n.valid_o.eq(data_valid)
 572         m.d.comb += self.p._ready_o.eq(~data_valid | self.n.ready_i_test)
 573         m.d.sync += data_valid.eq(p_valid_i | buf_full)
 574
 575         with m.If(pv):
 576             m.d.sync += nmoperator.eq(r_data, self.data_r)
 577         data_o = self._postprocess(r_data) # XXX TBD, does nothing right now
 578         m.d.comb += nmoperator.eq(self.n.data_o, data_o)
 579
 580         return self.m
 581
 582 class UnbufferedPipeline2(ControlBase):
 583     """ A simple pipeline stage with single-clock synchronisation
 584         and two-way valid/ready synchronised signalling.
 585
 586         Note that a stall in one stage will result in the entire pipeline
 587         chain stalling.
 588
 589         Also that unlike BufferedHandshake, the valid/ready signalling does NOT
 590         travel synchronously with the data: the valid/ready signalling
 591         combines in a *combinatorial* fashion.  Therefore, a long pipeline
 592         chain will lengthen propagation delays.
 593
 594         Argument: stage.  see Stage API, above
 595
 596         stage-1   p.valid_i >>in   stage   n.valid_o out>>   stage+1
 597         stage-1   p.ready_o <<out  stage   n.ready_i <<in    stage+1
 598         stage-1   p.data_i  >>in   stage   n.data_o  out>>   stage+1
 599                               |             |    |
 600                               +- process-> buf <-+
 601         Attributes:
 602         -----------
 603         p.data_i : StageInput, shaped according to ispec
 604             The pipeline input
 605         p.data_o : StageOutput, shaped according to ospec
 606             The pipeline output
 607         buf : output_shape according to ospec
 608             A temporary (buffered) copy of a valid output
 609             This is HELD if the output is not ready.  It is updated
 610             SYNCHRONOUSLY.
 611
 612         Inputs  Temp  Output Data
 613         -------   -   -----
 614         P P N N ~NiR&  N P   (buf_full)
 615         i o i o  NoV   o o
 616         V R R V        V R
 617
 618         -------   -    - -
 619         0 0 0 0   0    0 1   process(data_i)
 620         0 0 0 1   1    1 0   reg (odata, unchanged)
 621         0 0 1 0   0    0 1   process(data_i)
 622         0 0 1 1   0    0 1   process(data_i)
 623         -------   -    - -
 624         0 1 0 0   0    0 1   process(data_i)
 625         0 1 0 1   1    1 0   reg (odata, unchanged)
 626         0 1 1 0   0    0 1   process(data_i)
 627         0 1 1 1   0    0 1   process(data_i)
 628         -------   -    - -
 629         1 0 0 0   0    1 1   process(data_i)
 630         1 0 0 1   1    1 0   reg (odata, unchanged)
 631         1 0 1 0   0    1 1   process(data_i)
 632         1 0 1 1   0    1 1   process(data_i)
 633         -------   -    - -
 634         1 1 0 0   0    1 1   process(data_i)
 635         1 1 0 1   1    1 0   reg (odata, unchanged)
 636         1 1 1 0   0    1 1   process(data_i)
 637         1 1 1 1   0    1 1   process(data_i)
 638         -------   -    - -
 639
 640         Note: PoR is *NOT* involved in the above decision-making.
 641     """
 642
 643     def elaborate(self, platform):
 644         self.m = m = ControlBase.elaborate(self, platform)
 645
 646         buf_full = Signal() # is data valid or not
 647         buf = _spec(self.stage.ospec, "r_tmp") # output type
 648
 649         # some temporaries
 650         p_valid_i = Signal(reset_less=True)
 651         m.d.comb += p_valid_i.eq(self.p.valid_i_test)
 652
 653         m.d.comb += self.n.valid_o.eq(buf_full | p_valid_i)
 654         m.d.comb += self.p._ready_o.eq(~buf_full)
 655         m.d.sync += buf_full.eq(~self.n.ready_i_test & self.n.valid_o)
 656
 657         data_o = Mux(buf_full, buf, self.data_r)
 658         data_o = self._postprocess(data_o) # XXX TBD, does nothing right now
 659         m.d.comb += nmoperator.eq(self.n.data_o, data_o)
 660         m.d.sync += nmoperator.eq(buf, self.n.data_o)
 661
 662         return self.m
 663
 664
 665 class PassThroughHandshake(ControlBase):
 666     """ A control block that delays by one clock cycle.
 667
 668         Inputs   Temporary          Output Data
 669         -------  ------------------  ----- ----
 670         P P N N  PiV& PiV| NiR| pvr   N P  (pvr)
 671         i o i o  PoR  ~PoR ~NoV       o o
 672         V R R V                       V R
 673
 674         -------   -    -    -   -     - -
 675         0 0 0 0   0    1    1   0     1 1   odata (unchanged)
 676         0 0 0 1   0    1    0   0     1 0   odata (unchanged)
 677         0 0 1 0   0    1    1   0     1 1   odata (unchanged)
 678         0 0 1 1   0    1    1   0     1 1   odata (unchanged)
 679         -------   -    -    -   -     - -
 680         0 1 0 0   0    0    1   0     0 1   odata (unchanged)
 681         0 1 0 1   0    0    0   0     0 0   odata (unchanged)
 682         0 1 1 0   0    0    1   0     0 1   odata (unchanged)
 683         0 1 1 1   0    0    1   0     0 1   odata (unchanged)
 684         -------   -    -    -   -     - -
 685         1 0 0 0   0    1    1   1     1 1   process(in)
 686         1 0 0 1   0    1    0   0     1 0   odata (unchanged)
 687         1 0 1 0   0    1    1   1     1 1   process(in)
 688         1 0 1 1   0    1    1   1     1 1   process(in)
 689         -------   -    -    -   -     - -
 690         1 1 0 0   1    1    1   1     1 1   process(in)
 691         1 1 0 1   1    1    0   0     1 0   odata (unchanged)
 692         1 1 1 0   1    1    1   1     1 1   process(in)
 693         1 1 1 1   1    1    1   1     1 1   process(in)
 694         -------   -    -    -   -     - -
 695
 696     """
 697
 698     def elaborate(self, platform):
 699         self.m = m = ControlBase.elaborate(self, platform)
 700
 701         r_data = _spec(self.stage.ospec, "r_tmp") # output type
 702
 703         # temporaries
 704         p_valid_i = Signal(reset_less=True)
 705         pvr = Signal(reset_less=True)
 706         m.d.comb += p_valid_i.eq(self.p.valid_i_test)
 707         m.d.comb += pvr.eq(p_valid_i & self.p.ready_o)
 708
 709         m.d.comb += self.p.ready_o.eq(~self.n.valid_o |  self.n.ready_i_test)
 710         m.d.sync += self.n.valid_o.eq(p_valid_i       | ~self.p.ready_o)
 711
 712         odata = Mux(pvr, self.data_r, r_data)
 713         m.d.sync += nmoperator.eq(r_data, odata)
 714         r_data = self._postprocess(r_data) # XXX TBD, does nothing right now
 715         m.d.comb += nmoperator.eq(self.n.data_o, r_data)
 716
 717         return m
 718
 719
 720 class RegisterPipeline(UnbufferedPipeline):
 721     """ A pipeline stage that delays by one clock cycle, creating a
 722         sync'd latch out of data_o and valid_o as an indirect byproduct
 723         of using PassThroughStage
 724     """
 725     def __init__(self, iospecfn):
 726         UnbufferedPipeline.__init__(self, PassThroughStage(iospecfn))
 727
 728
 729 class FIFOControl(ControlBase):
 730     """ FIFO Control.  Uses Queue to store data, coincidentally
 731         happens to have same valid/ready signalling as Stage API.
 732         (TODO: remove use of SyncFIFOBuffered)
 733
 734         data_i -> fifo.din -> FIFO -> fifo.dout -> data_o
 735     """
 736     def __init__(self, depth, stage, in_multi=None, stage_ctl=False,
 737                                      fwft=True, buffered=False, pipe=False):
 738         """ FIFO Control
 739
 740             * :depth:    number of entries in the FIFO
 741             * :stage:    data processing block
 742             * :fwft:     first word fall-thru mode (non-fwft introduces delay)
 743             * :buffered: use buffered FIFO (introduces extra cycle delay)
 744
 745             NOTE 1: FPGAs may have trouble with the defaults for SyncFIFO
 746                     (fwft=True, buffered=False).  XXX TODO: fix this by
 747                     using Queue in all cases instead.
 748
 749             data is processed (and located) as follows:
 750
 751             self.p  self.stage temp    fn temp  fn  temp  fp   self.n
 752             data_i->process()->result->cat->din.FIFO.dout->cat(data_o)
 753
 754             yes, really: cat produces a Cat() which can be assigned to.
 755             this is how the FIFO gets de-catted without needing a de-cat
 756             function
 757         """
 758
 759         assert not (fwft and buffered), "buffered cannot do fwft"
 760         if buffered:
 761             depth += 1
 762         self.fwft = fwft
 763         self.buffered = buffered
 764         self.pipe = pipe
 765         self.fdepth = depth
 766         ControlBase.__init__(self, stage, in_multi, stage_ctl)
 767
 768     def elaborate(self, platform):
 769         self.m = m = ControlBase.elaborate(self, platform)
 770
 771         # make a FIFO with a signal of equal width to the data_o.
 772         (fwidth, _) = nmoperator.shape(self.n.data_o)
 773         if self.buffered:
 774             fifo = SyncFIFOBuffered(fwidth, self.fdepth)
 775         else:
 776             fifo = Queue(fwidth, self.fdepth, fwft=self.fwft, pipe=self.pipe)
 777         m.submodules.fifo = fifo
 778
 779         # store result of processing in combinatorial temporary
 780         result = _spec(self.stage.ospec, "r_temp")
 781         m.d.comb += nmoperator.eq(result, self.data_r)
 782
 783         # connect previous rdy/valid/data - do cat on data_i
 784         # NOTE: cannot do the PrevControl-looking trick because
 785         # of need to process the data.  shaaaame....
 786         m.d.comb += [fifo.we.eq(self.p.valid_i_test),
 787                      self.p.ready_o.eq(fifo.writable),
 788                      nmoperator.eq(fifo.din, nmoperator.cat(result)),
 789                    ]
 790
 791         # connect next rdy/valid/data - do cat on data_o (further below)
 792         connections = [self.n.valid_o.eq(fifo.readable),
 793                        fifo.re.eq(self.n.ready_i_test),
 794                       ]
 795         if self.fwft or self.buffered:
 796             m.d.comb += connections # combinatorial on next ready/valid
 797         else:
 798             m.d.sync += connections # unbuffered fwft mode needs sync
 799         data_o = nmoperator.cat(self.n.data_o).eq(fifo.dout)
 800         data_o = self._postprocess(data_o) # XXX TBD, does nothing right now
 801         m.d.comb += data_o
 802
 803         return m
 804
 805
 806 # aka "RegStage".
 807 class UnbufferedPipeline(FIFOControl):
 808     def __init__(self, stage, in_multi=None, stage_ctl=False):
 809         FIFOControl.__init__(self, 1, stage, in_multi, stage_ctl,
 810                                    fwft=True, pipe=False)
 811
 812 # aka "BreakReadyStage" XXX had to set fwft=True to get it to work
 813 class PassThroughHandshake(FIFOControl):
 814     def __init__(self, stage, in_multi=None, stage_ctl=False):
 815         FIFOControl.__init__(self, 1, stage, in_multi, stage_ctl,
 816                                    fwft=True, pipe=True)
 817
 818 # this is *probably* BufferedHandshake, although test #997 now succeeds.
 819 class BufferedHandshake(FIFOControl):
 820     def __init__(self, stage, in_multi=None, stage_ctl=False):
 821         FIFOControl.__init__(self, 2, stage, in_multi, stage_ctl,
 822                                    fwft=True, pipe=False)
 823
 824
 825 """
 826 # this is *probably* SimpleHandshake (note: memory cell size=0)
 827 class SimpleHandshake(FIFOControl):
 828     def __init__(self, stage, in_multi=None, stage_ctl=False):
 829         FIFOControl.__init__(self, 0, stage, in_multi, stage_ctl,
 830                                    fwft=True, pipe=False)
 831 """