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
  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 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=None)
 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):
 175         self.stage_ctl = stage_ctl
 176         self.valid_i = Signal(i_width, name="p_valid_i") # prev   >>in  self
 177         self._ready_o = Signal(name="p_ready_o")         # prev   <<out self
 178         self.data_i = None # XXX MUST BE ADDED BY USER
 179         if stage_ctl:
 180             self.s_ready_o = Signal(name="p_s_o_rdy")    # prev   <<out self
 181         self.trigger = Signal(reset_less=True)
 182
 183     @property
 184     def ready_o(self):
 185         """ public-facing API: indicates (externally) that stage is ready
 186         """
 187         if self.stage_ctl:
 188             return self.s_ready_o # set dynamically by stage
 189         return self._ready_o      # return this when not under dynamic control
 190
 191     def _connect_in(self, prev, direct=False, fn=None):
 192         """ internal helper function to connect stage to an input source.
 193             do not use to connect stage-to-stage!
 194         """
 195         valid_i = prev.valid_i if direct else prev.valid_i_test
 196         data_i = fn(prev.data_i) if fn is not None else prev.data_i
 197         return [self.valid_i.eq(valid_i),
 198                 prev.ready_o.eq(self.ready_o),
 199                 nmoperator.eq(self.data_i, data_i),
 200                ]
 201
 202     @property
 203     def valid_i_test(self):
 204         vlen = len(self.valid_i)
 205         if vlen > 1:
 206             # multi-bit case: valid only when valid_i is all 1s
 207             all1s = Const(-1, (len(self.valid_i), False))
 208             valid_i = (self.valid_i == all1s)
 209         else:
 210             # single-bit valid_i case
 211             valid_i = self.valid_i
 212
 213         # when stage indicates not ready, incoming data
 214         # must "appear" to be not ready too
 215         if self.stage_ctl:
 216             valid_i = valid_i & self.s_ready_o
 217
 218         return valid_i
 219
 220     def elaborate(self, platform):
 221         m = Module()
 222         m.d.comb += self.trigger.eq(self.valid_i_test & self.ready_o)
 223         return m
 224
 225     def eq(self, i):
 226         return [self.data_i.eq(i.data_i),
 227                 self.ready_o.eq(i.ready_o),
 228                 self.valid_i.eq(i.valid_i)]
 229
 230     def __iter__(self):
 231         yield self.valid_i
 232         yield self.ready_o
 233         if hasattr(self.data_i, "ports"):
 234             yield from self.data_i.ports()
 235         elif isinstance(self.data_i, Sequence):
 236             yield from self.data_i
 237         else:
 238             yield self.data_i
 239
 240     def ports(self):
 241         return list(self)
 242
 243
 244 class NextControl(Elaboratable):
 245     """ contains the signals that go *to* the next stage (both in and out)
 246         * valid_o: output indicating to next stage that data is valid
 247         * ready_i: input from next stage indicating that it can accept data
 248         * data_o : an output - MUST be added by the USER of this class
 249     """
 250     def __init__(self, stage_ctl=False):
 251         self.stage_ctl = stage_ctl
 252         self.valid_o = Signal(name="n_valid_o") # self out>>  next
 253         self.ready_i = Signal(name="n_ready_i") # self <<in   next
 254         self.data_o = None # XXX MUST BE ADDED BY USER
 255         #if self.stage_ctl:
 256         self.d_valid = Signal(reset=1) # INTERNAL (data valid)
 257         self.trigger = Signal(reset_less=True)
 258
 259     @property
 260     def ready_i_test(self):
 261         if self.stage_ctl:
 262             return self.ready_i & self.d_valid
 263         return self.ready_i
 264
 265     def connect_to_next(self, nxt, do_data=True):
 266         """ helper function to connect to the next stage data/valid/ready.
 267             data/valid is passed *TO* nxt, and ready comes *IN* from nxt.
 268             use this when connecting stage-to-stage
 269         """
 270         res = [nxt.valid_i.eq(self.valid_o),
 271                self.ready_i.eq(nxt.ready_o)]
 272         if do_data:
 273             res.append(nmoperator.eq(nxt.data_i, self.data_o))
 274         return res
 275
 276     def _connect_out(self, nxt, direct=False, fn=None, do_data=True):
 277         """ internal helper function to connect stage to an output source.
 278             do not use to connect stage-to-stage!
 279         """
 280         ready_i = nxt.ready_i if direct else nxt.ready_i_test
 281         res = [nxt.valid_o.eq(self.valid_o),
 282                self.ready_i.eq(ready_i)]
 283         if not do_data:
 284             return res
 285         data_o = fn(nxt.data_o) if fn is not None else nxt.data_o
 286         return res + [nmoperator.eq(data_o, self.data_o)]
 287
 288     def elaborate(self, platform):
 289         m = Module()
 290         m.d.comb += self.trigger.eq(self.ready_i_test & self.valid_o)
 291         return m
 292
 293     def __iter__(self):
 294         yield self.ready_i
 295         yield self.valid_o
 296         if hasattr(self.data_o, "ports"):
 297             yield from self.data_o.ports()
 298         elif isinstance(self.data_o, Sequence):
 299             yield from self.data_o
 300         else:
 301             yield self.data_o
 302
 303     def ports(self):
 304         return list(self)
 305