[soc.git] / src / soc / simple / issuer.py

"""simple core issuer

not in any way intended for production use.  this runs a FSM that:

* reads the Program Counter from StateRegs
* reads an instruction from a fixed-size Test Memory
* issues it to the Simple Core
* waits for it to complete
* increments the PC
* does it all over again

the purpose of this module is to verify the functional correctness
of the Function Units in the absolute simplest and clearest possible
way, and to at provide something that can be further incrementally
improved.
"""

from nmigen import (Elaboratable, Module, Signal, ClockSignal, ResetSignal,
                    ClockDomain, DomainRenamer)
from nmigen.cli import rtlil
from nmigen.cli import main
import sys

from soc.decoder.power_decoder import create_pdecode
from soc.decoder.power_decoder2 import PowerDecode2
from soc.decoder.decode2execute1 import IssuerDecode2ToOperand
from soc.decoder.decode2execute1 import Data
from soc.experiment.testmem import TestMemory # test only for instructions
from soc.regfile.regfiles import StateRegs, FastRegs
from soc.simple.core import NonProductionCore
from soc.config.test.test_loadstore import TestMemPspec
from soc.config.ifetch import ConfigFetchUnit
from soc.decoder.power_enums import MicrOp
from soc.debug.dmi import CoreDebug, DMIInterface
from soc.debug.jtag import JTAG
from soc.config.pinouts import get_pinspecs
from soc.config.state import CoreState
from soc.interrupts.xics import XICS_ICP, XICS_ICS
from soc.bus.simple_gpio import SimpleGPIO
from soc.clock.select import ClockSelect
from soc.clock.dummypll import DummyPLL


from nmutil.util import rising_edge


class TestIssuerInternal(Elaboratable):
    """TestIssuer - reads instructions from TestMemory and issues them

    efficiency and speed is not the main goal here: functional correctness is.
    """
    def __init__(self, pspec):

        # JTAG interface.  add this right at the start because if it's
        # added it *modifies* the pspec, by adding enable/disable signals
        # for parts of the rest of the core
        self.jtag_en = hasattr(pspec, "debug") and pspec.debug == 'jtag'
        if self.jtag_en:
            subset = {'uart', 'mtwi', 'eint', 'gpio', 'mspi0', 'mspi1',
                      'pwm', 'sd0', 'sdr'}
            self.jtag = JTAG(get_pinspecs(subset=subset))
            # add signals to pspec to enable/disable icache and dcache
            # (or data and intstruction wishbone if icache/dcache not included)
            # https://bugs.libre-soc.org/show_bug.cgi?id=520
            # TODO: do we actually care if these are not domain-synchronised?
            # honestly probably not.
            pspec.wb_icache_en = self.jtag.wb_icache_en
            pspec.wb_dcache_en = self.jtag.wb_dcache_en

        # add interrupt controller?
        self.xics = hasattr(pspec, "xics") and pspec.xics == True
        if self.xics:
            self.xics_icp = XICS_ICP()
            self.xics_ics = XICS_ICS()
            self.int_level_i = self.xics_ics.int_level_i

        # add GPIO peripheral?
        self.gpio = hasattr(pspec, "gpio") and pspec.gpio == True
        if self.gpio:
            self.simple_gpio = SimpleGPIO()
            self.gpio_o = self.simple_gpio.gpio_o

        # main instruction core25
        self.core = core = NonProductionCore(pspec)

        # instruction decoder.  goes into Trap Record
        pdecode = create_pdecode()
        self.cur_state = CoreState("cur") # current state (MSR/PC/EINT)
        self.pdecode2 = PowerDecode2(pdecode, state=self.cur_state,
                                     opkls=IssuerDecode2ToOperand)

        # Test Instruction memory
        self.imem = ConfigFetchUnit(pspec).fu
        # one-row cache of instruction read
        self.iline = Signal(64) # one instruction line
        self.iprev_adr = Signal(64) # previous address: if different, do read

        # DMI interface
        self.dbg = CoreDebug()

        # instruction go/monitor
        self.pc_o = Signal(64, reset_less=True)
        self.pc_i = Data(64, "pc_i") # set "ok" to indicate "please change me"
        self.core_bigendian_i = Signal()
        self.busy_o = Signal(reset_less=True)
        self.memerr_o = Signal(reset_less=True)

        # FAST regfile read /write ports for PC, MSR, DEC/TB
        staterf = self.core.regs.rf['state']
        self.state_r_pc = staterf.r_ports['cia'] # PC rd
        self.state_w_pc = staterf.w_ports['d_wr1'] # PC wr
        self.state_r_msr = staterf.r_ports['msr'] # MSR rd

        # DMI interface access
        intrf = self.core.regs.rf['int']
        crrf = self.core.regs.rf['cr']
        xerrf = self.core.regs.rf['xer']
        self.int_r = intrf.r_ports['dmi'] # INT read
        self.cr_r = crrf.r_ports['full_cr_dbg'] # CR read
        self.xer_r = xerrf.r_ports['full_xer'] # XER read

        # hack method of keeping an eye on whether branch/trap set the PC
        self.state_nia = self.core.regs.rf['state'].w_ports['nia']
        self.state_nia.wen.name = 'state_nia_wen'

    def elaborate(self, platform):
        m = Module()
        comb, sync = m.d.comb, m.d.sync

        m.submodules.core = core = DomainRenamer("coresync")(self.core)
        m.submodules.imem = imem = self.imem
        m.submodules.dbg = dbg = self.dbg
        if self.jtag_en:
            m.submodules.jtag = jtag = self.jtag
            # TODO: UART2GDB mux, here, from external pin
            # see https://bugs.libre-soc.org/show_bug.cgi?id=499
            sync += dbg.dmi.connect_to(jtag.dmi)

        cur_state = self.cur_state

        # XICS interrupt handler
        if self.xics:
            m.submodules.xics_icp = icp = self.xics_icp
            m.submodules.xics_ics = ics = self.xics_ics
            comb += icp.ics_i.eq(ics.icp_o)           # connect ICS to ICP
            sync += cur_state.eint.eq(icp.core_irq_o) # connect ICP to core

        # GPIO test peripheral
        if self.gpio:
            m.submodules.simple_gpio = simple_gpio = self.simple_gpio

        # connect one GPIO output to ICS bit 15 (like in microwatt soc.vhdl)
        # XXX causes litex ECP5 test to get wrong idea about input and output
        # (but works with verilator sim *sigh*)
        #if self.gpio and self.xics:
        #   comb += self.int_level_i[15].eq(simple_gpio.gpio_o[0])

        # instruction decoder
        pdecode = create_pdecode()
        m.submodules.dec2 = pdecode2 = self.pdecode2

        # convenience
        dmi, d_reg, d_cr, d_xer, = dbg.dmi, dbg.d_gpr, dbg.d_cr, dbg.d_xer
        intrf = self.core.regs.rf['int']

        # clock delay power-on reset
        cd_por  = ClockDomain(reset_less=True)
        cd_sync = ClockDomain()
        core_sync = ClockDomain("coresync")
        m.domains += cd_por, cd_sync, core_sync

        ti_rst = Signal(reset_less=True)
        delay = Signal(range(4), reset=3)
        with m.If(delay != 0):
            m.d.por += delay.eq(delay - 1)
        comb += cd_por.clk.eq(ClockSignal())

        # power-on reset delay
        core_rst = ResetSignal("coresync")
        comb += ti_rst.eq(delay != 0 | dbg.core_rst_o | ResetSignal())
        comb += core_rst.eq(ti_rst)

        # busy/halted signals from core
        comb += self.busy_o.eq(core.busy_o)
        comb += pdecode2.dec.bigendian.eq(self.core_bigendian_i)

        # temporary hack: says "go" immediately for both address gen and ST
        l0 = core.l0
        ldst = core.fus.fus['ldst0']
        st_go_edge = rising_edge(m, ldst.st.rel_o)
        m.d.comb += ldst.ad.go_i.eq(ldst.ad.rel_o) # link addr-go direct to rel
        m.d.comb += ldst.st.go_i.eq(st_go_edge) # link store-go to rising rel

        # PC and instruction from I-Memory
        pc_changed = Signal() # note write to PC
        comb += self.pc_o.eq(cur_state.pc)
        ilatch = Signal(32)

        # next instruction (+4 on current)
        nia = Signal(64, reset_less=True)
        comb += nia.eq(cur_state.pc + 4)

        # read the PC
        pc = Signal(64, reset_less=True)
        pc_ok_delay = Signal()
        sync += pc_ok_delay.eq(~self.pc_i.ok)
        with m.If(self.pc_i.ok):
            # incoming override (start from pc_i)
            comb += pc.eq(self.pc_i.data)
        with m.Else():
            # otherwise read StateRegs regfile for PC...
            comb += self.state_r_pc.ren.eq(1<<StateRegs.PC)
        # ... but on a 1-clock delay
        with m.If(pc_ok_delay):
            comb += pc.eq(self.state_r_pc.data_o)

        # don't write pc every cycle
        comb += self.state_w_pc.wen.eq(0)
        comb += self.state_w_pc.data_i.eq(0)

        # don't read msr every cycle
        comb += self.state_r_msr.ren.eq(0)
        msr_read = Signal(reset=1)

        # connect up debug signals
        # TODO comb += core.icache_rst_i.eq(dbg.icache_rst_o)
        comb += dbg.terminate_i.eq(core.core_terminate_o)
        comb += dbg.state.pc.eq(pc)
        #comb += dbg.state.pc.eq(cur_state.pc)
        comb += dbg.state.msr.eq(cur_state.msr)

        # temporaries
        core_busy_o = core.busy_o                 # core is busy
        core_ivalid_i = core.ivalid_i             # instruction is valid
        core_issue_i = core.issue_i               # instruction is issued
        dec_opcode_i = pdecode2.dec.raw_opcode_in # raw opcode

        insn_type = core.e.do.insn_type

        # actually use a nmigen FSM for the first time (w00t)
        # this FSM is perhaps unusual in that it detects conditions
        # then "holds" information, combinatorially, for the core
        # (as opposed to using sync - which would be on a clock's delay)
        # this includes the actual opcode, valid flags and so on.
        with m.FSM() as fsm:

            # waiting (zzz)
            with m.State("IDLE"):
                sync += pc_changed.eq(0)
                sync += core.e.eq(0)
                sync += core.raw_insn_i.eq(0)
                sync += core.bigendian_i.eq(0)
                with m.If(~dbg.core_stop_o & ~core_rst):
                    # instruction allowed to go: start by reading the PC
                    # capture the PC and also drop it into Insn Memory
                    # we have joined a pair of combinatorial memory
                    # lookups together.  this is Generally Bad.
                    comb += self.imem.a_pc_i.eq(pc)
                    comb += self.imem.a_valid_i.eq(1)
                    comb += self.imem.f_valid_i.eq(1)
                    sync += cur_state.pc.eq(pc)

                    # initiate read of MSR.  arrives one clock later
                    comb += self.state_r_msr.ren.eq(1<<StateRegs.MSR)
                    sync += msr_read.eq(0)

                    m.next = "INSN_READ" # move to "wait for bus" phase
                with m.Else():
                    comb += core.core_stopped_i.eq(1)
                    comb += dbg.core_stopped_i.eq(1)

            # dummy pause to find out why simulation is not keeping up
            with m.State("INSN_READ"):
                # one cycle later, msr read arrives.  valid only once.
                with m.If(~msr_read):
                    sync += msr_read.eq(1) # yeah don't read it again
                    sync += cur_state.msr.eq(self.state_r_msr.data_o)
                with m.If(self.imem.f_busy_o): # zzz...
                    # busy: stay in wait-read
                    comb += self.imem.a_valid_i.eq(1)
                    comb += self.imem.f_valid_i.eq(1)
                with m.Else():
                    # not busy: instruction fetched
                    f_instr_o = self.imem.f_instr_o
                    if f_instr_o.width == 32:
                        insn = f_instr_o
                    else:
                        insn = f_instr_o.word_select(cur_state.pc[2], 32)
                    comb += dec_opcode_i.eq(insn) # actual opcode
                    sync += core.e.eq(pdecode2.e)
                    sync += core.state.eq(cur_state)
                    sync += core.raw_insn_i.eq(dec_opcode_i)
                    sync += core.bigendian_i.eq(self.core_bigendian_i)
                    sync += ilatch.eq(insn) # latch current insn
                    # also drop PC and MSR into decode "state"
                    m.next = "INSN_START" # move to "start"

            # waiting for instruction bus (stays there until not busy)
            with m.State("INSN_START"):
                comb += core_ivalid_i.eq(1) # instruction is valid
                comb += core_issue_i.eq(1)  # and issued

                m.next = "INSN_ACTIVE" # move to "wait completion"

            # instruction started: must wait till it finishes
            with m.State("INSN_ACTIVE"):
                with m.If(insn_type != MicrOp.OP_NOP):
                    comb += core_ivalid_i.eq(1) # instruction is valid
                with m.If(self.state_nia.wen & (1<<StateRegs.PC)):
                    sync += pc_changed.eq(1)
                with m.If(~core_busy_o): # instruction done!
                    # ok here we are not reading the branch unit.  TODO
                    # this just blithely overwrites whatever pipeline
                    # updated the PC
                    with m.If(~pc_changed):
                        comb += self.state_w_pc.wen.eq(1<<StateRegs.PC)
                        comb += self.state_w_pc.data_i.eq(nia)
                    sync += core.e.eq(0)
                    sync += core.raw_insn_i.eq(0)
                    sync += core.bigendian_i.eq(0)
                    m.next = "IDLE" # back to idle

        # this bit doesn't have to be in the FSM: connect up to read
        # regfiles on demand from DMI
        with m.If(d_reg.req): # request for regfile access being made
            # TODO: error-check this
            # XXX should this be combinatorial?  sync better?
            if intrf.unary:
                comb += self.int_r.ren.eq(1<<d_reg.addr)
            else:
                comb += self.int_r.addr.eq(d_reg.addr)
                comb += self.int_r.ren.eq(1)
        d_reg_delay  = Signal()
        sync += d_reg_delay.eq(d_reg.req)
        with m.If(d_reg_delay):
            # data arrives one clock later
            comb += d_reg.data.eq(self.int_r.data_o)
            comb += d_reg.ack.eq(1)

        # sigh same thing for CR debug
        with m.If(d_cr.req): # request for regfile access being made
            comb += self.cr_r.ren.eq(0b11111111) # enable all
        d_cr_delay  = Signal()
        sync += d_cr_delay.eq(d_cr.req)
        with m.If(d_cr_delay):
            # data arrives one clock later
            comb += d_cr.data.eq(self.cr_r.data_o)
            comb += d_cr.ack.eq(1)

        # aaand XER...
        with m.If(d_xer.req): # request for regfile access being made
            comb += self.xer_r.ren.eq(0b111111) # enable all
        d_xer_delay  = Signal()
        sync += d_xer_delay.eq(d_xer.req)
        with m.If(d_xer_delay):
            # data arrives one clock later
            comb += d_xer.data.eq(self.xer_r.data_o)
            comb += d_xer.ack.eq(1)

        # DEC and TB inc/dec FSM
        self.tb_dec_fsm(m, cur_state.dec)

        return m

    def tb_dec_fsm(self, m, spr_dec):
        """tb_dec_fsm

        this is a FSM for updating either dec or tb.  it runs alternately
        DEC, TB, DEC, TB.  note that SPR pipeline could have written a new
        value to DEC, however the regfile has "passthrough" on it so this
        *should* be ok.

        see v3.0B p1097-1099 for Timeer Resource and p1065 and p1076
        """

        comb, sync = m.d.comb, m.d.sync
        fast_rf = self.core.regs.rf['fast']
        fast_r_dectb = fast_rf.r_ports['issue'] # DEC/TB
        fast_w_dectb = fast_rf.w_ports['issue'] # DEC/TB

        with m.FSM() as fsm:

            # initiates read of current DEC
            with m.State("DEC_READ"):
                comb += fast_r_dectb.addr.eq(FastRegs.DEC)
                comb += fast_r_dectb.ren.eq(1)
                m.next = "DEC_WRITE"

            # waits for DEC read to arrive (1 cycle), updates with new value
            with m.State("DEC_WRITE"):
                new_dec = Signal(64)
                # TODO: MSR.LPCR 32-bit decrement mode
                comb += new_dec.eq(fast_r_dectb.data_o - 1)
                comb += fast_w_dectb.addr.eq(FastRegs.DEC)
                comb += fast_w_dectb.wen.eq(1)
                comb += fast_w_dectb.data_i.eq(new_dec)
                sync += spr_dec.eq(new_dec) # copy into cur_state for decoder
                m.next = "TB_READ"

            # initiates read of current TB
            with m.State("TB_READ"):
                comb += fast_r_dectb.addr.eq(FastRegs.TB)
                comb += fast_r_dectb.ren.eq(1)
                m.next = "TB_WRITE"

            # waits for read TB to arrive, initiates write of current TB
            with m.State("TB_WRITE"):
                new_tb = Signal(64)
                comb += new_tb.eq(fast_r_dectb.data_o + 1)
                comb += fast_w_dectb.addr.eq(FastRegs.TB)
                comb += fast_w_dectb.wen.eq(1)
                comb += fast_w_dectb.data_i.eq(new_tb)
                m.next = "DEC_READ"

        return m

    def __iter__(self):
        yield from self.pc_i.ports()
        yield self.pc_o
        yield self.memerr_o
        yield from self.core.ports()
        yield from self.imem.ports()
        yield self.core_bigendian_i
        yield self.busy_o

    def ports(self):
        return list(self)

    def external_ports(self):
        ports = self.pc_i.ports()
        ports += [self.pc_o, self.memerr_o, self.core_bigendian_i, self.busy_o,
                ]

        if self.jtag_en:
            ports += list(self.jtag.external_ports())
        else:
            # don't add DMI if JTAG is enabled
            ports += list(self.dbg.dmi.ports())

        ports += list(self.imem.ibus.fields.values())
        ports += list(self.core.l0.cmpi.lsmem.lsi.slavebus.fields.values())

        if self.xics:
            ports += list(self.xics_icp.bus.fields.values())
            ports += list(self.xics_ics.bus.fields.values())
            ports.append(self.int_level_i)

        if self.gpio:
            ports += list(self.simple_gpio.bus.fields.values())
            ports.append(self.gpio_o)

        return ports

    def ports(self):
        return list(self)


class TestIssuer(Elaboratable):
    def __init__(self, pspec):
        self.ti = TestIssuerInternal(pspec)

        self.pll = DummyPLL()

        # PLL direct clock or not
        self.pll_en = hasattr(pspec, "use_pll") and pspec.use_pll

    def elaborate(self, platform):
        m = Module()
        comb = m.d.comb

        # TestIssuer runs at direct clock
        m.submodules.ti = ti = self.ti
        cd_int = ClockDomain("coresync")

        if self.pll_en:
            # ClockSelect runs at PLL output internal clock rate
            m.submodules.pll = pll = self.pll

            # add clock domains from PLL
            cd_pll = ClockDomain("pllclk")
            m.domains += cd_pll

            # PLL clock established.  has the side-effect of running clklsel
            # at the PLL's speed (see DomainRenamer("pllclk") above)
            pllclk = ClockSignal("pllclk")
            comb += pllclk.eq(pll.clk_pll_o)

            # wire up external 24mhz to PLL
            comb += pll.clk_24_i.eq(ClockSignal())

            # now wire up ResetSignals.  don't mind them being in this domain
            pll_rst = ResetSignal("pllclk")
            comb += pll_rst.eq(ResetSignal())

        # internal clock is set to selector clock-out.  has the side-effect of
        # running TestIssuer at this speed (see DomainRenamer("intclk") above)
        intclk = ClockSignal("coresync")
        if self.pll_en:
            comb += intclk.eq(pll.clk_pll_o)
        else:
            comb += intclk.eq(ClockSignal())

        return m

    def ports(self):
        return list(self.ti.ports()) + list(self.pll.ports()) + \
               [ClockSignal(), ResetSignal()]

    def external_ports(self):
        ports = self.ti.external_ports()
        ports.append(ClockSignal())
        ports.append(ResetSignal())
        if self.pll_en:
            ports.append(self.pll.clk_sel_i)
            ports.append(self.pll.pll_18_o)
            ports.append(self.pll.pll_lck_o)
        return ports


if __name__ == '__main__':
    units = {'alu': 1, 'cr': 1, 'branch': 1, 'trap': 1, 'logical': 1,
             'spr': 1,
             'div': 1,
             'mul': 1,
             'shiftrot': 1
            }
    pspec = TestMemPspec(ldst_ifacetype='bare_wb',
                         imem_ifacetype='bare_wb',
                         addr_wid=48,
                         mask_wid=8,
                         reg_wid=64,
                         units=units)
    dut = TestIssuer(pspec)
    vl = main(dut, ports=dut.ports(), name="test_issuer")

    if len(sys.argv) == 1:
        vl = rtlil.convert(dut, ports=dut.external_ports(), name="test_issuer")
        with open("test_issuer.il", "w") as f:
            f.write(vl)