src/nmutil/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
  13     Stages do not HOLD data, and they definitely do not contain
  14     signalling (ready/valid).  They do however specify the FORMAT
  15     of the incoming and outgoing data, and they provide a means to
  16     PROCESS that data (from incoming format to outgoing format).
  17
  18     Stage Blocks really must be combinatorial blocks.  It would be ok
  19     to have input come in from sync'd sources (clock-driven) however by
  20     doing so they would no longer be deterministic, and chaining such
  21     blocks with such side-effects together could result in unexpected,
  22     unpredictable, unreproduceable behaviour.
  23     So generally to be avoided, then unless you know what you are doing.
  24
  25     the methods of a stage instance must be as follows:
  26
  27     * ispec() - Input data format specification.  Takes a bit of explaining.
  28                 The requirements are: something that eventually derives from
  29                 nmigen Value must be returned *OR* an iterator or iterable
  30                 or sequence (list, tuple etc.) or generator must *yield*
  31                 thing(s) that (eventually) derive from the nmigen Value class.
  32
  33                 Complex to state, very simple in practice:
  34                 see test_buf_pipe.py for over 25 worked examples.
  35
  36     * ospec() - Output data format specification.
  37                 format requirements identical to ispec.
  38
  39     * process(m, i) - Optional function for processing ispec-formatted data.
  40                 returns a combinatorial block of a result that
  41                 may be assigned to the output, by way of the "nmoperator.eq"
  42                 function.  Note that what is returned here can be
  43                 extremely flexible.  Even a dictionary can be returned
  44                 as long as it has fields that match precisely with the
  45                 Record into which its values is intended to be assigned.
  46                 Again: see example unit tests for details.
  47
  48     * setup(m, i) - Optional function for setting up submodules.
  49                 may be used for more complex stages, to link
  50                 the input (i) to submodules.  must take responsibility
  51                 for adding those submodules to the module (m).
  52                 the submodules must be combinatorial blocks and
  53                 must have their inputs and output linked combinatorially.
  54
  55     Both StageCls (for use with non-static classes) and Stage (for use
  56     by static classes) are abstract classes from which, for convenience
  57     and as a courtesy to other developers, anything conforming to the
  58     Stage API may *choose* to derive.  See Liskov Substitution Principle:
  59     https://en.wikipedia.org/wiki/Liskov_substitution_principle
  60
  61     StageChain:
  62     ----------
  63
  64     A useful combinatorial wrapper around stages that chains them together
  65     and then presents a Stage-API-conformant interface.  By presenting
  66     the same API as the stages it wraps, it can clearly be used recursively.
  67
  68     ControlBase:
  69     -----------
  70
  71     The base class for pipelines.  Contains previous and next ready/valid/data.
  72     Also has an extremely useful "connect" function that can be used to
  73     connect a chain of pipelines and present the exact same prev/next
  74     ready/valid/data API.
  75
  76     Note: pipelines basically do not become pipelines as such until
  77     handed to a derivative of ControlBase.  ControlBase itself is *not*
  78     strictly considered a pipeline class.  Wishbone and AXI4 (master or
  79     slave) could be derived from ControlBase, for example.
  80 """
  81
  82 from nmigen import Signal, Cat, Const, Module, Value, Elaboratable
  83 from nmigen.cli import verilog, rtlil
  84 from nmigen.hdl.rec import Record
  85
  86 from collections.abc import Sequence, Iterable
  87 from collections import OrderedDict
  88
  89 from nmutil import nmoperator
  90
  91
  92 class Object:
  93     def __init__(self):
  94         self.fields = OrderedDict()
  95
  96     def __setattr__(self, k, v):
  97         print ("kv", k, v)
  98         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
  99            k in dir(Object) or "fields" not in self.__dict__):
 100             return object.__setattr__(self, k, v)
 101         self.fields[k] = v
 102
 103     def __getattr__(self, k):
 104         if k in self.__dict__:
 105             return object.__getattr__(self, k)
 106         try:
 107             return self.fields[k]
 108         except KeyError as e:
 109             raise AttributeError(e)
 110
 111     def __iter__(self):
 112         for x in self.fields.values():  # OrderedDict so order is preserved
 113             if isinstance(x, Iterable):
 114                 yield from x
 115             else:
 116                 yield x
 117
 118     def eq(self, inp):
 119         res = []
 120         for (k, o) in self.fields.items():
 121             i = getattr(inp, k)
 122             print ("eq", o, i)
 123             rres = o.eq(i)
 124             if isinstance(rres, Sequence):
 125                 res += rres
 126             else:
 127                 res.append(rres)
 128         print (res)
 129         return res
 130
 131     def ports(self): # being called "keys" would be much better
 132         return list(self)
 133
 134
 135 class RecordObject(Record):
 136     def __init__(self, layout=None, name=None):
 137         Record.__init__(self, layout=layout or [], name=name)
 138
 139     def __setattr__(self, k, v):
 140         #print (dir(Record))
 141         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
 142            k in dir(Record) or "fields" not in self.__dict__):
 143             return object.__setattr__(self, k, v)
 144         self.fields[k] = v
 145         #print ("RecordObject setattr", k, v)
 146         if isinstance(v, Record):
 147             newlayout = {k: (k, v.layout)}
 148         elif isinstance(v, Value):
 149             newlayout = {k: (k, v.shape())}
 150         else:
 151             newlayout = {k: (k, nmoperator.shape(v))}
 152         self.layout.fields.update(newlayout)
 153
 154     def __iter__(self):
 155         for x in self.fields.values(): # remember: fields is an OrderedDict
 156             if isinstance(x, Iterable):
 157                 yield from x           # a bit like flatten (nmigen.tools)
 158             else:
 159                 yield x
 160
 161     def ports(self): # would be better being called "keys"
 162         return list(self)
 163
 164
 165 class PrevControl(Elaboratable):
 166     """ contains signals that come *from* the previous stage (both in and out)
 167         * valid_i: previous stage indicating all incoming data is valid.
 168                    may be a multi-bit signal, where all bits are required
 169                    to be asserted to indicate "valid".
 170         * ready_o: output to next stage indicating readiness to accept data
 171         * data_i : an input - MUST be added by the USER of this class
 172     """
 173
 174     def __init__(self, i_width=1, stage_ctl=False, maskwid=0):
 175         self.stage_ctl = stage_ctl
 176         self.maskwid = maskwid
 177         if maskwid:
 178             self.mask_i = Signal(maskwid)                # prev   >>in  self
 179         self.valid_i = Signal(i_width, name="p_valid_i") # prev   >>in  self
 180         self._ready_o = Signal(name="p_ready_o")         # prev   <<out self
 181         self.data_i = None # XXX MUST BE ADDED BY USER
 182         if stage_ctl:
 183             self.s_ready_o = Signal(name="p_s_o_rdy")    # prev   <<out self
 184         self.trigger = Signal(reset_less=True)
 185
 186     @property
 187     def ready_o(self):
 188         """ public-facing API: indicates (externally) that stage is ready
 189         """
 190         if self.stage_ctl:
 191             return self.s_ready_o # set dynamically by stage
 192         return self._ready_o      # return this when not under dynamic control
 193
 194     def _connect_in(self, prev, direct=False, fn=None, do_data=True):
 195         """ internal helper function to connect stage to an input source.
 196             do not use to connect stage-to-stage!
 197         """
 198         valid_i = prev.valid_i if direct else prev.valid_i_test
 199         res = [self.valid_i.eq(valid_i),
 200                prev.ready_o.eq(self.ready_o)]
 201         if self.maskwid:
 202             res.append(self.mask_i.eq(prev.mask_i))
 203         if do_data is False:
 204             return res
 205         data_i = fn(prev.data_i) if fn is not None else prev.data_i
 206         return res + [nmoperator.eq(self.data_i, data_i)]
 207
 208     @property
 209     def valid_i_test(self):
 210         vlen = len(self.valid_i)
 211         if vlen > 1:
 212             # multi-bit case: valid only when valid_i is all 1s
 213             all1s = Const(-1, (len(self.valid_i), False))
 214             valid_i = (self.valid_i == all1s)
 215         else:
 216             # single-bit valid_i case
 217             valid_i = self.valid_i
 218
 219         # when stage indicates not ready, incoming data
 220         # must "appear" to be not ready too
 221         if self.stage_ctl:
 222             valid_i = valid_i & self.s_ready_o
 223
 224         return valid_i
 225
 226     def elaborate(self, platform):
 227         m = Module()
 228         m.d.comb += self.trigger.eq(self.valid_i_test & self.ready_o)
 229         return m
 230
 231     def eq(self, i):
 232         res = [nmoperator.eq(self.data_i, i.data_i),
 233                 self.ready_o.eq(i.ready_o),
 234                 self.valid_i.eq(i.valid_i)]
 235         if self.maskwid:
 236             res.append(self.mask_i.eq(i.mask_i))
 237         return res
 238
 239     def __iter__(self):
 240         yield self.valid_i
 241         yield self.ready_o
 242         if self.maskwid:
 243             yield self.mask_i
 244         if hasattr(self.data_i, "ports"):
 245             yield from self.data_i.ports()
 246         elif isinstance(self.data_i, Sequence):
 247             yield from self.data_i
 248         else:
 249             yield self.data_i
 250
 251     def ports(self):
 252         return list(self)
 253
 254
 255 class NextControl(Elaboratable):
 256     """ contains the signals that go *to* the next stage (both in and out)
 257         * valid_o: output indicating to next stage that data is valid
 258         * ready_i: input from next stage indicating that it can accept data
 259         * data_o : an output - MUST be added by the USER of this class
 260     """
 261     def __init__(self, stage_ctl=False):
 262         self.stage_ctl = stage_ctl
 263         self.valid_o = Signal(name="n_valid_o") # self out>>  next
 264         self.ready_i = Signal(name="n_ready_i") # self <<in   next
 265         self.data_o = None # XXX MUST BE ADDED BY USER
 266         #if self.stage_ctl:
 267         self.d_valid = Signal(reset=1) # INTERNAL (data valid)
 268         self.trigger = Signal(reset_less=True)
 269
 270     @property
 271     def ready_i_test(self):
 272         if self.stage_ctl:
 273             return self.ready_i & self.d_valid
 274         return self.ready_i
 275
 276     def connect_to_next(self, nxt, do_data=True):
 277         """ helper function to connect to the next stage data/valid/ready.
 278             data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
 279             use this when connecting stage-to-stage
 280         """
 281         res = [nxt.valid_i.eq(self.valid_o),
 282                self.ready_i.eq(nxt.ready_o)]
 283         if do_data:
 284             res.append(nmoperator.eq(nxt.data_i, self.data_o))
 285         return res
 286
 287     def _connect_out(self, nxt, direct=False, fn=None, do_data=True):
 288         """ internal helper function to connect stage to an output source.
 289             do not use to connect stage-to-stage!
 290         """
 291         ready_i = nxt.ready_i if direct else nxt.ready_i_test
 292         res = [nxt.valid_o.eq(self.valid_o),
 293                self.ready_i.eq(ready_i)]
 294         if not do_data:
 295             return res
 296         data_o = fn(nxt.data_o) if fn is not None else nxt.data_o
 297         return res + [nmoperator.eq(data_o, self.data_o)]
 298
 299     def elaborate(self, platform):
 300         m = Module()
 301         m.d.comb += self.trigger.eq(self.ready_i_test & self.valid_o)
 302         return m
 303
 304     def __iter__(self):
 305         yield self.ready_i
 306         yield self.valid_o
 307         if hasattr(self.data_o, "ports"):
 308             yield from self.data_o.ports()
 309         elif isinstance(self.data_o, Sequence):
 310             yield from self.data_o
 311         else:
 312             yield self.data_o
 313
 314     def ports(self):
 315         return list(self)
 316