src/soc/experiment/l0_cache.py

   1 """L0 Cache/Buffer
   2
   3 This first version is intended for prototyping and test purposes:
   4 it has "direct" access to Memory.
   5
   6 The intention is that this version remains an integral part of the
   7 test infrastructure, and, just as with minerva's memory arrangement,
   8 a dynamic runtime config *selects* alternative memory arrangements
   9 rather than *replaces and discards* this code.
  10
  11 Links:
  12
  13 * https://bugs.libre-soc.org/show_bug.cgi?id=216
  14 * https://libre-soc.org/3d_gpu/architecture/memory_and_cache/
  15
  16 """
  17
  18 from nmigen.compat.sim import run_simulation
  19 from nmigen.cli import verilog, rtlil
  20 from nmigen import Module, Signal, Mux, Elaboratable, Array, Cat
  21 from nmutil.iocontrol import RecordObject
  22 from nmigen.utils import log2_int
  23 from nmigen.hdl.rec import Record, Layout
  24
  25 from nmutil.latch import SRLatch, latchregister
  26 from soc.decoder.power_decoder2 import Data
  27 from soc.decoder.power_enums import InternalOp
  28
  29 from soc.experiment.compldst import CompLDSTOpSubset
  30 from soc.decoder.power_decoder2 import Data
  31 #from nmutil.picker import PriorityPicker
  32 from nmigen.lib.coding import PriorityEncoder
  33
  34 # for testing purposes
  35 from soc.experiment.testmem import TestMemory
  36
  37
  38 class PortInterface(RecordObject):
  39     """PortInterface
  40
  41     defines the interface - the API - that the LDSTCompUnit connects
  42     to.  note that this is NOT a "fire-and-forget" interface.  the
  43     LDSTCompUnit *must* be kept appraised that the request is in
  44     progress, and only when it has a 100% successful completion rate
  45     can the notification be given (busy dropped).
  46
  47     The interface FSM rules are as follows:
  48
  49     * if busy_o is asserted, a LD/ST is in progress.  further
  50       requests may not be made until busy_o is deasserted.
  51
  52     * only one of is_ld_i or is_st_i may be asserted.  busy_o
  53       will immediately be asserted and remain asserted.
  54
  55     * addr.ok is to be asserted when the LD/ST address is known.
  56       addr.data is to be valid on the same cycle.
  57
  58       addr.ok and addr.data must REMAIN asserted until busy_o
  59       is de-asserted.  this ensures that there is no need
  60       for the L0 Cache/Buffer to have an additional address latch
  61       (because the LDSTCompUnit already has it)
  62
  63     * addr_ok_o (or addr_exc_o) must be waited for.  these will
  64       be asserted *only* for one cycle and one cycle only.
  65
  66     * addr_exc_o will be asserted if there is no chance that the
  67       memory request may be fulfilled.
  68
  69       busy_o is deasserted on the same cycle as addr_exc_o is asserted.
  70
  71     * conversely: addr_ok_o must *ONLY* be asserted if there is a
  72       HUNDRED PERCENT guarantee that the memory request will be
  73       fulfilled.
  74
  75     * for a LD, ld.ok will be asserted - for only one clock cycle -
  76       at any point in the future that is acceptable to the underlying
  77       Memory subsystem.  the recipient MUST latch ld.data on that cycle.
  78
  79       busy_o is deasserted on the same cycle as ld.ok is asserted.
  80
  81     * for a ST, st.ok may be asserted only after addr_ok_o had been
  82       asserted, alongside valid st.data at the same time.  st.ok
  83       must only be asserted for one cycle.
  84
  85       the underlying Memory is REQUIRED to pick up that data and
  86       guarantee its delivery.  no back-acknowledgement is required.
  87
  88       busy_o is deasserted on the cycle AFTER st.ok is asserted.
  89     """
  90
  91     def __init__(self, name=None, regwid=64, addrwid=48):
  92
  93         self._regwid = regwid
  94         self._addrwid = addrwid
  95
  96         RecordObject.__init__(self, name=name)
  97
  98         # distinguish op type (ld/st)
  99         self.is_ld_i = Signal(reset_less=True)
 100         self.is_st_i = Signal(reset_less=True)
 101         self.op = CompLDSTOpSubset()  # hm insn_type ld/st duplicates here
 102
 103         # common signals
 104         self.busy_o = Signal(reset_less=True)     # do not use if busy
 105         self.go_die_i = Signal(reset_less=True)   # back to reset
 106         self.addr = Data(addrwid, "addr_i")            # addr/addr-ok
 107         # addr is valid (TLB, L1 etc.)
 108         self.addr_ok_o = Signal(reset_less=True)
 109         self.addr_exc_o = Signal(reset_less=True)  # TODO, "type" of exception
 110
 111         # LD/ST
 112         self.ld = Data(regwid, "ld_data_o")  # ok to be set by L0 Cache/Buf
 113         self.st = Data(regwid, "st_data_i")  # ok to be set by CompUnit
 114
 115 # TODO:
 116
 117
 118 class DualPortSplitter(Elaboratable):
 119     """DualPortSplitter
 120
 121     * one incoming PortInterface
 122     * two *OUTGOING* PortInterfaces
 123     * uses LDSTSplitter to do it
 124
 125     (actually, thinking about it LDSTSplitter could simply be
 126      modified to conform to PortInterface: one in, two out)
 127
 128     once that is done each pair of ports may be wired directly
 129     to the dual ports of L0CacheBuffer
 130     """
 131     pass
 132
 133
 134 class DataMergerRecord(Record):
 135     """
 136     {data: 128 bit, byte_enable: 16 bit}
 137     """
 138
 139     def __init__(self, name=None):
 140         layout = (('data', 128),
 141                   ('byte_enable', 16)
 142                   )
 143
 144         Record.__init__(self, Layout(layout), name=name)
 145
 146 # TODO:
 147
 148
 149 class DataMerger(Elaboratable):
 150     """DataMerger
 151
 152     Merges data based on an address-match matrix
 153
 154     """
 155
 156     def __init__(self, array_size):
 157         """
 158         :addr_array_i: an NxN Array of
 159                        Signals with bits set indicating address match
 160         :data_i: an Nx Array of Records {data: 128 bit, byte_enable: 16 bit}
 161         :data_o: an Output Record of same type
 162                  {data: 128 bit, byte_enable: 16 bit}
 163         """
 164         self.array_size = array_size
 165         ul = []
 166         for i in range(0, array_size):
 167             ul2 = []
 168             for j in range(0, array_size):
 169                 ul2.append(Signal())
 170             ul.append(ul2)
 171         self.addr_array_i = Array(ul)
 172
 173         ul = []
 174         for i in range(0, array_size):
 175             ul.append(DataMergerRecord())
 176         self.data_i = Array(ul)
 177         self.data_o = DataMergerRecord()
 178
 179
 180 class LDSTPort(Elaboratable):
 181     def __init__(self, idx, regwid=64, addrwid=48):
 182         self.pi = PortInterface("ldst_port%d" % idx, regwid, addrwid)
 183
 184     def elaborate(self, platform):
 185         m = Module()
 186         comb, sync = m.d.comb, m.d.sync
 187
 188         # latches
 189         m.submodules.busy_l = busy_l = SRLatch(False, name="busy")
 190         m.submodules.cyc_l = cyc_l = SRLatch(True, name="cyc")
 191         comb += cyc_l.s.eq(0)
 192         comb += cyc_l.r.eq(0)
 193
 194         # this is a little weird: we let the L0Cache/Buffer set
 195         # the outputs: this module just monitors "state".
 196
 197         # LD/ST requested activates "busy"
 198         with m.If(self.pi.is_ld_i | self.pi.is_st_i):
 199             comb += busy_l.s.eq(1)
 200
 201         # monitor for an exception or the completion of LD.
 202         with m.If(self.pi.addr_exc_o):
 203             comb += busy_l.r.eq(1)
 204
 205         # however ST needs one cycle before busy is reset
 206         with m.If(self.pi.st.ok | self.pi.ld.ok):
 207             comb += cyc_l.s.eq(1)
 208
 209         with m.If(cyc_l.q):
 210             comb += cyc_l.r.eq(1)
 211             comb += busy_l.r.eq(1)
 212
 213         # busy latch outputs to interface
 214         comb += self.pi.busy_o.eq(busy_l.q)
 215
 216         return m
 217
 218     def __iter__(self):
 219         yield self.pi.is_ld_i
 220         yield self.pi.is_st_i
 221         yield from self.pi.op.ports()
 222         yield self.pi.busy_o
 223         yield self.pi.go_die_i
 224         yield from self.pi.addr.ports()
 225         yield self.pi.addr_ok_o
 226         yield self.pi.addr_exc_o
 227
 228         yield from self.pi.ld.ports()
 229         yield from self.pi.st.ports()
 230
 231     def ports(self):
 232         return list(self)
 233
 234
 235 class L0CacheBuffer(Elaboratable):
 236     """L0 Cache / Buffer
 237
 238     Note that the final version will have *two* interfaces per LDSTCompUnit,
 239     to cover mis-aligned requests, as well as *two* 128-bit L1 Cache
 240     interfaces: one for odd (addr[4] == 1) and one for even (addr[4] == 1).
 241
 242     This version is to be used for test purposes (and actively maintained
 243     for such, rather than "replaced")
 244
 245     There are much better ways to implement this.  However it's only
 246     a "demo" / "test" class, and one important aspect: it responds
 247     combinatorially, where a nmigen FSM's state-changes only activate
 248     on clock-sync boundaries.
 249     """
 250
 251     def __init__(self, n_units, mem, regwid=64, addrwid=48):
 252         self.n_units = n_units
 253         self.mem = mem
 254         ul = []
 255         for i in range(n_units):
 256             ul.append(LDSTPort(i, regwid, addrwid))
 257         self.dports = Array(ul)
 258
 259     def elaborate(self, platform):
 260         m = Module()
 261         comb, sync = m.d.comb, m.d.sync
 262
 263         # connect the ports as modules
 264         for i in range(self.n_units):
 265             setattr(m.submodules, "port%d" % i, self.dports[i])
 266
 267         # state-machine latches
 268         m.submodules.st_active = st_active = SRLatch(False, name="st_active")
 269         m.submodules.ld_active = ld_active = SRLatch(False, name="ld_active")
 270         m.submodules.reset_l = reset_l = SRLatch(True, name="reset")
 271         m.submodules.idx_l = idx_l = SRLatch(False, name="idx_l")
 272         m.submodules.adrok_l = adrok_l = SRLatch(False, name="addr_acked")
 273
 274         # find one LD (or ST) and do it.  only one per cycle.
 275         # TODO: in the "live" (production) L0Cache/Buffer, merge multiple
 276         # LD/STs using mask-expansion - see LenExpand class
 277
 278         m.submodules.ldpick = ldpick = PriorityEncoder(self.n_units)
 279         m.submodules.stpick = stpick = PriorityEncoder(self.n_units)
 280
 281         lds = Signal(self.n_units, reset_less=True)
 282         sts = Signal(self.n_units, reset_less=True)
 283         ldi = []
 284         sti = []
 285         for i in range(self.n_units):
 286             pi = self.dports[i].pi
 287             ldi.append(pi.is_ld_i & pi.busy_o)  # accumulate ld-req signals
 288             sti.append(pi.is_st_i & pi.busy_o)  # accumulate st-req signals
 289         # put the requests into the priority-pickers
 290         comb += ldpick.i.eq(Cat(*ldi))
 291         comb += stpick.i.eq(Cat(*sti))
 292
 293         # hmm, have to select (record) the right port index
 294         nbits = log2_int(self.n_units, False)
 295         ld_idx = Signal(nbits, reset_less=False)
 296         st_idx = Signal(nbits, reset_less=False)
 297         # use these because of the sync-and-comb pass-through capability
 298         latchregister(m, ldpick.o, ld_idx, idx_l.qn, name="ld_idx_l")
 299         latchregister(m, stpick.o, st_idx, idx_l.qn, name="st_idx_l")
 300
 301         # convenience variables to reference the "picked" port
 302         ldport = self.dports[ld_idx].pi
 303         stport = self.dports[st_idx].pi
 304         # and the memory ports
 305         rdport = self.mem.rdport
 306         wrport = self.mem.wrport
 307
 308         # Priority-Pickers pick one and only one request, capture its index.
 309         # from that point on this code *only* "listens" to that port.
 310
 311         sync += adrok_l.s.eq(0)
 312         comb += adrok_l.r.eq(0)
 313         with m.If(~ldpick.n):
 314             comb += ld_active.s.eq(1)  # activate LD mode
 315             comb += idx_l.r.eq(1)  # pick (and capture) the port index
 316         with m.Elif(~stpick.n):
 317             comb += st_active.s.eq(1)  # activate ST mode
 318             comb += idx_l.r.eq(1)  # pick (and capture) the port index
 319
 320         # from this point onwards, with the port "picked", it stays picked
 321         # until ld_active (or st_active) are de-asserted.
 322
 323         # if now in "LD" mode: wait for addr_ok, then send the address out
 324         # to memory, acknowledge address, and send out LD data
 325         with m.If(ld_active.q):
 326             with m.If(ldport.addr.ok & adrok_l.qn):
 327                 comb += rdport.addr.eq(ldport.addr.data)  # addr ok, send thru
 328                 comb += ldport.addr_ok_o.eq(1)  # acknowledge addr ok
 329                 sync += adrok_l.s.eq(1)       # and pull "ack" latch
 330
 331         # if now in "ST" mode: likewise do the same but with "ST"
 332         # to memory, acknowledge address, and send out LD data
 333         with m.If(st_active.q):
 334             with m.If(stport.addr.ok):
 335                 comb += wrport.addr.eq(stport.addr.data)  # addr ok, send thru
 336                 with m.If(adrok_l.qn):
 337                     comb += stport.addr_ok_o.eq(1)  # acknowledge addr ok
 338                     sync += adrok_l.s.eq(1)       # and pull "ack" latch
 339
 340         # NOTE: in both these, below, the port itself takes care
 341         # of de-asserting its "busy_o" signal, based on either ld.ok going
 342         # high (by us, here) or by st.ok going high (by the LDSTCompUnit).
 343
 344         # for LD mode, when addr has been "ok'd", assume that (because this
 345         # is a "Memory" test-class) the memory read data is valid.
 346         comb += reset_l.s.eq(0)
 347         comb += reset_l.r.eq(0)
 348         with m.If(ld_active.q & adrok_l.q):
 349             comb += ldport.ld.data.eq(rdport.data)  # put data out
 350             comb += ldport.ld.ok.eq(1)             # indicate data valid
 351             comb += reset_l.s.eq(1)   # reset mode after 1 cycle
 352
 353         # for ST mode, when addr has been "ok'd", wait for incoming "ST ok"
 354         with m.If(st_active.q & stport.st.ok):
 355             comb += wrport.data.eq(stport.st.data)  # write st to mem
 356             comb += wrport.en.eq(1)                # enable write
 357             comb += reset_l.s.eq(1)   # reset mode after 1 cycle
 358
 359         # after waiting one cycle (reset_l is "sync" mode), reset the port
 360         with m.If(reset_l.q):
 361             comb += idx_l.s.eq(1)  # deactivate port-index selector
 362             comb += ld_active.r.eq(1)   # leave the ST active for 1 cycle
 363             comb += st_active.r.eq(1)   # leave the ST active for 1 cycle
 364             comb += reset_l.r.eq(1)     # clear reset
 365             comb += adrok_l.r.eq(1)     # address reset
 366
 367         return m
 368
 369     def ports(self):
 370         for p in self.dports:
 371             yield from p.ports()
 372
 373
 374 class TstL0CacheBuffer(Elaboratable):
 375     def __init__(self, n_units=3, regwid=16, addrwid=4):
 376         self.mem = TestMemory(regwid, addrwid)
 377         self.l0 = L0CacheBuffer(n_units, self.mem, regwid, addrwid)
 378
 379     def elaborate(self, platform):
 380         m = Module()
 381         m.submodules.mem = self.mem
 382         m.submodules.l0 = self.l0
 383
 384         return m
 385
 386     def ports(self):
 387         yield from self.l0.ports()
 388         yield self.mem.rdport.addr
 389         yield self.mem.rdport.data
 390         yield self.mem.wrport.addr
 391         yield self.mem.wrport.data
 392         # TODO: mem ports
 393
 394
 395 def wait_busy(port, no=False):
 396     while True:
 397         busy = yield port.pi.busy_o
 398         print("busy", no, busy)
 399         if bool(busy) == no:
 400             break
 401         yield
 402
 403
 404 def wait_addr(port):
 405     while True:
 406         addr_ok = yield port.pi.addr_ok_o
 407         print("addrok", addr_ok)
 408         if not addr_ok:
 409             break
 410         yield
 411
 412
 413 def wait_ldok(port):
 414     while True:
 415         ldok = yield port.pi.ld.ok
 416         print("ldok", ldok)
 417         if ldok:
 418             break
 419         yield
 420
 421
 422 def l0_cache_st(dut, addr, data):
 423     l0 = dut.l0
 424     mem = dut.mem
 425     port0 = l0.dports[0]
 426     port1 = l0.dports[1]
 427
 428     # have to wait until not busy
 429     yield from wait_busy(port1, no=False)    # wait until not busy
 430
 431     # set up a ST on the port.  address first:
 432     yield port1.pi.is_st_i.eq(1)  # indicate LD
 433
 434     yield port1.pi.addr.data.eq(addr)  # set address
 435     yield port1.pi.addr.ok.eq(1)  # set ok
 436     yield from wait_addr(port1)             # wait until addr ok
 437     # yield # not needed, just for checking
 438     # yield # not needed, just for checking
 439     # assert "ST" for one cycle (required by the API)
 440     yield port1.pi.st.data.eq(data)
 441     yield port1.pi.st.ok.eq(1)
 442     yield
 443     yield port1.pi.st.ok.eq(0)
 444
 445     # can go straight to reset.
 446     yield port1.pi.is_st_i.eq(0)  # end
 447     yield port1.pi.addr.ok.eq(0)  # set !ok
 448     # yield from wait_busy(port1, False)    # wait until not busy
 449
 450
 451 def l0_cache_ld(dut, addr, expected):
 452
 453     l0 = dut.l0
 454     mem = dut.mem
 455     port0 = l0.dports[0]
 456     port1 = l0.dports[1]
 457
 458     # have to wait until not busy
 459     yield from wait_busy(port1, no=False)    # wait until not busy
 460
 461     # set up a LD on the port.  address first:
 462     yield port1.pi.is_ld_i.eq(1)  # indicate LD
 463
 464     yield port1.pi.addr.data.eq(addr)  # set address
 465     yield port1.pi.addr.ok.eq(1)  # set ok
 466     yield from wait_addr(port1)             # wait until addr ok
 467
 468     yield from wait_ldok(port1)             # wait until ld ok
 469     data = yield port1.pi.ld.data
 470
 471     # cleanup
 472     yield port1.pi.is_ld_i.eq(0)  # end
 473     yield port1.pi.addr.ok.eq(0)  # set !ok
 474     # yield from wait_busy(port1, no=False)    # wait until not busy
 475
 476     return data
 477
 478
 479 def l0_cache_ldst(dut):
 480     yield
 481     addr = 0x2
 482     data = 0xbeef
 483     data2 = 0xf00f
 484     #data = 0x4
 485     yield from l0_cache_st(dut, 0x2, data)
 486     yield from l0_cache_st(dut, 0x3, data2)
 487     result = yield from l0_cache_ld(dut, 0x2, data)
 488     result2 = yield from l0_cache_ld(dut, 0x3, data2)
 489     yield
 490     assert data == result, "data %x != %x" % (result, data)
 491     assert data2 == result2, "data2 %x != %x" % (result2, data2)
 492
 493
 494 def test_l0_cache():
 495
 496     dut = TstL0CacheBuffer()
 497     vl = rtlil.convert(dut, ports=dut.ports())
 498     with open("test_basic_l0_cache.il", "w") as f:
 499         f.write(vl)
 500
 501     run_simulation(dut, l0_cache_ldst(dut),
 502                    vcd_name='test_l0_cache_basic.vcd')
 503
 504
 505 if __name__ == '__main__':
 506     test_l0_cache()