prim: Add arbiter module and testbench

Signed-off-by: Alex Forencich <alex@alexforencich.com>

rtl/prim/taxi_arbiter.sv

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: CERN-OHL-S-2.0
+/*
+
+Copyright (c) 2014-2025 FPGA Ninja, LLC
+
+Authors:
+- Alex Forencich
+
+*/
+
+`resetall
+`timescale 1ns / 1ps
+`default_nettype none
+
+/*
+ * Arbiter module
+ */
+module taxi_arbiter #
+(
+    parameter PORTS = 4,
+    // select round robin arbitration
+    parameter logic ARB_ROUND_ROBIN = 1'b1,
+    // blocking arbiter enable
+    parameter logic ARB_BLOCK = 1'b1,
+    // block on acknowledge assert when nonzero, request deassert when 0
+    parameter logic ARB_BLOCK_ACK = 1'b0,
+    // LSB priority selection
+    parameter logic LSB_HIGH_PRIO = 1'b0
+)
+(
+    input  wire logic                      clk,
+    input  wire logic                      rst,
+
+    input  wire logic [PORTS-1:0]          req,
+    input  wire logic [PORTS-1:0]          ack,
+
+    output wire logic                      grant_valid,
+    output wire logic [PORTS-1:0]          grant,
+    output wire logic [$clog2(PORTS)-1:0]  grant_index
+);
+
+localparam CL_PORTS = $clog2(PORTS);
+
+logic [PORTS-1:0] grant_reg = 'd0, grant_next;
+logic grant_valid_reg = 1'b0, grant_valid_next;
+logic [CL_PORTS-1:0] grant_index_reg = 'd0, grant_index_next;
+
+assign grant_valid = grant_valid_reg;
+assign grant = grant_reg;
+assign grant_index = grant_index_reg;
+
+wire req_valid;
+wire [CL_PORTS-1:0] req_index;
+wire [PORTS-1:0] req_mask;
+
+taxi_penc #(
+    .WIDTH(PORTS),
+    .LSB_HIGH_PRIO(LSB_HIGH_PRIO)
+)
+penc_inst (
+    .input_mask(req),
+    .output_valid(req_valid),
+    .output_index(req_index),
+    .output_mask(req_mask)
+);
+
+logic [PORTS-1:0] mask_reg = 'd0, mask_next;
+
+wire masked_req_valid;
+wire [CL_PORTS-1:0] masked_req_index;
+wire [PORTS-1:0] masked_req_mask;
+
+if (ARB_ROUND_ROBIN) begin
+
+    taxi_penc #(
+        .WIDTH(PORTS),
+        .LSB_HIGH_PRIO(LSB_HIGH_PRIO)
+    )
+    penc_masked (
+        .input_mask(req & mask_reg),
+        .output_valid(masked_req_valid),
+        .output_index(masked_req_index),
+        .output_mask(masked_req_mask)
+    );
+
+end else begin
+
+    assign masked_req_valid = 1'b0;
+    assign masked_req_index = '0;
+    assign masked_req_mask = '0;
+
+end
+
+always_comb begin
+    grant_next = 'd0;
+    grant_valid_next = 1'b0;
+    grant_index_next = 'd0;
+    mask_next = mask_reg;
+
+    if (ARB_BLOCK && !ARB_BLOCK_ACK && ((grant_reg & req) != 0)) begin
+        // granted req still asserted; hold it
+        grant_valid_next = grant_valid_reg;
+        grant_next = grant_reg;
+        grant_index_next = grant_index_reg;
+    end else if (ARB_BLOCK && ARB_BLOCK_ACK && grant_valid && ((grant_reg & ack) == 0)) begin
+        // granted req not yet acknowledged; hold it
+        grant_valid_next = grant_valid_reg;
+        grant_next = grant_reg;
+        grant_index_next = grant_index_reg;
+    end else if (req_valid) begin
+        if (ARB_ROUND_ROBIN) begin
+            if (masked_req_valid) begin
+                grant_valid_next = 1'b1;
+                grant_next = masked_req_mask;
+                grant_index_next = masked_req_index;
+                if (LSB_HIGH_PRIO) begin
+                    mask_next = {PORTS{1'b1}} << (masked_req_index + 1);
+                end else begin
+                    mask_next = {PORTS{1'b1}} >> ((CL_PORTS+1)'(PORTS) - masked_req_index);
+                end
+            end else begin
+                grant_valid_next = 1;
+                grant_next = req_mask;
+                grant_index_next = req_index;
+                if (LSB_HIGH_PRIO) begin
+                    mask_next = {PORTS{1'b1}} << (req_index + 1);
+                end else begin
+                    mask_next = {PORTS{1'b1}} >> ((CL_PORTS+1)'(PORTS) - req_index);
+                end
+            end
+        end else begin
+            grant_valid_next = 1'b1;
+            grant_next = req_mask;
+            grant_index_next = req_index;
+        end
+    end
+end
+
+always_ff @(posedge clk) begin
+    grant_reg <= grant_next;
+    grant_valid_reg <= grant_valid_next;
+    grant_index_reg <= grant_index_next;
+    mask_reg <= mask_next;
+
+    if (rst) begin
+        grant_reg <= 'd0;
+        grant_valid_reg <= 1'b0;
+        grant_index_reg <= 'd0;
+        mask_reg <= 'd0;
+    end
+end
+
+endmodule
+
+`resetall

tb/prim/taxi_arbiter/Makefile

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: CERN-OHL-S-2.0
+#
+# Copyright (c) 2025 FPGA Ninja, LLC
+#
+# Authors:
+# - Alex Forencich
+
+TOPLEVEL_LANG = verilog
+
+SIM ?= verilator
+WAVES ?= 0
+
+COCOTB_HDL_TIMEUNIT = 1ns
+COCOTB_HDL_TIMEPRECISION = 1ps
+
+DUT      = taxi_arbiter
+COCOTB_TEST_MODULES = test_$(DUT)
+COCOTB_TOPLEVEL     = $(DUT)
+MODULE   = $(COCOTB_TEST_MODULES)
+TOPLEVEL = $(COCOTB_TOPLEVEL)
+VERILOG_SOURCES += ../../../rtl/prim/$(DUT).sv
+VERILOG_SOURCES += ../../../rtl/prim/taxi_penc.sv
+
+# handle file list files
+process_f_file = $(call process_f_files,$(addprefix $(dir $1),$(shell cat $1)))
+process_f_files = $(foreach f,$1,$(if $(filter %.f,$f),$(call process_f_file,$f),$f))
+uniq_base = $(if $1,$(call uniq_base,$(foreach f,$1,$(if $(filter-out $(notdir $(lastword $1)),$(notdir $f)),$f,))) $(lastword $1))
+VERILOG_SOURCES := $(call uniq_base,$(call process_f_files,$(VERILOG_SOURCES)))
+
+# module parameters
+export PARAM_PORTS := 32
+export PARAM_ARM_ROUND_ROBIN := "1'b1"
+export PARAM_ARM_BLOCK := "1'b1"
+export PARAM_ARM_BLOCK_ACK := "1'b0"
+export PARAM_LSB_HIGH_PRIO := "1'b0"
+
+ifeq ($(SIM), icarus)
+	PLUSARGS += -fst
+
+	COMPILE_ARGS += $(foreach v,$(filter PARAM_%,$(.VARIABLES)),-P $(COCOTB_TOPLEVEL).$(subst PARAM_,,$(v))=$($(v)))
+else ifeq ($(SIM), verilator)
+	COMPILE_ARGS += $(foreach v,$(filter PARAM_%,$(.VARIABLES)),-G$(subst PARAM_,,$(v))=$($(v)))
+
+	ifeq ($(WAVES), 1)
+		COMPILE_ARGS += --trace-fst
+		VERILATOR_TRACE = 1
+	endif
+endif
+
+include $(shell cocotb-config --makefiles)/Makefile.sim

tb/prim/taxi_arbiter/test_taxi_arbiter.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: CERN-OHL-S-2.0
+"""
+
+Copyright (c) 2020-2025 FPGA Ninja, LLC
+
+Authors:
+- Alex Forencich
+
+"""
+
+import logging
+import os
+
+import cocotb_test.simulator
+import pytest
+
+import cocotb
+from cocotb.clock import Clock
+from cocotb.triggers import RisingEdge
+
+
+class TB(object):
+    def __init__(self, dut):
+        self.dut = dut
+
+        self.log = logging.getLogger("cocotb.tb")
+        self.log.setLevel(logging.DEBUG)
+
+        cocotb.start_soon(Clock(dut.clk, 10, units="ns").start())
+
+        dut.req.setimmediatevalue(0)
+        dut.ack.setimmediatevalue(0)
+
+    async def reset(self):
+        self.dut.rst.setimmediatevalue(0)
+        await RisingEdge(self.dut.clk)
+        await RisingEdge(self.dut.clk)
+        self.dut.rst.value = 1
+        await RisingEdge(self.dut.clk)
+        await RisingEdge(self.dut.clk)
+        self.dut.rst.value = 0
+        await RisingEdge(self.dut.clk)
+        await RisingEdge(self.dut.clk)
+
+
+@cocotb.test()
+async def run_single_bit(dut):
+
+    tb = TB(dut)
+
+    round_robin = bool(int(dut.ARB_ROUND_ROBIN.value))
+    lsb_high_prio = bool(int(dut.LSB_HIGH_PRIO.value))
+
+    await tb.reset()
+
+    if lsb_high_prio:
+        prev_index = 31
+    else:
+        prev_index = 0
+
+    for i in range(32):
+        lst = [i]
+        k = 0
+        for y in lst:
+            k = k | 1 << y
+
+        tb.log.info("Request: 0x%08x", k)
+
+        dut.req.value = k
+        await RisingEdge(dut.clk)
+        dut.req.value = 0
+        await RisingEdge(dut.clk)
+
+        if round_robin:
+            if lsb_high_prio:
+                # emulate round robin
+                lst2 = [x for x in lst if x > prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = min(lst2)
+            else:
+                # emulate round robin
+                lst2 = [x for x in lst if x < prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = max(lst2)
+        else:
+            if lsb_high_prio:
+                g = min(lst)
+            else:
+                g = max(lst)
+
+        tb.log.info("Grant (mask): 0x%08x", int(dut.grant.value))
+        tb.log.info("Grant (index): %d", int(dut.grant_index.value))
+
+        assert int(dut.grant.value) == 1 << g
+        assert int(dut.grant_index.value) == g
+
+        prev_index = int(g)
+
+        await RisingEdge(dut.clk)
+
+
+@cocotb.test()
+async def run_cycle(dut):
+
+    tb = TB(dut)
+
+    round_robin = bool(int(dut.ARB_ROUND_ROBIN.value))
+    lsb_high_prio = bool(int(dut.LSB_HIGH_PRIO.value))
+
+    await tb.reset()
+
+    if lsb_high_prio:
+        prev_index = 31
+    else:
+        prev_index = 0
+
+    for i in range(32):
+        lst = [0, 5, 10, 15, 20, 25, 30]
+        k = 0
+        for y in lst:
+            k = k | 1 << y
+
+        tb.log.info("Request: 0x%08x", k)
+
+        dut.req.value = k
+        await RisingEdge(dut.clk)
+        dut.req.value = 0
+        await RisingEdge(dut.clk)
+
+        if round_robin:
+            if lsb_high_prio:
+                # emulate round robin
+                lst2 = [x for x in lst if x > prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = min(lst2)
+            else:
+                # emulate round robin
+                lst2 = [x for x in lst if x < prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = max(lst2)
+        else:
+            if lsb_high_prio:
+                g = min(lst)
+            else:
+                g = max(lst)
+
+        tb.log.info("Grant (mask): 0x%08x", int(dut.grant.value))
+        tb.log.info("Grant (index): %d", int(dut.grant_index.value))
+
+        assert int(dut.grant.value) == 1 << g
+        assert int(dut.grant_index.value) == g
+
+        prev_index = int(g)
+
+        await RisingEdge(dut.clk)
+
+
+@cocotb.test()
+async def run_two_bits(dut):
+
+    tb = TB(dut)
+
+    round_robin = bool(int(dut.ARB_ROUND_ROBIN.value))
+    lsb_high_prio = bool(int(dut.LSB_HIGH_PRIO.value))
+
+    await tb.reset()
+
+    if lsb_high_prio:
+        prev_index = 31
+    else:
+        prev_index = 0
+
+    for i in range(32):
+        for j in range(32):
+            lst = [i, j]
+            k = 0
+            for y in lst:
+                k = k | 1 << y
+
+            tb.log.info("Request: 0x%08x", k)
+
+            dut.req.value = k
+            await RisingEdge(dut.clk)
+            dut.req.value = 0
+            await RisingEdge(dut.clk)
+
+            if round_robin:
+                if lsb_high_prio:
+                    # emulate round robin
+                    lst2 = [x for x in lst if x > prev_index]
+                    if len(lst2) == 0:
+                        lst2 = lst
+                    g = min(lst2)
+                else:
+                    # emulate round robin
+                    lst2 = [x for x in lst if x < prev_index]
+                    if len(lst2) == 0:
+                        lst2 = lst
+                    g = max(lst2)
+            else:
+                if lsb_high_prio:
+                    g = min(lst)
+                else:
+                    g = max(lst)
+
+            tb.log.info("Grant (mask): 0x%08x", int(dut.grant.value))
+            tb.log.info("Grant (index): %d", int(dut.grant_index.value))
+
+            assert int(dut.grant.value) == 1 << g
+            assert int(dut.grant_index.value) == g
+
+            prev_index = int(g)
+
+            await RisingEdge(dut.clk)
+
+
+@cocotb.test()
+async def run_five_bits(dut):
+
+    tb = TB(dut)
+
+    round_robin = bool(int(dut.ARB_ROUND_ROBIN.value))
+    lsb_high_prio = bool(int(dut.LSB_HIGH_PRIO.value))
+
+    await tb.reset()
+
+    if lsb_high_prio:
+        prev_index = 31
+    else:
+        prev_index = 0
+
+    for i in range(32):
+        lst = [(i*x) % 32 for x in [1, 3, 5, 7, 11]]
+        k = 0
+        for y in lst:
+            k = k | 1 << y
+
+        tb.log.info("Request: 0x%08x", k)
+
+        dut.req.value = k
+        await RisingEdge(dut.clk)
+        dut.req.value = 0
+        await RisingEdge(dut.clk)
+
+        if round_robin:
+            if lsb_high_prio:
+                # emulate round robin
+                lst2 = [x for x in lst if x > prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = min(lst2)
+            else:
+                # emulate round robin
+                lst2 = [x for x in lst if x < prev_index]
+                if len(lst2) == 0:
+                    lst2 = lst
+                g = max(lst2)
+        else:
+            if lsb_high_prio:
+                g = min(lst)
+            else:
+                g = max(lst)
+
+        tb.log.info("Grant (mask): 0x%08x", int(dut.grant.value))
+        tb.log.info("Grant (index): %d", int(dut.grant_index.value))
+
+        assert int(dut.grant.value) == 1 << g
+        assert int(dut.grant_index.value) == g
+
+        prev_index = int(g)
+
+        await RisingEdge(dut.clk)
+
+
+# cocotb-test
+
+tests_dir = os.path.abspath(os.path.dirname(__file__))
+rtl_dir = os.path.abspath(os.path.join(tests_dir, '..', '..', '..', 'rtl'))
+
+
+def process_f_files(files):
+    lst = {}
+    for f in files:
+        if f[-2:].lower() == '.f':
+            with open(f, 'r') as fp:
+                l = fp.read().split()
+            for f in process_f_files([os.path.join(os.path.dirname(f), x) for x in l]):
+                lst[os.path.basename(f)] = f
+        else:
+            lst[os.path.basename(f)] = f
+    return list(lst.values())
+
+
+@pytest.mark.parametrize("lsb_high_prio", [0, 1])
+@pytest.mark.parametrize("round_robin", [0, 1])
+def test_taxi_arbiter(request, round_robin, lsb_high_prio):
+    dut = "taxi_arbiter"
+    module = os.path.splitext(os.path.basename(__file__))[0]
+    toplevel = dut
+
+    verilog_sources = [
+        os.path.join(rtl_dir, "prim", f"{dut}.sv"),
+        os.path.join(rtl_dir, "prim", "taxi_penc.sv"),
+    ]
+
+    verilog_sources = process_f_files(verilog_sources)
+
+    parameters = {}
+
+    parameters['PORTS'] = 32
+    parameters['ARB_ROUND_ROBIN'] = f"1'b{round_robin}"
+    parameters['ARB_BLOCK'] = "1'b1"
+    parameters['ARB_BLOCK_ACK'] = "1'b0"
+    parameters['LSB_HIGH_PRIO'] = f"1'b{lsb_high_prio}"
+
+    extra_env = {f'PARAM_{k}': str(v) for k, v in parameters.items()}
+
+    sim_build = os.path.join(tests_dir, "sim_build",
+        request.node.name.replace('[', '-').replace(']', ''))
+
+    cocotb_test.simulator.run(
+        simulator="verilator",
+        python_search=[tests_dir],
+        verilog_sources=verilog_sources,
+        toplevel=toplevel,
+        module=module,
+        parameters=parameters,
+        sim_build=sim_build,
+        extra_env=extra_env,
+    )