Round Robin oracle and eDSL

calyx-py/calyx/builder.py

@@ -1026,6 +1026,14 @@ def le_store_in_reg(
         cell = self.le(width, cellname, signed)
         return self.op_store_in_reg(cell, left, right, cell.name, 1, ans_reg)
 
+    def ge_store_in_reg(
+        self, left, right, ans_reg=None, cellname=None, width=None, signed=False
+    ):
+        """Inserts wiring into `self` to perform `reg := left >= right`."""
+        width = width or self.try_infer_width(width, left, right)
+        cell = self.ge(width, cellname, signed)
+        return self.op_store_in_reg(cell, left, right, cell.name, 1, ans_reg)
+
     def mult_store_in_reg(
         self, left, right, ans_reg=None, cellname=None, width=None, signed=False
     ):

calyx-py/calyx/gen_queue_data_expect.sh

@@ -26,3 +26,8 @@ done
 # use binheap_oracle to generate the expected output
 python3 queue_data_gen.py $num_cmds --use-rank > ../test/correctness/queues/binheap/stable_binheap.data
 cat ../test/correctness/queues/binheap/stable_binheap.data | python3 binheap_oracle.py $num_cmds $queue_size --keepgoing > ../test/correctness/queues/binheap/stable_binheap.expect
+
+# For the Round Robin queues, we drop piezo mode as well and use rrqueue_oracle to
+# generate the expected output
+python3 queue_data_gen.py 20 > ../test/correctness/queues/rr_queues/rr_queue.data
+cat ../test/correctness/queues/rr_queues/rr_queue.data | python3 rrqueue_oracle.py 20 $queue_size --keepgoing > ../test/correctness/queues/rr_queues/rr_queue.expect

calyx-py/calyx/queues.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass, field
-from typing import Any, List, Optional
+from typing import Any, Optional
 import heapq
 
 
@@ -152,7 +152,7 @@ def __len__(self) -> int:
 @dataclass(order=True)
 class RankValue:
     priority: int
-    value: Any=field(compare=False)
+    value: Any = field(compare=False)
 
 
 @dataclass
@@ -192,13 +192,104 @@ def __len__(self) -> int:
         return self.len
 
 
+@dataclass
+class RRQueue:
+    """
+    This is a version of a PIFO generalized to `n` flows, with a work conserving
+    round robin policy. If a flow is silent when it is its turn, that flow
+    simply skips its turn and the next flow is offered service.
+
+    Supports the operations `push`, `pop`, and `peek`.
+    It takes in a list `boundaries` that must be of length `n`, using which the
+    client can divide the incoming traffic into `n` flows.
+    For example, if n = 3 and the client passes boundaries [133, 266, 400],
+    packets will be divided into three flows: [0, 133], [134, 266], [267, 400].
+
+    - At push, we check the `boundaries` list to determine which flow to push to.
+    Take the boundaries example given earlier, [133, 266, 400].
+    If we push the value 89, it will end up in flow 0 becuase 89 <= 133,
+    and 305 would end up in flow 2 since 266 <= 305 <= 400.
+    - Pop first tries to pop from `hot`. If this succeeds, great. If it fails,
+    it increments `hot` and therefore continues to check all other flows
+    in round robin fashion.
+    - Peek allows the client to see which element is at the head of the queue
+    without removing it. Thus, peek works in a similar fashion to `pop`, except
+    `hot` is restored to its original value at the every end.
+    Further, nothing is actually dequeued.
+    """
+
+    def __init__(self, n, boundaries, max_len: int):
+        self.hot = 0
+        self.n = n
+        self.pifo_len = 0
+        self.boundaries = boundaries
+        self.data = [Fifo(max_len) for _ in range(n)]
+
+        self.max_len = max_len
+        assert (
+            self.pifo_len <= self.max_len
+        )  # We can't be initialized with a PIFO that is too long.
+
+    def push(self, val: int):
+        """Pushes `val` to the PIFO."""
+        if self.pifo_len == self.max_len:
+            raise QueueError("Cannot push to full PIFO.")
+        for fifo, boundary in zip(self.data, self.boundaries):
+            if val <= boundary:
+                fifo.push(val)
+                self.pifo_len += 1
+                break
+
+    def increment_hot(self):
+        """Increments `hot`, taking into account wraparound."""
+        self.hot = 0 if self.hot == (self.n - 1) else self.hot + 1
+
+    def pop(self) -> Optional[int]:
+        """Pops the PIFO by popping some internal FIFO.
+        Updates `hot` to be one more than the index of the internal FIFO that
+        we did pop.
+        """
+        if self.pifo_len == 0:
+            raise QueueError("Cannot pop from empty PIFO.")
+
+        while True:
+            try:
+                val = self.data[self.hot].pop()
+                if val is not None:
+                    self.increment_hot()
+                    self.pifo_len -= 1
+                    return val
+                self.increment_hot()
+            except QueueError:
+                self.increment_hot()
+
+    def peek(self) -> Optional[int]:
+        """Peeks into the PIFO. Does not affect what `hot` is."""
+        if self.pifo_len == 0:
+            raise QueueError("Cannot peek into empty PIFO.")
+
+        original_hot = self.hot
+        while True:
+            try:
+                val = self.data[self.hot].peek()
+                if val is not None:
+                    self.hot = original_hot
+                    return val
+                self.increment_hot()
+            except QueueError:
+                self.increment_hot()
+
+    def __len__(self) -> int:
+        return self.pifo_len
+
+
 def operate_queue(queue, max_cmds, commands, values, ranks=None, keepgoing=False):
     """Given the two lists, one of commands and one of values.
     Feed these into our queue, and return the answer memory.
     """
 
     ans = []
-    ranks_or_values = values if ranks == None else ranks
+    ranks_or_values = values if ranks is None else ranks
     for cmd, val, rnk in zip(commands, values, ranks_or_values):
         if cmd == 0:
             try:
@@ -218,7 +309,7 @@ def operate_queue(queue, max_cmds, commands, values, ranks=None, keepgoing=False
 
         elif cmd == 2:
             try:
-                if ranks == None:
+                if ranks is None:
                     queue.push(val)
                 else:
                     queue.push(rnk, val)

calyx-py/calyx/rrqueue_oracle.py

@@ -0,0 +1,18 @@
+# For usage, see gen_queue_data_expect.sh
+import sys
+import calyx.queues as queues
+from calyx import queue_util
+
+if __name__ == "__main__":
+    max_cmds, len = int(sys.argv[1]), int(sys.argv[2])
+    keepgoing = "--keepgoing" in sys.argv
+    commands, values, _ = queue_util.parse_json()
+
+    # Our Round Robin Queue (formerly known as generalized pifo) is simple: it 
+    # just orchestrates n FIFOs, in this case 3. It takes in a list of
+    # boundaries of length n (in this case 3).
+    pifo = queues.RRQueue(2, [200, 400], len)
+
+    ans = queues.operate_queue(pifo, max_cmds, commands, values, keepgoing=keepgoing)
+
+    queue_util.dump_json(ans, commands, values)

calyx-py/test/correctness/queues/rr_queues/rr_queue.data

@@ -0,0 +1,89 @@
+{
+  "commands": {
+    "data": [
+      2,
+      1,
+      2,
+      1,
+      2,
+      2,
+      2,
+      2,
+      0,
+      1,
+      0,
+      2,
+      0,
+      0,
+      0,
+      1,
+      1,
+      0,
+      1,
+      2
+    ],
+    "format": {
+      "is_signed": false,
+      "numeric_type": "bitnum",
+      "width": 2
+    }
+  },
+  "values": {
+    "data": [
+      52,
+      293,
+      127,
+      6,
+      374,
+      110,
+      208,
+      143,
+      93,
+      392,
+      199,
+      81,
+      390,
+      36,
+      71,
+      316,
+      316,
+      227,
+      64,
+      67
+    ],
+    "format": {
+      "is_signed": false,
+      "numeric_type": "bitnum",
+      "width": 32
+    }
+  },
+  "ans_mem": {
+    "data": [
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0
+    ],
+    "format": {
+      "is_signed": false,
+      "numeric_type": "bitnum",
+      "width": 32
+    }
+  }
+}

calyx-py/test/correctness/queues/rr_queues/rr_queue.expect

@@ -0,0 +1,68 @@
+{
+  "ans_mem": [
+    52,
+    52,
+    52,
+    374,
+    374,
+    127,
+    208,
+    110,
+    143,
+    143,
+    143,
+    81,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0
+  ],
+  "commands": [
+    2,
+    1,
+    2,
+    1,
+    2,
+    2,
+    2,
+    2,
+    0,
+    1,
+    0,
+    2,
+    0,
+    0,
+    0,
+    1,
+    1,
+    0,
+    1,
+    2
+  ],
+  "values": [
+    52,
+    293,
+    127,
+    6,
+    374,
+    110,
+    208,
+    143,
+    93,
+    392,
+    199,
+    81,
+    390,
+    36,
+    71,
+    316,
+    316,
+    227,
+    64,
+    67
+  ]
+}