"""cocotb tests for axil_regs.sv with a Python AXI4-Lite manager. The manager drives AW and W from separate coroutines with random start delays, so writes arrive with AW first, W first or both in the same cycle. A background coroutine drives BREADY and RREADY randomly to apply back-pressure. A monitor samples every channel once per cycle and checks the handshake rules of the AMBA AXI specification (IHI0022, A3.2 and A3.3): VALID stays high with a stable payload until READY, BVALID only after both AW and W handshakes, RVALID only after an AR handshake. Register addresses come from fir_regs.h, so the C header and the RTL are checked against each other. Timing: inputs change on the falling clock edge. Signals are sampled in the ReadOnly phase after the falling edge; a channel whose VALID and READY are both high there handshakes at the next rising edge. """ from __future__ import annotations import random import re from dataclasses import dataclass, field from pathlib import Path import cocotb from cocotb.clock import Clock from cocotb.queue import Queue from cocotb.simtime import get_sim_time from cocotb.triggers import ClockCycles, FallingEdge, ReadOnly, RisingEdge OKAY, SLVERR = 0b00, 0b10 N_COEF = 8 def header_defines() -> dict[str, int]: """Read the FIR_* integer constants from fir_regs.h.""" text = (Path(__file__).resolve().parent / "fir_regs.h").read_text() pat = re.compile(r"#define\s+(FIR_\w+)\s+\(?(0x[0-9A-Fa-f]+|\d+)u?") return {m.group(1): int(m.group(2), 0) for m in pat.finditer(text)} H = header_defines() A_CTRL, A_STATUS, A_ID, A_COEF0 = H["FIR_REG_CTRL"], H["FIR_REG_STATUS"], H["FIR_REG_ID"], H["FIR_REG_COEF0"] @dataclass class RegModel: """Expected contents of the register file.""" id_value: int = H["FIR_ID_VALUE"] enable: int = 0 status: int = 0 coef: list[int] = field(default_factory=lambda: [0] * N_COEF) def mapped(self, addr: int) -> bool: return addr in (A_CTRL, A_STATUS, A_ID) or A_COEF0 <= addr < A_COEF0 + 4 * N_COEF def write(self, addr: int, data: int, strb: int) -> tuple[int, int]: """Return (expected BRESP, expected number of START pulses).""" addr &= ~3 if not self.mapped(addr): return SLVERR, 0 pulses = 0 if addr == A_CTRL and strb & 1: self.enable = data & 1 pulses = (data >> 1) & 1 elif A_COEF0 <= addr < A_COEF0 + 4 * N_COEF: k = (addr - A_COEF0) // 4 for b in range(4): if strb >> b & 1: mask = 0xFF << (8 * b) self.coef[k] = (self.coef[k] & ~mask) | (data & mask) return OKAY, pulses def read(self, addr: int) -> tuple[int, int]: """Return (expected RDATA, expected RRESP).""" addr &= ~3 if not self.mapped(addr): return 0, SLVERR if addr == A_CTRL: return self.enable, OKAY if addr == A_STATUS: return self.status, OKAY if addr == A_ID: return self.id_value, OKAY return self.coef[(addr - A_COEF0) // 4], OKAY class AxiLiteManager: """Sequential AXI4-Lite manager: one transaction at a time, random timing.""" def __init__(self, dut, rng: random.Random, max_delay: int = 3, ready_prob: float = 0.5) -> None: self.dut, self.rng, self.max_delay, self.ready_prob = dut, rng, max_delay, ready_prob self.b_queue: Queue[int] = Queue() self.r_queue: Queue[tuple[int, int]] = Queue() self.errors: list[str] = [] self.counts = {"aw": 0, "w": 0, "b": 0, "ar": 0, "r": 0} self.start_pulses = 0 for name in ("awvalid", "wvalid", "arvalid", "bready", "rready"): getattr(dut, f"s_axil_{name}").value = 0 for name in ("awaddr", "awprot", "wdata", "wstrb", "araddr", "arprot"): getattr(dut, f"s_axil_{name}").value = 0 cocotb.start_soon(self._ready_driver()) cocotb.start_soon(self._monitor()) cocotb.start_soon(self._count_start()) async def _send(self, valid: str, ready: str, payload: dict[str, int], delay: int) -> None: """Drive one VALID/READY channel: wait, raise VALID, hold until accepted.""" dut = self.dut for _ in range(delay): await FallingEdge(dut.aclk) for name, value in payload.items(): getattr(dut, name).value = value getattr(dut, valid).value = 1 while True: await ReadOnly() accepted = int(getattr(dut, ready).value) == 1 await FallingEdge(dut.aclk) if accepted: break # Not accepted yet: keep VALID and the payload unchanged (AXI rule). getattr(dut, valid).value = 0 async def write(self, addr: int, data: int, strb: int = 0xF) -> int: await FallingEdge(self.dut.aclk) aw = cocotb.start_soon(self._send("s_axil_awvalid", "s_axil_awready", {"s_axil_awaddr": addr}, self.rng.randint(0, self.max_delay))) w = cocotb.start_soon(self._send("s_axil_wvalid", "s_axil_wready", {"s_axil_wdata": data, "s_axil_wstrb": strb}, self.rng.randint(0, self.max_delay))) await aw await w resp = await self.b_queue.get() # sampled in ReadOnly before the B handshake edge await RisingEdge(self.dut.aclk) # leave the ReadOnly phase at the handshake edge return resp async def write_many(self, items: list[tuple[int, int, int]]) -> list[int]: """Several writes without waiting for each response: the AW and W streams run independently, so a new address can arrive while the previous write is still waiting for its data or its response.""" await FallingEdge(self.dut.aclk) async def aw_stream() -> None: for addr, _, _ in items: await self._send("s_axil_awvalid", "s_axil_awready", {"s_axil_awaddr": addr}, self.rng.randint(0, self.max_delay)) async def w_stream() -> None: for _, data, strb in items: await self._send("s_axil_wvalid", "s_axil_wready", {"s_axil_wdata": data, "s_axil_wstrb": strb}, self.rng.randint(0, self.max_delay)) aw = cocotb.start_soon(aw_stream()) w = cocotb.start_soon(w_stream()) responses = [await self.b_queue.get() for _ in items] await aw await w await RisingEdge(self.dut.aclk) return responses async def read(self, addr: int) -> tuple[int, int]: await FallingEdge(self.dut.aclk) await self._send("s_axil_arvalid", "s_axil_arready", {"s_axil_araddr": addr}, self.rng.randint(0, self.max_delay)) result = await self.r_queue.get() await RisingEdge(self.dut.aclk) return result async def _ready_driver(self) -> None: """Random BREADY and RREADY: back-pressure on the response channels.""" while True: await FallingEdge(self.dut.aclk) self.dut.s_axil_bready.value = int(self.rng.random() < self.ready_prob) self.dut.s_axil_rready.value = int(self.rng.random() < self.ready_prob) async def _count_start(self) -> None: while True: await RisingEdge(self.dut.aclk) await ReadOnly() self.start_pulses += int(self.dut.start_o.value) def _fail(self, msg: str) -> None: self.errors.append(f"{get_sim_time('ns'):.0f} ns: {msg}") async def _monitor(self) -> None: """Sample all channels once per cycle and check the handshake rules.""" dut = self.dut prev: dict[str, int] = {} while True: await FallingEdge(dut.aclk) await ReadOnly() s = {n: int(getattr(dut, f"s_axil_{n}").value) for n in ( "awvalid", "awready", "wvalid", "wready", "bvalid", "bready", "bresp", "arvalid", "arready", "rvalid", "rready", "rdata", "rresp")} if int(dut.aresetn.value) == 0: if s["bvalid"] or s["rvalid"]: self._fail("BVALID or RVALID high during reset") prev = {} continue if prev: # A VALID that was not accepted must stay high with the same payload. if prev["bvalid"] and not prev["bready"] and (not s["bvalid"] or s["bresp"] != prev["bresp"]): self._fail("BVALID dropped or BRESP changed before BREADY") if prev["rvalid"] and not prev["rready"] and ( not s["rvalid"] or (s["rdata"], s["rresp"]) != (prev["rdata"], prev["rresp"])): self._fail("RVALID dropped or RDATA/RRESP changed before RREADY") # A new response may only appear after its request handshakes. if s["bvalid"] and not prev["bvalid"]: if self.counts["b"] >= min(self.counts["aw"], self.counts["w"]): self._fail("BVALID raised before both AW and W handshakes") if s["rvalid"] and not prev["rvalid"]: if self.counts["r"] >= self.counts["ar"]: self._fail("RVALID raised before the AR handshake") # Handshakes at the coming rising edge. if s["awvalid"] and s["awready"]: self.counts["aw"] += 1 if s["wvalid"] and s["wready"]: self.counts["w"] += 1 if s["arvalid"] and s["arready"]: self.counts["ar"] += 1 if s["bvalid"] and s["bready"]: self.counts["b"] += 1 self.b_queue.put_nowait(s["bresp"]) if s["rvalid"] and s["rready"]: self.counts["r"] += 1 self.r_queue.put_nowait((s["rdata"], s["rresp"])) prev = s async def setup(dut, seed: int, **kwargs) -> tuple[AxiLiteManager, RegModel]: cocotb.start_soon(Clock(dut.aclk, 10, unit="ns").start()) dut.aresetn.value = 0 dut.status_i.value = 0 mgr = AxiLiteManager(dut, random.Random(seed), **kwargs) await ClockCycles(dut.aclk, 3) await FallingEdge(dut.aclk) dut.aresetn.value = 1 return mgr, RegModel() def check_clean(mgr: AxiLiteManager) -> None: assert not mgr.errors, "protocol errors:\n" + "\n".join(mgr.errors[:10]) @cocotb.test(timeout_time=500, timeout_unit="us") async def reset_values_and_id(dut) -> None: """ID identifies the block; CTRL and coefficients reset to zero.""" mgr, model = await setup(dut, seed=1) for addr in (A_ID, A_CTRL, A_STATUS, A_COEF0, A_COEF0 + 4 * (N_COEF - 1)): got = await mgr.read(addr) assert got == model.read(addr), f"read 0x{addr:02X}: got {got}, expected {model.read(addr)}" check_clean(mgr) @cocotb.test(timeout_time=500, timeout_unit="us") async def start_pulse_and_enable(dut) -> None: """START gives exactly one one-cycle pulse per write of 1; ENABLE is a level.""" mgr, model = await setup(dut, seed=2) for n in range(1, 6): resp = await mgr.write(A_CTRL, H["FIR_CTRL_ENABLE"] | H["FIR_CTRL_START"]) assert resp == OKAY await ClockCycles(dut.aclk, 2) assert mgr.start_pulses == n, f"expected {n} START pulses, saw {mgr.start_pulses}" assert int(dut.enable_o.value) == 1 rdata, rresp = await mgr.read(A_CTRL) assert (rdata, rresp) == (H["FIR_CTRL_ENABLE"], OKAY), "START must read back as 0" await mgr.write(A_CTRL, 0) await ClockCycles(dut.aclk, 2) assert int(dut.enable_o.value) == 0 and mgr.start_pulses == 5 check_clean(mgr) @cocotb.test(timeout_time=500, timeout_unit="us") async def random_traffic_with_backpressure(dut) -> None: """600 random reads and writes, random strobes and timing, against the model.""" mgr, model = await setup(dut, seed=3, max_delay=4, ready_prob=0.4) rng = random.Random(33) addrs = [A_CTRL, A_STATUS, A_ID, 0x0C] + [A_COEF0 + 4 * k for k in range(N_COEF)] + [0x30, 0x34, 0x38, 0x3C] pulses = 0 for i in range(600): if i % 50 == 0: model.status = rng.getrandbits(32) dut.status_i.value = model.status addr = rng.choice(addrs) if rng.random() < 0.5: data, strb = rng.getrandbits(32), rng.randint(0, 15) exp_resp, exp_pulse = model.write(addr, data, strb) resp = await mgr.write(addr, data, strb) assert resp == exp_resp, f"write 0x{addr:02X}: BRESP {resp:02b}, expected {exp_resp:02b}" pulses += exp_pulse else: got = await mgr.read(addr) exp = model.read(addr) assert got == exp, f"read 0x{addr:02X}: got {got}, expected {exp}" await ClockCycles(dut.aclk, 3) for k in range(N_COEF): hw = (int(dut.coef_o.value) >> (32 * k)) & 0xFFFF_FFFF assert hw == model.coef[k], f"coef_o[{k}] = 0x{hw:08X}, expected 0x{model.coef[k]:08X}" assert mgr.start_pulses == pulses, f"{mgr.start_pulses} START pulses, expected {pulses}" assert mgr.counts["aw"] == mgr.counts["w"] == mgr.counts["b"] assert mgr.counts["ar"] == mgr.counts["r"] check_clean(mgr) dut._log.info(f"handshakes: {mgr.counts}") @cocotb.test(timeout_time=500, timeout_unit="us") async def overlapping_writes(dut) -> None: """Bursts of writes whose AW and W streams run ahead of the responses.""" mgr, model = await setup(dut, seed=4, max_delay=2, ready_prob=0.3) rng = random.Random(44) for _ in range(40): items = [] for _ in range(rng.randint(2, 5)): addr = A_COEF0 + 4 * rng.randrange(N_COEF) items.append((addr, rng.getrandbits(32), rng.randint(1, 15))) expected = [model.write(a, d, s)[0] for a, d, s in items] got = await mgr.write_many(items) assert got == expected, f"BRESP {got}, expected {expected}" for k in range(N_COEF): got = await mgr.read(A_COEF0 + 4 * k) assert got == (model.coef[k], OKAY), f"COEF{k}: got {got}, expected {model.coef[k]:#x}" check_clean(mgr)