wishbone_bridge.py

#!/usr/bin/env python3
"""Wishbone Bridge Example

Demonstrates how to use the PCIeWishboneMaster to expose FPGA registers
to the host via PCIe BAR0.

This example creates:
- A PCIe endpoint with SimPCIePHY
- A Wishbone bridge (PCIeWishboneMaster) for host CSR access
- A set of user-defined registers on the Wishbone bus
- A simulation that verifies the design elaborates correctly

Architecture::

    Host PC                          FPGA
    ───────                          ────
    PCIe BAR0 read/write  ──────►  PCIeWishboneMaster
                                        │
                                   Wishbone Bus
                                        │
                              ┌─────────┼─────────┐
                              │         │         │
                          scratch_reg  led_reg  status_reg
                          (RW, 32b)   (RW, 8b) (RO, 32b)

Usage:
    cd amaranth-pcie/
    pdm run python examples/wishbone_bridge.py
"""

from amaranth import *
from amaranth.sim import Simulator

from amaranth_pcie.phy.sim import SimPCIePHY
from amaranth_pcie.core.endpoint import PCIeEndpoint
from amaranth_pcie.frontend.wishbone import PCIeWishboneMaster


class WishboneRegisters(Elaboratable):
    """Simple Wishbone slave with user-defined registers.

    Register map (word-addressed):
        0x0000: SCRATCH  (RW) — 32-bit scratch register
        0x0001: LED      (RW) — 8-bit LED control register
        0x0002: STATUS   (RO) — 32-bit status register (reads cycle counter)
        0x0003: VERSION  (RO) — 32-bit version register (constant 0x00010000)
    """

    def __init__(self):
        # Wishbone slave signals (directly driven, no amaranth-soc bus)
        self.adr = Signal(16)
        self.dat_w = Signal(32)
        self.dat_r = Signal(32)
        self.we = Signal()
        self.stb = Signal()
        self.cyc = Signal()
        self.ack = Signal()
        self.sel = Signal(4)

        # User-visible registers
        self.scratch = Signal(32, init=0xDEADBEEF)
        self.leds = Signal(8)
        self.status_counter = Signal(32)

    def elaborate(self, platform):
        m = Module()

        # Free-running status counter
        m.d.sync += self.status_counter.eq(self.status_counter + 1)

        # Wishbone acknowledge — single-cycle
        m.d.sync += self.ack.eq(0)
        with m.If(self.stb & self.cyc & ~self.ack):
            m.d.sync += self.ack.eq(1)

            # Read path
            with m.Switch(self.adr[:4]):
                with m.Case(0x0):  # SCRATCH
                    m.d.sync += self.dat_r.eq(self.scratch)
                with m.Case(0x1):  # LED
                    m.d.sync += self.dat_r.eq(self.leds)
                with m.Case(0x2):  # STATUS (read-only)
                    m.d.sync += self.dat_r.eq(self.status_counter)
                with m.Case(0x3):  # VERSION (read-only)
                    m.d.sync += self.dat_r.eq(0x00010000)
                with m.Default():
                    m.d.sync += self.dat_r.eq(0)

            # Write path
            with m.If(self.we):
                with m.Switch(self.adr[:4]):
                    with m.Case(0x0):  # SCRATCH
                        m.d.sync += self.scratch.eq(self.dat_w)
                    with m.Case(0x1):  # LED
                        m.d.sync += self.leds.eq(self.dat_w[:8])
                    # STATUS and VERSION are read-only

        return m


class WishboneBridgeDesign(Elaboratable):
    """PCIe endpoint with Wishbone bridge and user registers.

    The host can read/write the FPGA registers through PCIe BAR0:
    - BAR0 + 0x00: SCRATCH register
    - BAR0 + 0x04: LED register
    - BAR0 + 0x08: STATUS register (read-only)
    - BAR0 + 0x0C: VERSION register (read-only)
    """

    def __init__(self):
        self.phy = SimPCIePHY(
            data_width=64,
            max_request_size=512,
            max_payload_size=128,
            with_loopback=False,
        )
        self.endpoint = PCIeEndpoint(self.phy)

    def elaborate(self, platform):
        m = Module()

        m.submodules.phy = self.phy
        m.submodules.endpoint = self.endpoint

        # Create Wishbone bridge
        m.submodules.wb_bridge = wb_bridge = PCIeWishboneMaster(
            endpoint=self.endpoint,
            base_address=0x00000000,
            wb_addr_width=16,
            wb_data_width=32,
        )

        # Create user registers
        m.submodules.regs = regs = WishboneRegisters()

        # Connect Wishbone bridge to user registers
        m.d.comb += [
            regs.adr.eq(wb_bridge.wb.adr),
            regs.dat_w.eq(wb_bridge.wb.dat_w),
            regs.we.eq(wb_bridge.wb.we),
            regs.stb.eq(wb_bridge.wb.stb),
            regs.cyc.eq(wb_bridge.wb.cyc),
            regs.sel.eq(wb_bridge.wb.sel),
            wb_bridge.wb.dat_r.eq(regs.dat_r),
            wb_bridge.wb.ack.eq(regs.ack),
        ]

        # Expose for testbench
        self.regs = regs
        self.wb_bridge = wb_bridge

        return m


def main():
    print("=" * 60)
    print("Wishbone Bridge Example")
    print("=" * 60)
    print()

    design = WishboneBridgeDesign()

    sim = Simulator(design)
    sim.add_clock(1e-8)  # 100 MHz

    async def testbench(ctx):
        """Verify the Wishbone bridge design elaborates and simulates."""
        print("Starting simulation...")

        # Let the design settle
        for _ in range(10):
            await ctx.tick()

        # Verify the status counter is incrementing
        counter_val = ctx.get(design.regs.status_counter)
        print(f"  - Status counter after 10 cycles: {counter_val}")

        for _ in range(10):
            await ctx.tick()

        counter_val2 = ctx.get(design.regs.status_counter)
        print(f"  - Status counter after 20 cycles: {counter_val2}")
        assert counter_val2 > counter_val, "Status counter should be incrementing"

        # Verify scratch register initial value
        scratch_val = ctx.get(design.regs.scratch)
        print(f"  - Scratch register initial value: 0x{scratch_val:08X}")

        # Run for more cycles
        for _ in range(80):
            await ctx.tick()

        print("  - Simulation completed (100 cycles)")

    sim.add_testbench(testbench)

    vcd_path = "wishbone_bridge.vcd"
    gtkw_path = "wishbone_bridge.gtkw"

    print(f"Writing VCD to: {vcd_path}")
    print(f"Writing GTKW to: {gtkw_path}")
    print()

    with sim.write_vcd(vcd_path, gtkw_path):
        sim.run()

    print()
    print("Register map (BAR0-relative byte addresses):")
    print("  0x00: SCRATCH  (RW)  — 32-bit scratch register")
    print("  0x04: LED      (RW)  — 8-bit LED control")
    print("  0x08: STATUS   (RO)  — 32-bit cycle counter")
    print("  0x0C: VERSION  (RO)  — 32-bit version (0x00010000)")
    print()
    print(f"Inspect waveforms with: gtkwave {vcd_path}")


if __name__ == "__main__":
    main()