src/add/multipipe.py

   1 """ Combinatorial Multi-input multiplexer block conforming to Pipeline API
   2 """
   3
   4 from math import log
   5 from nmigen import Signal, Cat, Const, Mux, Module, Array
   6 from nmigen.cli import verilog, rtlil
   7 from nmigen.lib.coding import PriorityEncoder
   8 from nmigen.hdl.rec import Record, Layout
   9
  10 from collections.abc import Sequence
  11
  12 from example_buf_pipe import eq, NextControl, PrevControl, ExampleStage
  13
  14
  15 class MultiInControlBase:
  16     """ Common functions for Pipeline API
  17     """
  18     def __init__(self, in_multi=None, p_len=1):
  19         """ Multi-input Control class.  Conforms to same API as ControlBase...
  20             mostly.  has additional indices to the *multiple* input stages
  21
  22             * p: contains ready/valid to the previous stages PLURAL
  23             * n: contains ready/valid to the next stage
  24
  25             User must also:
  26             * add i_data members to PrevControl and
  27             * add o_data member  to NextControl
  28         """
  29         # set up input and output IO ACK (prev/next ready/valid)
  30         p = []
  31         for i in range(p_len):
  32             p.append(PrevControl(in_multi))
  33         self.p = Array(p)
  34         self.n = NextControl()
  35
  36     def connect_to_next(self, nxt, p_idx=0):
  37         """ helper function to connect to the next stage data/valid/ready.
  38         """
  39         return self.n.connect_to_next(nxt.p[p_idx])
  40
  41     def _connect_in(self, prev, idx=0, prev_idx=None):
  42         """ helper function to connect stage to an input source.  do not
  43             use to connect stage-to-stage!
  44         """
  45         if prev_idx is None:
  46             return self.p[idx]._connect_in(prev.p)
  47         return self.p[idx]._connect_in(prev.p[prev_idx])
  48
  49     def _connect_out(self, nxt):
  50         """ helper function to connect stage to an output source.  do not
  51             use to connect stage-to-stage!
  52         """
  53         if nxt_idx is None:
  54             return self.n._connect_out(nxt.n)
  55         return self.n._connect_out(nxt.n)
  56
  57     def set_input(self, i, idx=0):
  58         """ helper function to set the input data
  59         """
  60         return eq(self.p[idx].i_data, i)
  61
  62     def ports(self):
  63         res = []
  64         for i in range(len(self.p)):
  65             res += [self.p[i].i_valid, self.p[i].o_ready,
  66                     self.p[i].i_data]# XXX need flattening!]
  67         res += [self.n.i_ready, self.n.o_valid,
  68                 self.n.o_data]   # XXX need flattening!]
  69         return res
  70
  71
  72
  73 class MultiOutControlBase:
  74     """ Common functions for Pipeline API
  75     """
  76     def __init__(self, n_len=1, in_multi=None):
  77         """ Multi-output Control class.  Conforms to same API as ControlBase...
  78             mostly.  has additional indices to the multiple *output* stages
  79             [MultiInControlBase has multiple *input* stages]
  80
  81             * p: contains ready/valid to the previou stage
  82             * n: contains ready/valid to the next stages PLURAL
  83
  84             User must also:
  85             * add i_data member to PrevControl and
  86             * add o_data members to NextControl
  87         """
  88
  89         # set up input and output IO ACK (prev/next ready/valid)
  90         self.p = PrevControl(in_multi)
  91         n = []
  92         for i in range(n_len):
  93             n.append(NextControl())
  94         self.n = Array(n)
  95
  96     def connect_to_next(self, nxt, n_idx=0):
  97         """ helper function to connect to the next stage data/valid/ready.
  98         """
  99         return self.n[n_idx].connect_to_next(nxt.p)
 100
 101     def _connect_in(self, prev, idx=0):
 102         """ helper function to connect stage to an input source.  do not
 103             use to connect stage-to-stage!
 104         """
 105         return self.n[idx]._connect_in(prev.p)
 106
 107     def _connect_out(self, nxt, idx=0, nxt_idx=None):
 108         """ helper function to connect stage to an output source.  do not
 109             use to connect stage-to-stage!
 110         """
 111         if nxt_idx is None:
 112             return self.n[idx]._connect_out(nxt.n)
 113         return self.n[idx]._connect_out(nxt.n[nxt_idx])
 114
 115     def set_input(self, i):
 116         """ helper function to set the input data
 117         """
 118         return eq(self.p.i_data, i)
 119
 120     def ports(self):
 121         res = []
 122         res += [self.p.i_valid, self.p.o_ready,
 123                 self.p.i_data] # XXX need flattening!
 124         for i in range(len(self.n)):
 125             res += [self.n[i].i_ready, self.n[i].o_valid,
 126                     self.n[i].o_data]   # XXX need flattening!
 127         return res
 128
 129
 130
 131 class CombMultiOutPipeline(MultiOutControlBase):
 132     """ A multi-input Combinatorial block conforming to the Pipeline API
 133
 134         Attributes:
 135         -----------
 136         p.i_data : StageInput, shaped according to ispec
 137             The pipeline input
 138         p.o_data : StageOutput, shaped according to ospec
 139             The pipeline output
 140         r_data : input_shape according to ispec
 141             A temporary (buffered) copy of a prior (valid) input.
 142             This is HELD if the output is not ready.  It is updated
 143             SYNCHRONOUSLY.
 144     """
 145
 146     def __init__(self, stage, n_len, n_mux):
 147         MultiOutControlBase.__init__(self, n_len=n_len)
 148         self.stage = stage
 149         self.n_mux = n_mux
 150
 151         # set up the input and output data
 152         self.p.i_data = stage.ispec() # input type
 153         for i in range(n_len):
 154             self.n[i].o_data = stage.ospec() # output type
 155
 156     def elaborate(self, platform):
 157         m = Module()
 158
 159         #m.submodules += self.n_mux
 160
 161         # need buffer register conforming to *input* spec
 162         r_data = self.stage.ispec() # input type
 163         if hasattr(self.stage, "setup"):
 164             self.stage.setup(m, r_data)
 165
 166         data_valid = []
 167         n_i_readyn = []
 168         n_len = len(self.n)
 169         for i in range(n_len):
 170             data_valid.append(Signal(name="data_valid", reset_less=True))
 171             n_i_readyn.append(Signal(name="n_i_readyn", reset_less=True))
 172         n_i_readyn = Array(n_i_readyn)
 173         data_valid = Array(data_valid)
 174
 175         p_i_valid = Signal(reset_less=True)
 176         m.d.comb += p_i_valid.eq(self.p.i_valid_logic())
 177
 178         mid = self.n_mux.m_id
 179
 180         for i in range(n_len):
 181             m.d.comb += data_valid[i].eq(0)
 182             m.d.comb += n_i_readyn[i].eq(1)
 183             m.d.comb += self.n[i].o_valid.eq(0)
 184         m.d.comb += self.n[mid].o_valid.eq(data_valid[mid])
 185         m.d.comb += n_i_readyn[mid].eq(~self.n[mid].i_ready & data_valid[mid])
 186         anyvalid = Signal(i, reset_less=True)
 187         av = []
 188         for i in range(n_len):
 189             av.append(~data_valid[i] | self.n[i].i_ready)
 190         anyvalid = Cat(*av)
 191         m.d.comb += self.p.o_ready.eq(anyvalid.bool())
 192         m.d.comb += data_valid[mid].eq(p_i_valid | \
 193                                     (n_i_readyn[mid] & data_valid[mid]))
 194
 195         with m.If(self.p.i_valid & self.p.o_ready):
 196             m.d.comb += eq(r_data, self.p.i_data)
 197         m.d.comb += eq(self.n[mid].o_data, self.stage.process(r_data))
 198
 199         return m
 200
 201
 202 class CombMultiInPipeline(MultiInControlBase):
 203     """ A multi-input Combinatorial block conforming to the Pipeline API
 204
 205         Attributes:
 206         -----------
 207         p.i_data : StageInput, shaped according to ispec
 208             The pipeline input
 209         p.o_data : StageOutput, shaped according to ospec
 210             The pipeline output
 211         r_data : input_shape according to ispec
 212             A temporary (buffered) copy of a prior (valid) input.
 213             This is HELD if the output is not ready.  It is updated
 214             SYNCHRONOUSLY.
 215     """
 216
 217     def __init__(self, stage, p_len, p_mux):
 218         MultiInControlBase.__init__(self, p_len=p_len)
 219         self.stage = stage
 220         self.p_mux = p_mux
 221
 222         # set up the input and output data
 223         for i in range(p_len):
 224             self.p[i].i_data = stage.ispec() # input type
 225         self.n.o_data = stage.ospec()
 226
 227     def elaborate(self, platform):
 228         m = Module()
 229
 230         m.submodules += self.p_mux
 231
 232         # need an array of buffer registers conforming to *input* spec
 233         r_data = []
 234         data_valid = []
 235         p_i_valid = []
 236         n_i_readyn = []
 237         p_len = len(self.p)
 238         for i in range(p_len):
 239             r = self.stage.ispec() # input type
 240             r_data.append(r)
 241             data_valid.append(Signal(name="data_valid", reset_less=True))
 242             p_i_valid.append(Signal(name="p_i_valid", reset_less=True))
 243             n_i_readyn.append(Signal(name="n_i_readyn", reset_less=True))
 244             if hasattr(self.stage, "setup"):
 245                 self.stage.setup(m, r)
 246         if len(r_data) > 1:
 247             r_data = Array(r_data)
 248             p_i_valid = Array(p_i_valid)
 249             n_i_readyn = Array(n_i_readyn)
 250             data_valid = Array(data_valid)
 251
 252         mid = self.p_mux.m_id
 253         for i in range(p_len):
 254             m.d.comb += data_valid[i].eq(0)
 255             m.d.comb += n_i_readyn[i].eq(1)
 256             m.d.comb += p_i_valid[i].eq(0)
 257             m.d.comb += self.p[i].o_ready.eq(0)
 258         m.d.comb += p_i_valid[mid].eq(self.p_mux.active)
 259         m.d.comb += self.p[mid].o_ready.eq(~data_valid[mid] | self.n.i_ready)
 260         m.d.comb += n_i_readyn[mid].eq(~self.n.i_ready & data_valid[mid])
 261         anyvalid = Signal(i, reset_less=True)
 262         av = []
 263         for i in range(p_len):
 264             av.append(data_valid[i])
 265         anyvalid = Cat(*av)
 266         m.d.comb += self.n.o_valid.eq(anyvalid.bool())
 267         m.d.comb += data_valid[mid].eq(p_i_valid[mid] | \
 268                                     (n_i_readyn[mid] & data_valid[mid]))
 269
 270         for i in range(p_len):
 271             vr = Signal(reset_less=True)
 272             m.d.comb += vr.eq(self.p[i].i_valid & self.p[i].o_ready)
 273             with m.If(vr):
 274                 m.d.comb += eq(r_data[i], self.p[i].i_data)
 275
 276         m.d.comb += eq(self.n.o_data, self.stage.process(r_data[mid]))
 277
 278         return m
 279
 280
 281 class InputPriorityArbiter:
 282     def __init__(self, pipe, num_rows):
 283         self.pipe = pipe
 284         self.num_rows = num_rows
 285         self.mmax = int(log(self.num_rows) / log(2))
 286         self.m_id = Signal(self.mmax, reset_less=True) # multiplex id
 287         self.active = Signal(reset_less=True)
 288
 289     def elaborate(self, platform):
 290         m = Module()
 291
 292         assert len(self.pipe.p) == self.num_rows, \
 293                 "must declare input to be same size"
 294         pe = PriorityEncoder(self.num_rows)
 295         m.submodules.selector = pe
 296
 297         # connect priority encoder
 298         in_ready = []
 299         for i in range(self.num_rows):
 300             p_i_valid = Signal(reset_less=True)
 301             m.d.comb += p_i_valid.eq(self.pipe.p[i].i_valid_logic())
 302             in_ready.append(p_i_valid)
 303         m.d.comb += pe.i.eq(Cat(*in_ready)) # array of input "valids"
 304         m.d.comb += self.active.eq(~pe.n)   # encoder active (one input valid)
 305         m.d.comb += self.m_id.eq(pe.o)       # output one active input
 306
 307         return m
 308
 309     def ports(self):
 310         return [self.m_id, self.active]
 311
 312
 313
 314 class ExamplePipeline(CombMultiInPipeline):
 315     """ an example of how to use the combinatorial pipeline.
 316     """
 317
 318     def __init__(self, p_len=2):
 319         p_mux = InputPriorityArbiter(self, p_len)
 320         CombMultiInPipeline.__init__(self, ExampleStage, p_len, p_mux)
 321
 322
 323 if __name__ == '__main__':
 324
 325     dut = ExamplePipeline()
 326     vl = rtlil.convert(dut, ports=dut.ports())
 327     with open("test_combpipe.il", "w") as f:
 328         f.write(vl)