Circular allocator (#151)

Author: tilk

test/lib/test_allocators.py

@@ -98,3 +98,68 @@ async def order_verifier(sim: TestbenchContext):
             sim.add_testbench(order_verifier, background=True)
             sim.add_testbench(allocator)
             sim.add_testbench(deallocator)
+
+
+class TestCircularAllocator(TestCaseWithSimulator):
+    @pytest.mark.parametrize("entries", [5, 8])
+    @pytest.mark.parametrize("max_alloc", [1, 3])
+    @pytest.mark.parametrize("max_free", [1, 3])
+    @pytest.mark.parametrize("with_validate_arguments", [False, True])
+    def test_allocator(self, entries: int, max_alloc: int, max_free: int, with_validate_arguments: bool):
+        m = CircularAllocator(entries, max_alloc, max_free, with_validate_arguments=with_validate_arguments)
+        dut = SimpleTestCircuit(m)
+
+        iterations = 5 * entries
+
+        start_idx = end_idx = allocated = 0
+
+        async def allocator(sim: TestbenchContext):
+            nonlocal allocated, end_idx
+            while True:
+                curr_max_alloc = max_alloc if with_validate_arguments else min(entries - allocated, max_alloc)
+                count = random.randrange(curr_max_alloc + 1)
+                ret = await dut.alloc.call_try(sim, count=count)
+                if ret is None:
+                    assert (with_validate_arguments and count > entries - allocated) or allocated == entries
+                    count = 1
+                    ret = await dut.alloc.call(sim, count=count)
+                for i in range(max_alloc):
+                    assert ret.idents[i] == (end_idx + i) % entries
+                await sim.delay(1e-12)
+                allocated = allocated + count
+                end_idx = (end_idx + count) % entries
+                assert ret.new_end_idx == end_idx
+                await sim.delay(1e-12)
+                await self.random_wait_geom(sim)
+
+        async def deallocator(sim: TestbenchContext):
+            nonlocal allocated, start_idx
+            for _ in range(iterations):
+                curr_max_free = max_free if with_validate_arguments else min(allocated, max_free)
+                count = random.randrange(curr_max_free + 1)
+                ret = await dut.free.call_try(sim, count=count)
+                if ret is None:
+                    assert (with_validate_arguments and count > allocated) or allocated == 0
+                    count = 1
+                    ret = await dut.free.call(sim, count=count)
+                for i in range(max_free):
+                    assert ret.idents[i] == (start_idx + i) % entries
+                await sim.delay(1e-12)
+                allocated = allocated - count
+                start_idx = (start_idx + count) % entries
+                assert ret.new_start_idx == start_idx
+                await sim.delay(1e-12)
+                await self.random_wait_geom(sim)
+
+        async def verifier(sim: TestbenchContext):
+            while True:
+                await sim.delay(2e-12)
+                assert allocated == sim.get(m.allocated)
+                assert start_idx == sim.get(m.start_idx)
+                assert end_idx == sim.get(m.end_idx)
+                await sim.tick()
+
+        with self.run_simulation(dut) as sim:
+            sim.add_testbench(allocator, background=True)
+            sim.add_testbench(deallocator)
+            sim.add_testbench(verifier, background=True)

transactron/lib/allocators.py

@@ -1,11 +1,13 @@
 from amaranth import *
 
-from transactron.core import Method, Methods, TModule, def_method, def_methods
+from transactron.core import Method, Methods, TModule, def_method, def_methods, Provided
 from transactron.utils.amaranth_ext.elaboratables import MultiPriorityEncoder
 from amaranth.lib.data import ArrayLayout
 
+from transactron.utils.amaranth_ext.functions import mod_add
 
-__all__ = ["PriorityEncoderAllocator"]
+
+__all__ = ["PriorityEncoderAllocator", "PreservedOrderAllocator", "CircularAllocator"]
 
 
 class PriorityEncoderAllocator(Elaboratable):
@@ -129,3 +131,162 @@ def _():
             return {"used": used, "order": order}
 
         return m
+
+
+class CircularAllocator(Elaboratable):
+    """Circular allocator.
+
+    Allows to allocate and deallocate identifiers in FIFO order. It is
+    possible to allocate or deallocate multiple identifiers in a single
+    clock cycle.
+    """
+
+    alloc: Provided[Method]
+    """
+    Allocates new identifiers. Ready only if there are free identifiers
+    available. The `count` argument must be less or equal to the number
+    of available free identifiers.
+
+    If `with_validate_arguments` is false, invalid calls are allowed but can
+    result in illegal state.
+
+    Parameters
+    ----------
+    count: range(max_alloc + 1)
+        The number of identifiers to allocate.
+
+    Returns
+    -------
+    idents: ArrayLayout(range(entries), max_alloc)
+        Array of allocated identifiers.
+    new_end_idx: range(entries)
+        First identifier after the last allocated one.
+    """
+
+    free: Provided[Method]
+    """
+    Frees previously allocated identifiers. Ready only if there are allocated
+    identifiers. The `count` argument must be less or equal to the number of
+    allocated identifiers.
+
+    If `with_validate_arguments` is false, invalid calls are allowed but can
+    result in illegal state.
+
+    Parameters
+    ----------
+    count: range(max_free + 1)
+        The number of identifiers to deallocate.
+
+    Returns
+    -------
+    idents: ArrayLayout(range(entries), max_alloc)
+        Array of freed identifiers.
+    new_start_idx: range(entries)
+        First identifier after the last freed one.
+    """
+
+    clear: Provided[Method]
+    """
+    Restores the allocator to its initial state.
+    """
+
+    start_idx: Signal
+    """
+    First pointer of the circular allocator. The oldest allocated identifier,
+    if one exists.
+    """
+
+    end_idx: Signal
+    """
+    Second pointer of the circular allocator. The first after the newest
+    allocated identifier, if one exists.
+    """
+
+    allocated: Signal
+    """
+    The number of allocated identifiers.
+    """
+
+    def __init__(self, entries: int, max_alloc: int = 1, max_free: int = 1, *, with_validate_arguments=True):
+        """
+        Parameters
+        ----------
+        entries: int
+            The total number of identifiers available for allocation.
+        max_alloc: int, optional
+            The amount of identifiers that can be allocated in a single cycle.
+            Defaults to 1.
+        max_free: int, optional
+            The amount of identifiers that can be freed in a single cycle.
+            Defaults to 1.
+        with_validate_arguments: bool, optional
+            If true, `alloc` and `free` methods are guarded by argument
+            validation so that it is impossible to put the allocator into
+            an illegal state. Otherwise, the `count` argument needs to
+            be verified using external logic.
+            Defaults to true.
+        """
+        self.entries = entries
+        self.max_alloc = max_alloc
+        self.max_free = max_free
+        self.with_validate_arguments = with_validate_arguments
+
+        self.alloc = Method(
+            i=[("count", range(max_alloc + 1))],
+            o=[("idents", ArrayLayout(range(entries), max_alloc)), ("new_end_idx", range(entries))],
+        )
+        self.free = Method(
+            i=[("count", range(max_free + 1))],
+            o=[("idents", ArrayLayout(range(entries), max_free)), ("new_start_idx", range(entries))],
+        )
+        self.clear = Method()
+
+        self.start_idx = Signal(range(entries))
+        self.end_idx = Signal(range(entries))
+        self.allocated = Signal(range(entries + 1))
+
+    def elaborate(self, platform):
+        m = TModule()
+
+        alloc_count = Signal(range(self.max_alloc + 1))
+        free_count = Signal(range(self.max_free + 1))
+
+        m.d.sync += self.allocated.eq(self.allocated + alloc_count - free_count)
+
+        kwargs = {}
+        if self.with_validate_arguments and self.max_alloc > 1:
+            kwargs["validate_arguments"] = lambda count: self.allocated + count <= self.entries
+
+        @def_method(m, self.alloc, ready=self.allocated != self.entries, **kwargs)
+        def _(count):
+            new_end_idx = Signal.like(self.end_idx)
+            m.d.av_comb += new_end_idx.eq(mod_add(self.end_idx, self.entries, count, self.max_alloc))
+            m.d.sync += self.end_idx.eq(new_end_idx)
+            m.d.comb += alloc_count.eq(count)
+            return {
+                "idents": [mod_add(self.end_idx, self.entries, i, i) for i in range(self.max_alloc)],
+                "new_end_idx": new_end_idx,
+            }
+
+        kwargs = {}
+        if self.with_validate_arguments and self.max_free > 1:
+            kwargs["validate_arguments"] = lambda count: count <= self.allocated
+
+        @def_method(m, self.free, ready=self.allocated != 0, **kwargs)
+        def _(count):
+            new_start_idx = Signal.like(self.start_idx)
+            m.d.av_comb += new_start_idx.eq(mod_add(self.start_idx, self.entries, count, self.max_free))
+            m.d.sync += self.start_idx.eq(new_start_idx)
+            m.d.comb += free_count.eq(count)
+            return {
+                "idents": [mod_add(self.start_idx, self.entries, i, i) for i in range(self.max_free)],
+                "new_start_idx": new_start_idx,
+            }
+
+        @def_method(m, self.clear)
+        def _():
+            m.d.sync += self.start_idx.eq(0)
+            m.d.sync += self.end_idx.eq(0)
+            m.d.sync += self.allocated.eq(0)
+
+        return m

transactron/lib/fifo.py

@@ -4,6 +4,7 @@
 import amaranth.lib.data as data
 from amaranth_types import ShapeLike, ValueLike, SrcLoc
 from transactron import Method, def_method, Priority, TModule
+from transactron.lib.allocators import CircularAllocator
 from transactron.utils.typing import MethodLayout, MethodStruct
 from transactron.utils.amaranth_ext import mod_incr, rotate_vec_right, rotate_vec_left
 from transactron.utils.amaranth_ext.functions import const_of
@@ -108,50 +109,39 @@ def __init__(self, layout: MethodLayout, depth: int, *, src_loc: int | SrcLoc =
     def elaborate(self, platform):
         m = TModule()
 
-        next_read_idx = Signal.like(self.read_idx)
-        m.d.comb += next_read_idx.eq(mod_incr(self.read_idx, self.depth))
+        m.submodules.allocator = allocator = CircularAllocator(self.depth)
+        m.d.comb += self.read_idx.eq(allocator.start_idx)
+        m.d.comb += self.write_idx.eq(allocator.end_idx)
+        m.d.comb += self.level.eq(allocator.allocated)
 
         m.submodules.data = self.data
         data_wrport = self.data.write_port()
         data_rdport = self.data.read_port(domain="sync", transparent_for=[data_wrport])
 
-        read_ready = Signal()
-        write_ready = Signal()
-
-        m.d.comb += read_ready.eq(self.level != 0)
-        m.d.comb += write_ready.eq(self.level != self.depth)
-
-        with m.If(self.read.run & ~self.write.run):
-            m.d.sync += self.level.eq(self.level - 1)
-        with m.If(self.write.run & ~self.read.run):
-            m.d.sync += self.level.eq(self.level + 1)
-        with m.If(self.clear.run):
-            m.d.sync += self.level.eq(0)
-
-        m.d.comb += data_rdport.addr.eq(Mux(self.read.run, next_read_idx, self.read_idx))
+        m.d.comb += data_rdport.addr.eq(self.read_idx)
         m.d.comb += self.head.eq(data_rdport.data)
 
-        @def_method(m, self.write, ready=write_ready)
+        @def_method(m, self.write)
         def _(arg: MethodStruct) -> None:
             m.d.top_comb += data_wrport.addr.eq(self.write_idx)
             m.d.top_comb += data_wrport.data.eq(arg)
             m.d.comb += data_wrport.en.eq(1)
 
-            m.d.sync += self.write_idx.eq(mod_incr(self.write_idx, self.depth))
+            allocator.alloc(m, count=1)
 
-        @def_method(m, self.read, read_ready)
+        @def_method(m, self.read)
         def _() -> ValueLike:
-            m.d.sync += self.read_idx.eq(next_read_idx)
+            ret = allocator.free(m, count=1)
+            m.d.comb += data_rdport.addr.eq(ret.new_start_idx)
             return self.head
 
-        @def_method(m, self.peek, read_ready, nonexclusive=True)
+        @def_method(m, self.peek, allocator.free.ready, nonexclusive=True)
         def _() -> ValueLike:
             return self.head
 
         @def_method(m, self.clear)
         def _() -> None:
-            m.d.sync += self.read_idx.eq(0)
-            m.d.sync += self.write_idx.eq(0)
+            allocator.clear(m)
 
         return m
 

transactron/utils/amaranth_ext/functions.py

@@ -1,6 +1,7 @@
 from typing import Any
 from amaranth import *
 from amaranth.hdl import ShapeCastable, ValueCastable
+from amaranth.hdl._ast import SwitchValue
 from amaranth.utils import bits_for, ceil_log2
 from amaranth.lib import data
 from collections.abc import Callable, Iterable, Mapping
@@ -11,6 +12,7 @@
 
 __all__ = [
     "mod_incr",
+    "mod_add",
     "popcount",
     "count_leading_zeros",
     "count_trailing_zeros",
@@ -28,15 +30,30 @@
 ]
 
 
-def mod_incr(sig: Value, mod: int) -> Value:
+def mod_incr(sig: ValueLike, mod: int) -> Value:
     """
     Perform `(sig+1) % mod` operation.
     """
-    if mod == 2 ** len(sig):
-        return sig + 1
+    assert mod > 0
+    sig = Value.cast(sig)
+    if not (mod & (mod - 1)):
+        return (sig + 1) & (mod - 1)
     return Mux(sig == mod - 1, 0, sig + 1)
 
 
+def mod_add(sig: ValueLike, mod: int, incr: ValueLike, max_incr: int):
+    """
+    Perform `(sig+incr) % mod` operation, for `0 < incr <= max_incr`.
+    """
+    assert mod > 0
+    assert max_incr >= 0
+    sig = Value.cast(sig)
+    incr = Value.cast(incr)
+    if not (mod & (mod - 1)):
+        return (sig + incr) & (mod - 1)
+    return SwitchValue(sig + incr, [(mod + i, i) for i in range(0, max_incr)] + [(None, sig + incr)])
+
+
 def popcount(s: Value):
     sum_layers = [s[i] for i in range(len(s))]