src/nmutil/iocontrol.py

   1 """ IO Control API
   2
   3     This work is funded through NLnet under Grant 2019-02-012
   4
   5     License: LGPLv3+
   6
   7
   8     Associated development bugs:
   9     * http://bugs.libre-riscv.org/show_bug.cgi?id=538
  10     * http://bugs.libre-riscv.org/show_bug.cgi?id=148
  11     * http://bugs.libre-riscv.org/show_bug.cgi?id=64
  12     * http://bugs.libre-riscv.org/show_bug.cgi?id=57
  13
  14     Important: see Stage API (stageapi.py) in combination with below
  15
  16     Main classes: PrevControl and NextControl.
  17
  18     These classes manage the data and the synchronisation state
  19     to the previous and next stage, respectively.  ready/valid
  20     signals are used by the Pipeline classes to tell if data
  21     may be safely passed from stage to stage.
  22
  23     The connection from one stage to the next is carried out with
  24     NextControl.connect_to_next.  It is *not* necessary to have
  25     a PrevControl.connect_to_prev because it is functionally
  26     directly equivalent to prev->next->connect_to_next.
  27 """
  28
  29 from nmigen import Signal, Cat, Const, Module, Value, Elaboratable
  30 from nmigen.cli import verilog, rtlil
  31 from nmigen.hdl.rec import Record
  32 from nmigen import tracer
  33
  34 from collections.abc import Sequence, Iterable
  35 from collections import OrderedDict
  36
  37 from nmutil import nmoperator
  38
  39
  40 class Object:
  41     def __init__(self):
  42         self.fields = OrderedDict()
  43
  44     def __setattr__(self, k, v):
  45         print ("kv", k, v)
  46         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
  47            k in dir(Object) or "fields" not in self.__dict__):
  48             return object.__setattr__(self, k, v)
  49         self.fields[k] = v
  50
  51     def __getattr__(self, k):
  52         if k in self.__dict__:
  53             return object.__getattr__(self, k)
  54         try:
  55             return self.fields[k]
  56         except KeyError as e:
  57             raise AttributeError(e)
  58
  59     def __iter__(self):
  60         for x in self.fields.values():  # OrderedDict so order is preserved
  61             if isinstance(x, Iterable):
  62                 yield from x
  63             else:
  64                 yield x
  65
  66     def eq(self, inp):
  67         res = []
  68         for (k, o) in self.fields.items():
  69             i = getattr(inp, k)
  70             print ("eq", o, i)
  71             rres = o.eq(i)
  72             if isinstance(rres, Sequence):
  73                 res += rres
  74             else:
  75                 res.append(rres)
  76         print (res)
  77         return res
  78
  79     def ports(self): # being called "keys" would be much better
  80         return list(self)
  81
  82
  83 def add_prefix_to_record_signals(prefix, record):
  84     """recursively hunt through Records, modifying names to add a prefix
  85     """
  86     for key, val in record.fields.items():
  87         if isinstance(val, Signal):
  88             val.name = prefix + val.name
  89         elif isinstance(val, Record):
  90             add_prefix_to_record_signals(prefix, val)
  91
  92
  93 class RecordObject(Record):
  94     def __init__(self, layout=None, name=None):
  95         #if name is None:
  96         #    name = tracer.get_var_name(depth=2, default="$ro")
  97         Record.__init__(self, layout=layout or [], name=name)
  98
  99
 100     def __setattr__(self, k, v):
 101         #print(f"RecordObject setattr({k}, {v})")
 102         #print (dir(Record))
 103         if (k.startswith('_') or k in ["fields", "name", "src_loc"] or
 104            k in dir(Record) or "fields" not in self.__dict__):
 105             return object.__setattr__(self, k, v)
 106
 107         if self.name is None:
 108             prefix = ""
 109         else:
 110             prefix = self.name + "_"
 111         # Prefix the signal name with the name of the recordobject
 112         if isinstance(v, Signal):
 113             #print (self, self.name, v.name)
 114             v.name = prefix + v.name
 115         elif isinstance(v, Record):
 116             add_prefix_to_record_signals(prefix, v)
 117
 118         self.fields[k] = v
 119         #print ("RecordObject setattr", k, v)
 120         if isinstance(v, Record):
 121             newlayout = {k: (k, v.layout)}
 122         elif isinstance(v, Value):
 123             newlayout = {k: (k, v.shape())}
 124         else:
 125             newlayout = {k: (k, nmoperator.shape(v))}
 126         self.layout.fields.update(newlayout)
 127
 128     def __iter__(self):
 129         for x in self.fields.values(): # remember: fields is an OrderedDict
 130             if hasattr(x, 'ports'):
 131                 yield from x.ports()
 132             elif isinstance(x, Record):
 133                 for f in x.fields.values():
 134                     yield f
 135             elif isinstance(x, Iterable):
 136                 yield from x           # a bit like flatten (nmigen.tools)
 137             else:
 138                 yield x
 139
 140     def ports(self): # would be better being called "keys"
 141         return list(self)
 142
 143
 144 class PrevControl(Elaboratable):
 145     """ contains signals that come *from* the previous stage (both in and out)
 146         * i_valid: previous stage indicating all incoming data is valid.
 147                    may be a multi-bit signal, where all bits are required
 148                    to be asserted to indicate "valid".
 149         * o_ready: output to next stage indicating readiness to accept data
 150         * i_data : an input - MUST be added by the USER of this class
 151     """
 152
 153     def __init__(self, i_width=1, stage_ctl=False, maskwid=0, offs=0,
 154                        name=None):
 155         if name is None:
 156             name = ""
 157         n_piv = "p_i_valid"+name
 158         n_por = "p_o_ready"+name
 159
 160         self.stage_ctl = stage_ctl
 161         self.maskwid = maskwid
 162         if maskwid:
 163             self.mask_i = Signal(maskwid)              # prev   >>in  self
 164             self.stop_i = Signal(maskwid)              # prev   >>in  self
 165         self.i_valid = Signal(i_width, name=n_piv)     # prev   >>in  self
 166         self._o_ready = Signal(name=n_por)             # prev   <<out self
 167         self.i_data = None # XXX MUST BE ADDED BY USER
 168         if stage_ctl:
 169             self.s_o_ready = Signal(name="p_s_o_rdy")    # prev   <<out self
 170         self.trigger = Signal(reset_less=True)
 171
 172     @property
 173     def o_ready(self):
 174         """ public-facing API: indicates (externally) that stage is ready
 175         """
 176         if self.stage_ctl:
 177             return self.s_o_ready # set dynamically by stage
 178         return self._o_ready      # return this when not under dynamic control
 179
 180     def _connect_in(self, prev, direct=False, fn=None,
 181                     do_data=True, do_stop=True):
 182         """ internal helper function to connect stage to an input source.
 183             do not use to connect stage-to-stage!
 184         """
 185         i_valid = prev.i_valid if direct else prev.i_valid_test
 186         res = [self.i_valid.eq(i_valid),
 187                prev.o_ready.eq(self.o_ready)]
 188         if self.maskwid:
 189             res.append(self.mask_i.eq(prev.mask_i))
 190             if do_stop:
 191                 res.append(self.stop_i.eq(prev.stop_i))
 192         if do_data is False:
 193             return res
 194         i_data = fn(prev.i_data) if fn is not None else prev.i_data
 195         return res + [nmoperator.eq(self.i_data, i_data)]
 196
 197     @property
 198     def i_valid_test(self):
 199         vlen = len(self.i_valid)
 200         if vlen > 1:
 201             # multi-bit case: valid only when i_valid is all 1s
 202             all1s = Const(-1, (len(self.i_valid), False))
 203             i_valid = (self.i_valid == all1s)
 204         else:
 205             # single-bit i_valid case
 206             i_valid = self.i_valid
 207
 208         # when stage indicates not ready, incoming data
 209         # must "appear" to be not ready too
 210         if self.stage_ctl:
 211             i_valid = i_valid & self.s_o_ready
 212
 213         return i_valid
 214
 215     def elaborate(self, platform):
 216         m = Module()
 217         m.d.comb += self.trigger.eq(self.i_valid_test & self.o_ready)
 218         return m
 219
 220     def eq(self, i):
 221         res = [nmoperator.eq(self.i_data, i.i_data),
 222                 self.o_ready.eq(i.o_ready),
 223                 self.i_valid.eq(i.i_valid)]
 224         if self.maskwid:
 225             res.append(self.mask_i.eq(i.mask_i))
 226         return res
 227
 228     def __iter__(self):
 229         yield self.i_valid
 230         yield self.o_ready
 231         if self.maskwid:
 232             yield self.mask_i
 233             yield self.stop_i
 234         if hasattr(self.i_data, "ports"):
 235             yield from self.i_data.ports()
 236         elif (isinstance(self.i_data, Sequence) or
 237               isinstance(self.i_data, Iterable)):
 238             yield from self.i_data
 239         else:
 240             yield self.i_data
 241
 242     def ports(self):
 243         return list(self)
 244
 245
 246 class NextControl(Elaboratable):
 247     """ contains the signals that go *to* the next stage (both in and out)
 248         * o_valid: output indicating to next stage that data is valid
 249         * i_ready: input from next stage indicating that it can accept data
 250         * o_data : an output - MUST be added by the USER of this class
 251     """
 252     def __init__(self, stage_ctl=False, maskwid=0, name=None):
 253         if name is None:
 254             name = ""
 255         n_nov = "n_o_valid"+name
 256         n_nir = "n_i_ready"+name
 257
 258         self.stage_ctl = stage_ctl
 259         self.maskwid = maskwid
 260         if maskwid:
 261             self.mask_o = Signal(maskwid) # self out>>  next
 262             self.stop_o = Signal(maskwid) # self out>>  next
 263         self.o_valid = Signal(name=n_nov) # self out>>  next
 264         self.i_ready = Signal(name=n_nir) # self <<in   next
 265         self.o_data = 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 i_ready_test(self):
 272         if self.stage_ctl:
 273             return self.i_ready & self.d_valid
 274         return self.i_ready
 275
 276     def connect_to_next(self, nxt, do_data=True, do_stop=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             note: a "connect_from_prev" is completely unnecessary: it's
 282             just nxt.connect_to_next(self)
 283         """
 284         res = [nxt.i_valid.eq(self.o_valid),
 285                self.i_ready.eq(nxt.o_ready)]
 286         if self.maskwid:
 287             res.append(nxt.mask_i.eq(self.mask_o))
 288             if do_stop:
 289                 res.append(nxt.stop_i.eq(self.stop_o))
 290         if do_data:
 291             res.append(nmoperator.eq(nxt.i_data, self.o_data))
 292         print ("connect to next", self, self.maskwid, nxt.i_data,
 293                                   do_data, do_stop)
 294         return res
 295
 296     def _connect_out(self, nxt, direct=False, fn=None,
 297                      do_data=True, do_stop=True):
 298         """ internal helper function to connect stage to an output source.
 299             do not use to connect stage-to-stage!
 300         """
 301         i_ready = nxt.i_ready if direct else nxt.i_ready_test
 302         res = [nxt.o_valid.eq(self.o_valid),
 303                self.i_ready.eq(i_ready)]
 304         if self.maskwid:
 305             res.append(nxt.mask_o.eq(self.mask_o))
 306             if do_stop:
 307                 res.append(nxt.stop_o.eq(self.stop_o))
 308         if not do_data:
 309             return res
 310         o_data = fn(nxt.o_data) if fn is not None else nxt.o_data
 311         return res + [nmoperator.eq(o_data, self.o_data)]
 312
 313     def elaborate(self, platform):
 314         m = Module()
 315         m.d.comb += self.trigger.eq(self.i_ready_test & self.o_valid)
 316         return m
 317
 318     def __iter__(self):
 319         yield self.i_ready
 320         yield self.o_valid
 321         if self.maskwid:
 322             yield self.mask_o
 323             yield self.stop_o
 324         if hasattr(self.o_data, "ports"):
 325             yield from self.o_data.ports()
 326         elif (isinstance(self.o_data, Sequence) or
 327               isinstance(self.o_data, Iterable)):
 328             yield from self.o_data
 329         else:
 330             yield self.o_data
 331
 332     def ports(self):
 333         return list(self)
 334