Introduce Affine Controller Design

.github/workflows/python-package.yml

@@ -135,8 +135,8 @@ jobs:
         end_time=$(date +%s)
         duration=$((end_time - start_time))
         echo "Synthesis step duration: $duration seconds"
-        if [ $duration -gt 900 ]; then
-          echo "ERROR: Synthesis step took longer than 15 minutes!"
+        if [ $duration -gt 1800 ]; then
+          echo "ERROR: Synthesis step took longer than 30 minutes!"
           exit 1
         fi
 

cgra/test/CgraRTL_fir_test.py

@@ -1017,7 +1017,6 @@ def sim_fir_return(cmdline_opts, mem_access_is_combinational):
                                                         FuOutType(0), FuOutType(0), FuOutType(0), FuOutType(0),
                                                         FuOutType(0), FuOutType(0), FuOutType(0), FuOutType(0)]),
                                                      data = DataType(1, 1))),
-
           # Launch the tile.
           IntraCgraPktType(0, 0, payload = CgraPayloadType(CMD_LAUNCH))
       ],

doc/figures/loop_controller/README.md

@@ -0,0 +1,131 @@
+# Loop Controller (LC) Architecture
+
+## Overview
+
+The Loop Controller (LC) is a hardware module inside the CGRA Controller that manages **outer loop counters**. It works alongside the existing LoopCounter FU (DCU) on the tile array, which handles the innermost loop counting.
+
+![LC in CGRA Overview](loop_controller_hierarchy.png)
+
+
+## Where LC Sits in the Architecture
+
+```
+  CPU
+   │ CMD_LC_CONFIG_* (via NoC → Controller)
+   ▼
+┌──────────────────────────────────────────────────┐
+│                     CGRA                         │
+│                                                  │
+│  ┌──────────────────┐    ┌────────────────────┐  │
+│  │   Controller     │    │    Tile Array       │  │
+│  │  ┌────────────┐  │    │  ┌──────┐ ┌──────┐ │  │
+│  │  │  Crossbar  │  │    │  │Tile 0│ │Tile 1│ │  │
+│  │  └────────────┘  │    │  │(DCU) │ │(DCU) │ │  │
+│  │  ┌────────────┐  │    │  │Count │ │Deliv.│ │  │
+│  │  │GlobalReduce│  │    │  └──────┘ └──────┘ │  │
+│  │  └────────────┘  │    │  ┌──────┐ ┌──────┐ │  │
+│  │  ┌────────────┐  │    │  │Tile 2│ │Tile 3│ │  │
+│  │  │    Loop    │◄─┼────┼──│(FU)  │ │(FU)  │ │  │
+│  │  │ Controller │──┼────┼─►│      │ │      │ │  │
+│  │  │   (LC)     │  │    │  └──────┘ └──────┘ │  │
+│  │  └────────────┘  │    └────────────────────┘  │
+│  └──────────────────┘                            │
+│         ▲  │                                     │
+│         │  │  send_to_remote / recv_from_remote   │
+└─────────┼──┼─────────────────────────────────────┘
+          │  │
+          │  ▼
+    ┌─────────────┐
+    │  Other CGRA │
+    │  (with LC)  │
+    └─────────────┘
+```
+
+## Command Flow
+
+### 1. Configuration (CPU → Controller → LC)
+
+The CPU sends config commands via the NoC. The Controller routes them to the LC.
+
+| Command | Description | Sender → Receiver |
+|---------|-------------|-------------------|
+| `CMD_LC_CONFIG_LOWER` | Set loop lower bound | CPU → Controller → LC |
+| `CMD_LC_CONFIG_UPPER` | Set loop upper bound | CPU → Controller → LC |
+| `CMD_LC_CONFIG_STEP` | Set loop step | CPU → Controller → LC |
+| `CMD_LC_CONFIG_CHILD_COUNT` | Set required child completions | CPU → Controller → LC |
+| `CMD_LC_CONFIG_TARGET` | Register a target DCU | CPU → Controller → LC |
+| `CMD_LC_CONFIG_PARENT` | Set parent CCU relationship | CPU → Controller → LC |
+| `CMD_LC_LAUNCH` | Start all configured CCUs | CPU → Controller → LC |
+
+### 2. Dispatch (LC → Tile Array DCUs)
+
+When a CCU advances its loop variable, it dispatches commands to its target DCUs (1 command per target per cycle):
+
+| Command | Target Type | Description | Sender → Receiver |
+|---------|------------|-------------|-------------------|
+| `CMD_RESET_LEAF_COUNTER` | Leaf DCU (`OPT_LOOP_COUNT`) | Reset inner loop counter to start next iteration | LC → DCU (tile) |
+| `CMD_UPDATE_COUNTER_SHADOW_VALUE` | Delivery DCU (`OPT_LOOP_DELIVERY`) | Update shadow register with outer loop variable | LC → DCU (tile) |
+
+### 3. Completion (DCU → LC)
+
+When a leaf DCU finishes its inner loop, it sends a completion signal back to the LC:
+
+| Command | Description | Sender → Receiver |
+|---------|-------------|-------------------|
+| `CMD_LEAF_COUNTER_COMPLETE` | Inner loop finished | DCU (tile) → LC |
+
+### 4. Cross-CGRA Communication (LC ↔ LC)
+
+For multi-CGRA loop nesting, LCs communicate via the inter-CGRA NoC:
+
+| Command | Description | Sender → Receiver |
+|---------|-------------|-------------------|
+| `CMD_RESET_LEAF_COUNTER` | Reset remote DCU | LC (CGRA-0) → NoC → DCU (CGRA-1) |
+| `CMD_UPDATE_COUNTER_SHADOW_VALUE` | Update remote shadow | LC (CGRA-0) → NoC → DCU (CGRA-1) |
+| `CMD_LC_CHILD_COMPLETE` | Remote loop finished | LC (CGRA-1) → NoC → LC (CGRA-0) |
+
+## Internal Structure: CCU DAG
+
+```
+Example: for(i) for(j) for(k) body(i,j,k)
+
+  ┌──────────────┐
+  │  CCU[0]      │  i = 0..N (root)
+  │  child_cnt=1 │
+  └──────┬───────┘
+         │ internal completion
+  ┌──────▼───────┐
+  │  CCU[1]      │  j = 0..M (parent=CCU[0])
+  │  child_cnt=1 │
+  └──────┬───────┘
+         │ targets
+    ┌────┴────┐
+    ▼         ▼
+ ┌─────┐  ┌─────┐
+ │DCU-A│  │DCU-B│
+ │Count│  │Deliv│  (on tile array)
+ │k=0.K│  │j val│
+ └─────┘  └─────┘
+```
+
+- **CCU[0]** (root): Manages `i`. Target = delivery DCU for `i` value (shadow_only).
+- **CCU[1]**: Manages `j`. Parent = CCU[0]. Targets = leaf DCU for `k` loop (reset) + delivery DCU for `j` value (shadow_only).
+- When CCU[1] completes (j reaches bound), it **internally notifies** CCU[0] in the same cycle.
+- When CCU[0] finishes dispatch, it **auto-resets** CCU[1] back to `j = lower_bound`.
+
+## CCU State Machine
+
+```
+        CMD_LC_LAUNCH
+  IDLE ──────────────→ RUNNING ◄────────────────┐
+                          │                      │
+                 child completions               │
+                 count >= threshold              │
+                          │                      │
+                          ▼                      │
+                    ┌──────────┐   all targets   │
+   value >= upper   │DISPATCHING│──dispatched───→─┘
+   ──────────→      └──────────┘
+  COMPLETE            (1 cmd/cycle/target)
+  (no dispatch)
+```

fu/single/LoopCounterRTL.py

@@ -5,17 +5,25 @@
 Loop Counter (DCU) for CGRA tile.
 
 This FU manages loop counters indexed by ctrl_addr from control memory.
-Each ctrl_addr has:
+
+NOTE: `ctrl_addr` serves as a "Context ID" or "Loop ID" multiplexer.
+If ctrl_mem_size > 1, a single LoopCounter (DCU) can support MULTIPLE independent loops
+simultaneously by mapping each loop's state to a different `ctrl_addr`.
+In a spatial-only CGRA (where ctrl_mem_size == 1), this DCU only has 1 ctrl_addr 
+and thus can only support ONE loop. To support nested loops in spatial-only CGRAs,
+different loops must be mapped to different tiles.
+
+Each ctrl_addr (loop context) has:
 - Leaf counter state (lower_bound, upper_bound, step, current_value)
-- Shadow register (for relay/root counter values from AC)
+- Shadow register (for relay/root counter values from LC)
 
 Supports two operation modes per ctrl_addr:
 1. OPT_LOOP_COUNT: Loop-Driven Mode (Leaf counter execution)
 2. OPT_LOOP_DELIVERY: Loop-Delivery Mode (Shadow register output)
 
 Configuration methods:
-1. Initial config (via ConstQueue): Configure leaf counter parameters
-2. Runtime updates (via AC): Reset leaf counter or update shadow register
+1. Initial config (via Controller): Configure leaf counter parameters
+2. Runtime updates (via LC): Reset leaf counter or update shadow register
 
 Author : Shangkun Li
   Date : January 27, 2026
@@ -55,7 +63,7 @@ def construct(s, CtrlPktType, num_inports, num_outports, vector_factor_power = 0
     s.current_ctrl_addr = Wire(s.CtrlAddrType)
     s.loop_terminated = Wire(1)
 
-    # Update triggers from AC (CMD).
+    # Update triggers from LC (CMD).
     s.cmd_reset_counter = Wire(1)
     s.cmd_update_shadow = Wire(1)
     s.cmd_config_lower = Wire(1)
@@ -138,7 +146,7 @@ def comb_logic():
             s.send_out[0].val @= b1(0)
             s.recv_opt.rdy @= b1(0)
 
-      # ===== Handle messages from AC (CMD updates) =====
+      # ===== Handle messages from LC (CMD updates) =====
       if s.recv_from_ctrl_mem.val:
         s.recv_from_ctrl_mem.rdy @= b1(1)
         s.target_ctrl_addr @= s.recv_from_ctrl_mem.msg.ctrl_addr
@@ -190,7 +198,7 @@ def update_leaf_counters():
                s.leaf_current_value[addr].payload + s.leaf_step[addr].payload, b1(1)
              )
 
-        # Runtime reset from AC.
+        # Runtime reset from LC.
         if s.cmd_reset_counter:
           addr = s.target_ctrl_addr
           s.leaf_current_value[addr] <<= s.leaf_lower_bound[addr]
@@ -202,7 +210,7 @@ def update_shadow_registers():
           s.shadow_regs[i] <<= s.DataType(0, 0)
           s.shadow_valid[i] <<= b1(0)
       else:
-        # Runtime update from AC.
+        # Runtime update from LC.
         if s.cmd_update_shadow:
           addr = s.target_ctrl_addr
           s.shadow_regs[addr] <<= s.target_ctrl_data
@@ -224,7 +232,7 @@ def update_already_done():
           addr = s.current_ctrl_addr
           s.already_done[addr] <<= b1(1)
 
-        # Resets done flag when counter is reset from AC.
+        # Resets done flag when counter is reset from LC.
         if s.cmd_reset_counter:
           addr = s.target_ctrl_addr
           s.already_done[addr] <<= b1(0)

lib/cmd_type.py

@@ -14,7 +14,7 @@
 
 # Total number of commands that are supported/recognized by controller.
 # Needs to be updated once more commands are added/supported.
-NUM_CMDS = 32
+NUM_CMDS = 43
 
 CMD_LAUNCH                           = 0
 CMD_PAUSE                            = 1
@@ -42,12 +42,29 @@
 CMD_CONFIG_STREAMING_LD_START_ADDR   = 23
 CMD_CONFIG_STREAMING_LD_STRIDE       = 24
 CMD_CONFIG_STREAMING_LD_END_ADDR     = 25
-CMD_UPDATE_COUNTER_SHADOW_VALUE      = 26  # Updates shadow registers value from AC.
-CMD_RESET_LEAF_COUNTER               = 27  # Resets leaf counter to lower_bound.
+CMD_UPDATE_COUNTER_SHADOW_VALUE      = 26  # LC -> Target Tile (DCU): update shadow register
+CMD_RESET_LEAF_COUNTER               = 27  # LC -> Target Tile (DCU): reset counter to lower_bound
 CMD_CONFIG_LOOP_LOWER                = 28
 CMD_CONFIG_LOOP_UPPER                = 29
 CMD_CONFIG_LOOP_STEP                 = 30
-CMD_LEAF_COUNTER_COMPLETE            = 31
+CMD_LEAF_COUNTER_COMPLETE            = 31  # Target Tile (DCU) -> LC: innermost loop finished
+
+# Loop Controller (LC) Configuration Commands (from Controller).
+CMD_LC_CONFIG_LOWER                  = 32  # Controller -> LC: Configures CCU lower_bound
+CMD_LC_CONFIG_UPPER                  = 33  # Controller -> LC: Configures CCU upper_bound
+CMD_LC_CONFIG_STEP                   = 34  # Controller -> LC: Configures CCU step
+CMD_LC_CONFIG_CHILD_COUNT            = 35  # Controller -> LC: Configures child_complete_count
+CMD_LC_CONFIG_TARGET                 = 36  # Controller -> LC: Configures target (tile_id, ctrl_addr, is_remote, cgra_id)
+CMD_LC_CONFIG_PARENT                 = 37  # Controller -> LC: Configures parent_ccu_id, is_root, is_relay
+CMD_LC_LAUNCH                        = 38  # Controller -> LC: Launches LC (all CCUs enter RUNNING)
+
+# Loop Controller Inter-CGRA Sync Commands.
+CMD_LC_SYNC_VALUE                    = 39  # Parent LC (this CGRA) -> Child LC (another CGRA): sync current value
+CMD_LC_CHILD_COMPLETE                = 40  # Child LC (another CGRA) -> Parent LC (this CGRA): child complete
+CMD_LC_CHILD_RESET                   = 41  # Parent LC (this CGRA) -> Child LC (another CGRA): reset child
+
+# Loop Controller Status.
+CMD_LC_ALL_COMPLETE                  = 42  # LC -> Controller: all outer loops complete
 
 CMD_SYMBOL_DICT = {
   CMD_LAUNCH:                           "(LAUNCH_KERNEL)",
@@ -82,5 +99,16 @@
   CMD_CONFIG_LOOP_UPPER:                "(CONFIG_LOOP_UPPER)",
   CMD_CONFIG_LOOP_STEP:                 "(CONFIG_LOOP_STEP)",
   CMD_LEAF_COUNTER_COMPLETE:            "(LEAF_COUNTER_COMPLETE)",
+  CMD_LC_CONFIG_LOWER:                  "(LC_CONFIG_CCU_LOWER)",
+  CMD_LC_CONFIG_UPPER:                  "(LC_CONFIG_CCU_UPPER)",
+  CMD_LC_CONFIG_STEP:                   "(LC_CONFIG_CCU_STEP)",
+  CMD_LC_CONFIG_CHILD_COUNT:            "(LC_CONFIG_CCU_CHILD_COUNT)",
+  CMD_LC_CONFIG_TARGET:                 "(LC_CONFIG_CCU_TARGET)",
+  CMD_LC_CONFIG_PARENT:                 "(LC_CONFIG_CCU_PARENT)",
+  CMD_LC_LAUNCH:                        "(LC_LAUNCH)",
+  CMD_LC_SYNC_VALUE:                    "(LC_SYNC_VALUE)",
+  CMD_LC_CHILD_COMPLETE:                "(LC_CHILD_COMPLETE)",
+  CMD_LC_CHILD_RESET:                   "(LC_CHILD_RESET)",
+  CMD_LC_ALL_COMPLETE:                  "(LC_ALL_COMPLETE)",
 }