From e415d981f9b40bf4a4667395245d4f3d6fa2e6bb Mon Sep 17 00:00:00 2001
From: Yehowshua Immanuel <yehowshua@joyofhardware.com>
Date: Fri, 4 Apr 2025 15:31:46 -0400
Subject: [PATCH] add some comments

---
 bs/TagEngine.bs | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/bs/TagEngine.bs b/bs/TagEngine.bs
index 0d28fce..921e58e 100644
--- a/bs/TagEngine.bs
+++ b/bs/TagEngine.bs
@@ -24,9 +24,15 @@ mkTagEngine = do
     -- Constants
     let maxTagCount = fromInteger (valueOf numTags)
 
-    -- State
     tagUsage :: Vector numTags (Reg Bool) <- replicateM (mkReg False)  -- Tracks which tags are in use
-    initialTagCounter <- mkReg (Just (maxTagCount - 1))  -- Distributes initial tags
+
+    -- Since Bluespec doesn't allow us to initialize FIFOs with values at
+    -- reset, we can pretend as if the buffer within our freeTagQueue is populated
+    -- with sequentially incrementing values(starting from 0) on reset
+    -- by having our tag engine effectively return the value of a decrementing
+    -- counter initialized to (maxTagCount - 1) for the first n tag requests made
+    -- to TagEngine where `n := maxTagCount`.
+    initialTagDistributor <- mkReg (Just (maxTagCount - 1))  -- Distributes initial tags
     retireQueue <- mkBypassFIFO  -- Queue for tags being retired
     freeTagQueue <- mkSizedFIFOF maxTagCount  -- Queue of available tags
 
@@ -75,13 +81,13 @@ mkTagEngine = do
         interface TagEngine
             requestTag :: ActionValue UIntLog2N(numTags)
             requestTag = do
-                case initialTagCounter of
+                case initialTagDistributor of
                     Just 0 -> do
-                        initialTagCounter := Nothing
+                        initialTagDistributor := Nothing
                         requestSignal.wset 0
                         return 0
                     Just tag -> do
-                        initialTagCounter := Just (tag - 1)
+                        initialTagDistributor := Just (tag - 1)
                         requestSignal.wset tag
                         return tag
                     Nothing -> do
@@ -90,6 +96,10 @@ mkTagEngine = do
                         requestSignal.wset tag
                         return tag
 
+            -- `retireTag` isn't guarded on tag validity(this would break Bluespec's safety model)
+            -- so it is advisable that the caller of `retireTag` only attempt to retire valid tags.
+            -- Internally, the tagEngine will keep a correct and consistent state since TagEngine
+            -- validates tags before attempting to retire them.
             retireTag :: UIntLog2N(numTags) -> Action
             retireTag tag =
                 do