rename flatten to cat
[ieee754fpu.git] / src / add / singlepipe.py
index 085b73dca145f6a24e2be14348007c41db7d96ee..011019fcfd1feafabccc2eb01d84f0538e0b0e3c 100644 (file)
@@ -1,6 +1,10 @@
 """ Pipeline and BufferedHandshake implementation, conforming to the same API.
     For multi-input and multi-output variants, see multipipe.
 
+    Associated development bugs:
+    * http://bugs.libre-riscv.org/show_bug.cgi?id=64
+    * http://bugs.libre-riscv.org/show_bug.cgi?id=57
+
     eq:
     --
 
 
 from nmigen import Signal, Cat, Const, Mux, Module, Value
 from nmigen.cli import verilog, rtlil
-from nmigen.lib.fifo import SyncFIFO
+from nmigen.lib.fifo import SyncFIFO, SyncFIFOBuffered
 from nmigen.hdl.ast import ArrayProxy
 from nmigen.hdl.rec import Record, Layout
 
 from abc import ABCMeta, abstractmethod
 from collections.abc import Sequence
+from queue import Queue
+
+
+class RecordObject(Record):
+    def __init__(self, layout=None, name=None):
+        Record.__init__(self, layout=layout or [], name=None)
+
+    def __setattr__(self, k, v):
+        if k in dir(Record) or "fields" not in self.__dict__:
+            return object.__setattr__(self, k, v)
+        self.fields[k] = v
+        if isinstance(v, Record):
+            newlayout = {k: (k, v.layout)}
+        else:
+            newlayout = {k: (k, v.shape())}
+        self.layout.fields.update(newlayout)
+
+    def __iter__(self):
+        for x in self.fields.values():
+            yield x
 
 
 class PrevControl:
@@ -199,17 +223,15 @@ class PrevControl:
             return self.s_o_ready # set dynamically by stage
         return self._o_ready      # return this when not under dynamic control
 
-    def _connect_in(self, prev, direct=False):
+    def _connect_in(self, prev, direct=False, fn=None):
         """ internal helper function to connect stage to an input source.
             do not use to connect stage-to-stage!
         """
-        if direct:
-            i_valid = prev.i_valid
-        else:
-            i_valid = prev.i_valid_test
+        i_valid = prev.i_valid if direct else prev.i_valid_test
+        i_data = fn(prev.i_data) if fn is not None else prev.i_data
         return [self.i_valid.eq(i_valid),
                 prev.o_ready.eq(self.o_ready),
-                eq(self.i_data, prev.i_data),
+                eq(self.i_data, i_data),
                ]
 
     @property
@@ -261,26 +283,20 @@ class NextControl:
                 eq(nxt.i_data, self.o_data),
                ]
 
-    def _connect_out(self, nxt, direct=False):
+    def _connect_out(self, nxt, direct=False, fn=None):
         """ internal helper function to connect stage to an output source.
             do not use to connect stage-to-stage!
         """
-        if direct:
-            i_ready = nxt.i_ready
-        else:
-            i_ready = nxt.i_ready_test
+        i_ready = nxt.i_ready if direct else nxt.i_ready_test
+        o_data = fn(nxt.o_data) if fn is not None else nxt.o_data
         return [nxt.o_valid.eq(self.o_valid),
                 self.i_ready.eq(i_ready),
-                eq(nxt.o_data, self.o_data),
+                eq(o_data, self.o_data),
                ]
 
 
-class Visitor:
-    """ a helper routine which identifies if it is being passed a list
-        (or tuple) of objects, or signals, or Records, and calls
-        a visitor function.
-
-        the visiting fn is called when an object is identified.
+class Visitor2:
+    """ a helper class for iterating twin-argument compound data structures.
 
         Record is a special (unusual, recursive) case, where the input may be
         specified as a dictionary (which may contain further dictionaries,
@@ -297,33 +313,28 @@ class Visitor:
         python object, enumerate them, find out the list of Signals that way,
         and assign them.
     """
-    def visit(self, o, i, act):
+    def iterator2(self, o, i):
         if isinstance(o, dict):
-            return self.dict_visit(o, i, act)
+            yield from self.dict_iter2(o, i)
 
-        res = act.prepare()
         if not isinstance(o, Sequence):
             o, i = [o], [i]
         for (ao, ai) in zip(o, i):
             #print ("visit", fn, ao, ai)
             if isinstance(ao, Record):
-                rres = self.record_visit(ao, ai, act)
+                yield from self.record_iter2(ao, ai)
             elif isinstance(ao, ArrayProxy) and not isinstance(ai, Value):
-                rres = self.arrayproxy_visit(ao, ai, act)
+                yield from self.arrayproxy_iter2(ao, ai)
             else:
-                rres = act.fn(ao, ai)
-            res += rres
-        return res
+                yield (ao, ai)
 
-    def dict_visit(self, o, i, act):
-        res = act.prepare()
+    def dict_iter2(self, o, i):
         for (k, v) in o.items():
-            print ("d-eq", v, i[k])
-            res.append(act.fn(v, i[k]))
+            print ("d-iter", v, i[k])
+            yield (v, i[k])
         return res
 
-    def record_visit(self, ao, ai, act):
-        res = act.prepare()
+    def record_iter2(self, ao, ai):
         for idx, (field_name, field_shape, _) in enumerate(ao.layout):
             if isinstance(field_shape, Layout):
                 val = ai.fields
@@ -333,34 +344,49 @@ class Visitor:
                 val = getattr(val, field_name)
             else:
                 val = val[field_name] # dictionary-style specification
-            val = self.visit(ao.fields[field_name], val, act)
-            if isinstance(val, Sequence):
-                rres += val
-            else:
-                rres.append(val)
-        return res
+            yield from self.iterator2(ao.fields[field_name], val)
 
-    def arrayproxy_visit(self, ao, ai, act):
-        res = act.prepare()
+    def arrayproxy_iter2(self, ao, ai):
         for p in ai.ports():
             op = getattr(ao, p.name)
-            #print (op, p, p.name)
-            res.append(fn(op, p))
-        return res
+            print ("arrayproxy - p", p, p.name)
+            yield from self.iterator2(op, p)
 
+class Visitor:
+    """ a helper class for iterating single-argument compound data structures.
+        similar to Visitor2.
+    """
+    def iterate(self, i):
+        """ iterate a compound structure recursively using yield
+        """
+        if not isinstance(i, Sequence):
+            i = [i]
+        for ai in i:
+            print ("iterate", ai)
+            if isinstance(ai, Record):
+                print ("record", list(ai.layout))
+                yield from self.record_iter(ai)
+            elif isinstance(ai, ArrayProxy) and not isinstance(ai, Value):
+                yield from self.array_iter(ai)
+            else:
+                yield ai
 
-class Eq(Visitor):
-    def __init__(self):
-        self.res = []
-    def prepare(self):
-        return []
-    def fn(self, o, i):
-        rres = o.eq(i)
-        if not isinstance(rres, Sequence):
-            rres = [rres]
-        return rres
-    def __call__(self, o, i):
-        return self.visit(o, i, self)
+    def record_iter(self, ai):
+        for idx, (field_name, field_shape, _) in enumerate(ai.layout):
+            if isinstance(field_shape, Layout):
+                val = ai.fields
+            else:
+                val = ai
+            if hasattr(val, field_name): # check for attribute
+                val = getattr(val, field_name)
+            else:
+                val = val[field_name] # dictionary-style specification
+            print ("recidx", idx, field_name, field_shape, val)
+            yield from self.iterate(val)
+
+    def array_iter(self, ai):
+        for p in ai.ports():
+            yield from self.iterate(p)
 
 
 def eq(o, i):
@@ -368,53 +394,39 @@ def eq(o, i):
         passed a list (or tuple) of objects, or signals, or Records, and calls
         the objects' eq function.
     """
-    return Eq()(o, i)
-
-
-def flatten(i):
-    """ flattens a compound structure recursively using Cat
-    """
-    if not isinstance(i, Sequence):
-        i = [i]
     res = []
-    for ai in i:
-        print ("flatten", ai)
-        if isinstance(ai, Record):
-            print ("record", list(ai.layout))
-            rres = []
-            for idx, (field_name, field_shape, _) in enumerate(ai.layout):
-                if isinstance(field_shape, Layout):
-                    val = ai.fields
-                else:
-                    val = ai
-                if hasattr(val, field_name): # check for attribute
-                    val = getattr(val, field_name)
-                else:
-                    val = val[field_name] # dictionary-style specification
-                print ("recidx", idx, field_name, field_shape, val)
-                val = flatten(val)
-                print ("recidx flat", idx, val)
-                if isinstance(val, Sequence):
-                    rres += val
-                else:
-                    rres.append(val)
-
-        elif isinstance(ai, ArrayProxy) and not isinstance(ai, Value):
-            rres = []
-            for p in ai.ports():
-                op = getattr(ai, p.name)
-                #print (op, p, p.name)
-                rres.append(flatten(p))
-        else:
-            rres = ai
+    for (ao, ai) in Visitor2().iterator2(o, i):
+        rres = ao.eq(ai)
         if not isinstance(rres, Sequence):
             rres = [rres]
         res += rres
-        print ("flatten res", res)
-    return Cat(*res)
+    return res
 
 
 
+def cat(i):
+    """ flattens a compound structure recursively using Cat
+
+        NOTE: this does NOT work:
+            from nmigen.tools import flatten
+            res = list(flatten(i))
+
+        the reason is that flatten is not sophisticated enough,
+        and does not support iteration on Record:
+
+          File "nmigen/tools.py", line 12, in flatten
+            for e in i:
+          File "nmigen/hdl/rec.py", line 98, in __getitem__
+            .format(reference, name, ", ".join(self.fields))) from None
+          NameError: Unnamed record does not have a field '0'.
+                     Did you mean one of: sig1, r2, r3?
+    """
+    #from nmigen.tools import flatten
+    #res = list(flatten(i))
+    res = list(Visitor().iterate(i))
+    return Cat(*res)
+
+
 class StageCls(metaclass=ABCMeta):
     """ Class-based "Stage" API.  requires instantiation (after derivation)
 
@@ -616,6 +628,12 @@ class ControlBase:
 
         return eqs
 
+    def _postprocess(self, i): # XXX DISABLED
+        return i # RETURNS INPUT
+        if hasattr(self.stage, "postprocess"):
+            return self.stage.postprocess(i)
+        return i
+
     def set_input(self, i):
         """ helper function to set the input data
         """
@@ -722,14 +740,16 @@ class BufferedHandshake(ControlBase):
 
         # data pass-through conditions
         with self.m.If(npnn):
+            o_data = self._postprocess(result)
             self.m.d.sync += [self.n.o_valid.eq(p_i_valid), # valid if p_valid
-                              eq(self.n.o_data, result),    # update output
+                              eq(self.n.o_data, o_data),    # update output
                              ]
         # buffer flush conditions (NOTE: can override data passthru conditions)
         with self.m.If(nir_por_n): # not stalled
             # Flush the [already processed] buffer to the output port.
+            o_data = self._postprocess(r_data)
             self.m.d.sync += [self.n.o_valid.eq(1),  # reg empty
-                              eq(self.n.o_data, r_data), # flush buffer
+                              eq(self.n.o_data, o_data), # flush buffer
                              ]
         # output ready conditions
         self.m.d.sync += self.p._o_ready.eq(nir_novn | por_pivn)
@@ -750,32 +770,32 @@ class SimpleHandshake(ControlBase):
                               +--process->--^
         Truth Table
 
-        Inputs   Temporary  Output
-        -------  ---------- -----
-        P P N N  PiV& ~NiV&  N P
+        Inputs   Temporary  Output Data
+        -------  ---------- -----  ----
+        P P N N  PiV& ~NiR&  N P
         i o i o  PoR  NoV    o o
         V R R V              V R
 
         -------   -    -     - -
-        0 0 0 0   0    0    >0 0
-        0 0 0 1   0    1    >1 0
-        0 0 1 0   0    0     0 1
-        0 0 1 1   0    0     0 1
+        0 0 0 0   0    0    >0 0    reg
+        0 0 0 1   0    1    >1 0    reg
+        0 0 1 0   0    0     0 1    process(i_data)
+        0 0 1 1   0    0     0 1    process(i_data)
         -------   -    -     - -
-        0 1 0 0   0    0    >0 0
-        0 1 0 1   0    1    >1 0
-        0 1 1 0   0    0     0 1
-        0 1 1 1   0    0     0 1
+        0 1 0 0   0    0    >0 0    reg
+        0 1 0 1   0    1    >1 0    reg
+        0 1 1 0   0    0     0 1    process(i_data)
+        0 1 1 1   0    0     0 1    process(i_data)
         -------   -    -     - -
-        1 0 0 0   0    0    >0 0
-        1 0 0 1   0    1    >1 0
-        1 0 1 0   0    0     0 1
-        1 0 1 1   0    0     0 1
+        1 0 0 0   0    0    >0 0    reg
+        1 0 0 1   0    1    >1 0    reg
+        1 0 1 0   0    0     0 1    process(i_data)
+        1 0 1 1   0    0     0 1    process(i_data)
         -------   -    -     - -
-        1 1 0 0   1    0     1 0
-        1 1 0 1   1    1     1 0
-        1 1 1 0   1    0     1 1
-        1 1 1 1   1    0     1 1
+        1 1 0 0   1    0     1 0    process(i_data)
+        1 1 0 1   1    1     1 0    process(i_data)
+        1 1 1 0   1    0     1 1    process(i_data)
+        1 1 1 1   1    0     1 1    process(i_data)
         -------   -    -     - -
     """
 
@@ -799,12 +819,14 @@ class SimpleHandshake(ControlBase):
 
         # previous valid and ready
         with m.If(p_i_valid_p_o_ready):
+            o_data = self._postprocess(result)
             m.d.sync += [r_busy.eq(1),      # output valid
-                         eq(self.n.o_data, result), # update output
+                         eq(self.n.o_data, o_data), # update output
                         ]
         # previous invalid or not ready, however next is accepting
         with m.Elif(n_i_ready):
-            m.d.sync += [eq(self.n.o_data, result)]
+            o_data = self._postprocess(result)
+            m.d.sync += [eq(self.n.o_data, o_data)]
             # TODO: could still send data here (if there was any)
             #m.d.sync += self.n.o_valid.eq(0) # ...so set output invalid
             m.d.sync += r_busy.eq(0) # ...so set output invalid
@@ -854,32 +876,32 @@ class UnbufferedPipeline(ControlBase):
 
         Truth Table
 
-        Inputs  Temp  Output
-        -------   -   -----
+        Inputs  Temp  Output  Data
+        -------   -   -----   ----
         P P N N ~NiR&  N P
         i o i o  NoV   o o
         V R R V        V R
 
         -------   -    - -
-        0 0 0 0   0    0 1
-        0 0 0 1   1    1 0
-        0 0 1 0   0    0 1
-        0 0 1 1   0    0 1
+        0 0 0 0   0    0 1    reg
+        0 0 0 1   1    1 0    reg
+        0 0 1 0   0    0 1    reg
+        0 0 1 1   0    0 1    reg
         -------   -    - -
-        0 1 0 0   0    0 1
-        0 1 0 1   1    1 0
-        0 1 1 0   0    0 1
-        0 1 1 1   0    0 1
+        0 1 0 0   0    0 1    reg
+        0 1 0 1   1    1 0    reg
+        0 1 1 0   0    0 1    reg
+        0 1 1 1   0    0 1    reg
         -------   -    - -
-        1 0 0 0   0    1 1
-        1 0 0 1   1    1 0
-        1 0 1 0   0    1 1
-        1 0 1 1   0    1 1
+        1 0 0 0   0    1 1    reg
+        1 0 0 1   1    1 0    reg
+        1 0 1 0   0    1 1    reg
+        1 0 1 1   0    1 1    reg
         -------   -    - -
-        1 1 0 0   0    1 1
-        1 1 0 1   1    1 0
-        1 1 1 0   0    1 1
-        1 1 1 1   0    1 1
+        1 1 0 0   0    1 1    process(i_data)
+        1 1 0 1   1    1 0    process(i_data)
+        1 1 1 0   0    1 1    process(i_data)
+        1 1 1 1   0    1 1    process(i_data)
         -------   -    - -
 
         Note: PoR is *NOT* involved in the above decision-making.
@@ -894,20 +916,22 @@ class UnbufferedPipeline(ControlBase):
         # some temporaries
         p_i_valid = Signal(reset_less=True)
         pv = Signal(reset_less=True)
+        buf_full = Signal(reset_less=True)
         m.d.comb += p_i_valid.eq(self.p.i_valid_test)
         m.d.comb += pv.eq(self.p.i_valid & self.p.o_ready)
+        m.d.comb += buf_full.eq(~self.n.i_ready_test & data_valid)
 
         m.d.comb += self.n.o_valid.eq(data_valid)
         m.d.comb += self.p._o_ready.eq(~data_valid | self.n.i_ready_test)
-        m.d.sync += data_valid.eq(p_i_valid | \
-                                        (~self.n.i_ready_test & data_valid))
+        m.d.sync += data_valid.eq(p_i_valid | buf_full)
+
         with m.If(pv):
             m.d.sync += eq(r_data, self.stage.process(self.p.i_data))
-        m.d.comb += eq(self.n.o_data, r_data)
+        o_data = self._postprocess(r_data)
+        m.d.comb += eq(self.n.o_data, o_data)
 
         return self.m
 
-
 class UnbufferedPipeline2(ControlBase):
     """ A simple pipeline stage with single-clock synchronisation
         and two-way valid/ready synchronised signalling.
@@ -937,6 +961,36 @@ class UnbufferedPipeline2(ControlBase):
             A temporary (buffered) copy of a valid output
             This is HELD if the output is not ready.  It is updated
             SYNCHRONOUSLY.
+
+        Inputs  Temp  Output Data
+        -------   -   -----
+        P P N N ~NiR&  N P   (buf_full)
+        i o i o  NoV   o o
+        V R R V        V R
+
+        -------   -    - -
+        0 0 0 0   0    0 1   process(i_data)
+        0 0 0 1   1    1 0   reg (odata, unchanged)
+        0 0 1 0   0    0 1   process(i_data)
+        0 0 1 1   0    0 1   process(i_data)
+        -------   -    - -
+        0 1 0 0   0    0 1   process(i_data)
+        0 1 0 1   1    1 0   reg (odata, unchanged)
+        0 1 1 0   0    0 1   process(i_data)
+        0 1 1 1   0    0 1   process(i_data)
+        -------   -    - -
+        1 0 0 0   0    1 1   process(i_data)
+        1 0 0 1   1    1 0   reg (odata, unchanged)
+        1 0 1 0   0    1 1   process(i_data)
+        1 0 1 1   0    1 1   process(i_data)
+        -------   -    - -
+        1 1 0 0   0    1 1   process(i_data)
+        1 1 0 1   1    1 0   reg (odata, unchanged)
+        1 1 1 0   0    1 1   process(i_data)
+        1 1 1 1   0    1 1   process(i_data)
+        -------   -    - -
+
+        Note: PoR is *NOT* involved in the above decision-making.
     """
 
     def elaborate(self, platform):
@@ -953,8 +1007,9 @@ class UnbufferedPipeline2(ControlBase):
         m.d.comb += self.p._o_ready.eq(~buf_full)
         m.d.sync += buf_full.eq(~self.n.i_ready_test & self.n.o_valid)
 
-        odata = Mux(buf_full, buf, self.stage.process(self.p.i_data))
-        m.d.comb += eq(self.n.o_data, odata)
+        o_data = Mux(buf_full, buf, self.stage.process(self.p.i_data))
+        o_data = self._postprocess(o_data)
+        m.d.comb += eq(self.n.o_data, o_data)
         m.d.sync += eq(buf, self.n.o_data)
 
         return self.m
@@ -973,11 +1028,42 @@ class PassThroughStage(StageCls):
 
 class PassThroughHandshake(ControlBase):
     """ A control block that delays by one clock cycle.
+
+        Inputs   Temporary          Output Data
+        -------  ------------------  ----- ----
+        P P N N  PiV& PiV| NiR| pvr   N P  (pvr)
+        i o i o  PoR  ~PoR ~NoV       o o
+        V R R V                       V R
+
+        -------   -    -    -   -     - -
+        0 0 0 0   0    1    1   0     1 1   odata (unchanged)
+        0 0 0 1   0    1    0   0     1 0   odata (unchanged)
+        0 0 1 0   0    1    1   0     1 1   odata (unchanged)
+        0 0 1 1   0    1    1   0     1 1   odata (unchanged)
+        -------   -    -    -   -     - -
+        0 1 0 0   0    0    1   0     0 1   odata (unchanged)
+        0 1 0 1   0    0    0   0     0 0   odata (unchanged)
+        0 1 1 0   0    0    1   0     0 1   odata (unchanged)
+        0 1 1 1   0    0    1   0     0 1   odata (unchanged)
+        -------   -    -    -   -     - -
+        1 0 0 0   0    1    1   1     1 1   process(in)
+        1 0 0 1   0    1    0   0     1 0   odata (unchanged)
+        1 0 1 0   0    1    1   1     1 1   process(in)
+        1 0 1 1   0    1    1   1     1 1   process(in)
+        -------   -    -    -   -     - -
+        1 1 0 0   1    1    1   1     1 1   process(in)
+        1 1 0 1   1    1    0   0     1 0   odata (unchanged)
+        1 1 1 0   1    1    1   1     1 1   process(in)
+        1 1 1 1   1    1    1   1     1 1   process(in)
+        -------   -    -    -   -     - -
+
     """
 
     def elaborate(self, platform):
         self.m = m = ControlBase._elaborate(self, platform)
 
+        r_data = self.stage.ospec() # output type
+
         # temporaries
         p_i_valid = Signal(reset_less=True)
         pvr = Signal(reset_less=True)
@@ -987,8 +1073,10 @@ class PassThroughHandshake(ControlBase):
         m.d.comb += self.p.o_ready.eq(~self.n.o_valid |  self.n.i_ready_test)
         m.d.sync += self.n.o_valid.eq(p_i_valid       | ~self.p.o_ready)
 
-        odata = Mux(pvr, self.stage.process(self.p.i_data), self.n.o_data)
-        m.d.sync += eq(self.n.o_data, odata)
+        odata = Mux(pvr, self.stage.process(self.p.i_data), r_data)
+        m.d.sync += eq(r_data, odata)
+        r_data = self._postprocess(r_data)
+        m.d.comb += eq(self.n.o_data, r_data)
 
         return m
 
@@ -1002,42 +1090,108 @@ class RegisterPipeline(UnbufferedPipeline):
         UnbufferedPipeline.__init__(self, PassThroughStage(iospecfn))
 
 
-class FIFOtest(ControlBase):
-    """ A test of using a SyncFIFO to see if it will work.
-        Note: the only things it will accept is a Signal of width "width".
+class FIFOControl(ControlBase):
+    """ FIFO Control.  Uses SyncFIFO to store data, coincidentally
+        happens to have same valid/ready signalling as Stage API.
+
+        i_data -> fifo.din -> FIFO -> fifo.dout -> o_data
     """
 
-    def __init__(self, width, depth):
+    def __init__(self, depth, stage, in_multi=None, stage_ctl=False,
+                                     fwft=True, buffered=False, pipe=False):
+        """ FIFO Control
+
+            * depth: number of entries in the FIFO
+            * stage: data processing block
+            * fwft : first word fall-thru mode (non-fwft introduces delay)
+            * buffered: use buffered FIFO (introduces extra cycle delay)
+
+            NOTE 1: FPGAs may have trouble with the defaults for SyncFIFO
+                    (fwft=True, buffered=False)
+
+            NOTE 2: i_data *must* have a shape function.  it can therefore
+                    be a Signal, or a Record, or a RecordObject.
+
+            data is processed (and located) as follows:
+
+            self.p  self.stage temp    fn temp  fn  temp  fp   self.n
+            i_data->process()->result->cat->din.FIFO.dout->cat(o_data)
 
-        self.fwidth = width
+            yes, really: cat produces a Cat() which can be assigned to.
+            this is how the FIFO gets de-catted without needing a de-cat
+            function
+        """
+
+        assert not (fwft and buffered), "buffered cannot do fwft"
+        if buffered:
+            depth += 1
+        self.fwft = fwft
+        self.buffered = buffered
+        self.pipe = pipe
         self.fdepth = depth
-        def iospecfn():
-            return Signal(width, name="data")
-        stage = PassThroughStage(iospecfn)
-        ControlBase.__init__(self, stage=stage)
+        ControlBase.__init__(self, stage, in_multi, stage_ctl)
 
     def elaborate(self, platform):
         self.m = m = ControlBase._elaborate(self, platform)
 
-        fifo = SyncFIFO(self.fwidth, self.fdepth)
+        # make a FIFO with a signal of equal width to the o_data.
+        (fwidth, _) = self.n.o_data.shape()
+        if self.buffered:
+            fifo = SyncFIFOBuffered(fwidth, self.fdepth)
+        else:
+            fifo = Queue(fwidth, self.fdepth, fwft=self.fwft, pipe=self.pipe)
         m.submodules.fifo = fifo
 
-        # prev: make the FIFO "look" like a PrevControl...
-        fp = PrevControl()
-        fp.i_valid = fifo.we
-        fp._o_ready = fifo.writable
-        fp.i_data = fifo.din
-        # ... so we can do this!
-        m.d.comb += fp._connect_in(self.p, True)
-
-        # next: make the FIFO "look" like a NextControl...
-        fn = NextControl()
-        fn.o_valid = fifo.readable
-        fn.i_ready = fifo.re
-        fn.o_data = fifo.dout
-        # ... so we can do this!
-        m.d.comb += fn._connect_out(self.n)
-
-        # err... that should be all!
+        # store result of processing in combinatorial temporary
+        result = self.stage.ospec()
+        m.d.comb += eq(result, self.stage.process(self.p.i_data))
+
+        # connect previous rdy/valid/data - do cat on i_data
+        # NOTE: cannot do the PrevControl-looking trick because
+        # of need to process the data.  shaaaame....
+        m.d.comb += [fifo.we.eq(self.p.i_valid_test),
+                     self.p.o_ready.eq(fifo.writable),
+                     eq(fifo.din, cat(result)),
+                   ]
+
+        # connect next rdy/valid/data - do cat on o_data
+        connections = [self.n.o_valid.eq(fifo.readable),
+                     fifo.re.eq(self.n.i_ready_test),
+                   ]
+        if self.fwft or self.buffered:
+            m.d.comb += connections
+        else:
+            m.d.sync += connections # unbuffered fwft mode needs sync
+        o_data = cat(self.n.o_data).eq(fifo.dout)
+        o_data = self._postprocess(o_data)
+        m.d.comb += o_data
+
         return m
 
+
+# aka "RegStage".
+class UnbufferedPipeline(FIFOControl):
+    def __init__(self, stage, in_multi=None, stage_ctl=False):
+        FIFOControl.__init__(self, 1, stage, in_multi, stage_ctl,
+                                   fwft=True, pipe=False)
+
+# aka "BreakReadyStage" XXX had to set fwft=True to get it to work
+class PassThroughHandshake(FIFOControl):
+    def __init__(self, stage, in_multi=None, stage_ctl=False):
+        FIFOControl.__init__(self, 1, stage, in_multi, stage_ctl,
+                                   fwft=True, pipe=True)
+
+# this is *probably* BufferedHandshake, although test #997 now succeeds.
+class BufferedHandshake(FIFOControl):
+    def __init__(self, stage, in_multi=None, stage_ctl=False):
+        FIFOControl.__init__(self, 2, stage, in_multi, stage_ctl,
+                                   fwft=True, pipe=False)
+
+
+"""
+# this is *probably* SimpleHandshake (note: memory cell size=0)
+class SimpleHandshake(FIFOControl):
+    def __init__(self, stage, in_multi=None, stage_ctl=False):
+        FIFOControl.__init__(self, 0, stage, in_multi, stage_ctl,
+                                   fwft=True, pipe=False)
+"""