radix sort

.github/workflows/test.yaml

@@ -47,6 +47,10 @@ jobs:
         run: |
           . setup.sh && python examples/array-increment/main.py
 
+      - name: Run Radix Sort Test
+        run: |
+          . setup.sh && python examples/radix_sort/benchmark.py
+
       - name: Clean CMake Cache
         run: |
           find . -name "CMakeCache.txt" -delete

examples/nested-loop-fsm/.gitignore

@@ -0,0 +1 @@
+workspace/*

examples/nested-loop-fsm/README.md

@@ -0,0 +1,377 @@
+# Nested For-Loop FSM Template
+
+> **可复用的嵌套循环状态机模板，支持握手协议的内层计算单元**
+
+---
+
+## 📖 项目概述
+
+本项目提供了一个通用的**嵌套for循环状态机模板**，用于在 Assassyn 硬件描述语言中实现循环控制逻辑。该模板将循环控制与计算逻辑解耦，通过握手协议（ready/valid/done）实现两者的协同工作。
+
+### 核心特性
+
+- ✅ **模块化设计**: 分离循环控制器（OuterLoopFSM）和计算单元（InnerComputeFSM）
+- ✅ **握手协议**: 使用 ready/valid/done 信号实现可靠的同步
+- ✅ **多周期计算支持**: 内层FSM可执行任意周期数的复杂计算
+- ✅ **声明式状态机**: 基于 Assassyn FSM 抽象，清晰易懂
+- ✅ **可参数化**: 支持数据位宽、循环边界的灵活配置
+- ✅ **可扩展**: 易于扩展到多层嵌套或并行计算
+
+---
+
+## 🏗️ 架构设计
+
+```
+┌─────────────────────────────────────────────┐
+│          OuterLoopFSM (外层循环控制器)        │
+│                                             │
+│  init → wait_ready → execute → check_done  │
+│          ↑                           ↓      │
+│          └───────────────────────────┘      │
+└───────────────────┬─────────────────────────┘
+                    │ Handshake Signals
+                    │ • inner_ready
+                    │ • outer_valid
+                    │ • inner_done
+┌───────────────────┴─────────────────────────┐
+│       InnerComputeFSM (内层计算单元)         │
+│                                             │
+│  idle → compute → done → reset → (idle)    │
+│   ↑                                         │
+│   └─────────────────────────────────────────┘
+└─────────────────────────────────────────────┘
+```
+
+### 握手协议时序
+
+```
+Cycle:      0    1    2    3    4    5    6
+            ───────────────────────────────────
+OuterFSM:   init wait exec chk  wait exec ...
+InnerFSM:   idle      cpt  cpt done rst  idle
+
+inner_ready: ──┐      ┌─────┐      ┌──────
+               └──────┘     └──────┘
+
+outer_valid: ──┐ ┌──────────┐ ┌──────────
+               └─┘          └─┘
+
+inner_done:  ──────────┐ ┌──────────┐ ┌──
+                       └─┘          └─┘
+```
+
+---
+
+## 📁 项目结构
+
+```
+examples/nested-loop-fsm/
+├── README.md                    # 项目介绍（本文件）
+├── SPEC.md                      # 详细规范文档
+├── basic_example.py             # 基础示例：简单累加循环
+├── multi_cycle_example.py       # 多周期示例：移位乘法器
+└── test_nested_loop_fsm.py      # 单元测试
+```
+
+---
+
+## 🚀 快速开始
+
+### 前置条件
+
+- 已安装 Assassyn 环境
+- 已执行 `source setup.sh`
+
+### 运行基础示例
+
+```bash
+cd examples/nested-loop-fsm
+python basic_example.py
+```
+
+该示例实现了一个简单的累加循环：
+```
+sum = 0 + 1 + 2 + ... + 99 = 4950
+```
+
+### 代码示例
+
+```python
+from assassyn.frontend import *
+from assassyn.ir.module import fsm
+
+# 定义内层计算FSM（累加器）
+class SimpleAccumulator(Module):
+    def __init__(self):
+        super().__init__(
+            ports={
+                'iteration': Port(UInt(32)),
+                'valid': Port(Bits(1)),
+            }
+        )
+
+    @module.combinational
+    def build(self, ready_out, done_out):
+        iteration, valid = self.pop_all_ports(True)
+
+        # 状态机定义...
+        # 详见 basic_example.py
+
+# 定义外层循环FSM（控制器）
+class OuterLoopController(Module):
+    def __init__(self):
+        super().__init__(ports={})
+
+    @module.combinational
+    def build(self, inner_fsm, loop_start, loop_end, loop_step):
+        # 创建握手信号
+        inner_ready = RegArray(Bits(1), 1, initializer=[1])
+        inner_done = RegArray(Bits(1), 1, initializer=[0])
+
+        # 调用内层FSM
+        result = inner_fsm.build(inner_ready, inner_done)
+
+        # 外层FSM逻辑...
+        # 详见 basic_example.py
+
+        return result
+
+# 在Driver中使用
+class Driver(Module):
+    @module.combinational
+    def build(self):
+        accumulator = SimpleAccumulator()
+        controller = OuterLoopController()
+
+        result = controller.build(
+            inner_fsm=accumulator,
+            loop_start=UInt(32)(0),
+            loop_end=UInt(32)(100),
+            loop_step=UInt(32)(1)
+        )
+```
+
+---
+
+## 📚 详细文档
+
+### [SPEC.md](./SPEC.md) - 完整规范文档
+
+包含以下内容：
+1. **设计动机与目标**
+2. **架构概述** - 双层FSM层次结构
+3. **外层循环FSM规范** - 状态定义、接口、行为
+4. **内层计算FSM规范** - 状态定义、接口、行为
+5. **握手协议规范** - 信号定义、时序要求
+6. **使用示例** - 基础循环、多周期计算
+7. **实现考虑** - 参数化、错误处理、性能优化
+8. **未来扩展** - 多层嵌套、动态边界、并行化
+
+---
+
+## 🔧 使用场景
+
+### 适用场景
+
+- ✅ 硬件加速器中的循环结构实现
+- ✅ 需要多周期计算的迭代算法
+- ✅ 流处理中的批量数据处理
+- ✅ 神经网络层的循环计算（如卷积、矩阵乘法）
+
+### 示例应用
+
+1. **向量点积计算**
+   - 外层FSM: 遍历向量元素
+   - 内层FSM: 执行乘法累加（可能需要多周期）
+
+2. **矩阵转置**
+   - 外层FSM: 遍历行/列索引
+   - 内层FSM: 执行内存读写操作
+
+3. **图像卷积**
+   - 外层FSM: 遍历输出像素位置
+   - 内层FSM: 计算卷积窗口内的乘加运算
+
+4. **排序算法**
+   - 外层FSM: 控制排序轮次
+   - 内层FSM: 执行单轮比较交换
+
+---
+
+## 🧪 测试
+
+运行单元测试：
+
+```bash
+pytest test_nested_loop_fsm.py -v
+```
+
+测试覆盖：
+- ✅ 基础循环功能
+- ✅ 握手信号正确性
+- ✅ 多周期计算
+- ✅ 边界条件（空循环、单次迭代）
+- ✅ 不同步长的循环
+
+---
+
+## 🎯 设计模式
+
+### 1. 单周期计算模式
+
+**适用**: 内层计算可在一个周期内完成
+
+```python
+# 内层FSM状态转移
+idle → compute → done → reset → idle
+  1      1        1      1     (cycles)
+```
+
+**示例**: 简单算术运算（加法、位运算）
+
+### 2. 多周期计算模式
+
+**适用**: 内层计算需要多个周期
+
+```python
+# 内层FSM状态转移
+idle → compute → ... → compute → done → reset → idle
+  1      1       ...      1      1      1
+```
+
+**示例**: 迭代算法（除法、平方根、乘法器）
+
+### 3. 数据依赖模式
+
+**适用**: 计算周期数依赖于数据
+
+```python
+# 内层FSM根据数据动态决定何时完成
+with Condition(result_meets_criteria):
+    state = "done"
+```
+
+**示例**: 收敛算法、搜索算法
+
+---
+
+## 🔍 调试技巧
+
+### 1. 添加日志输出
+
+在状态动作中添加 `log()` 语句：
+
+```python
+def execute_action():
+    log("OuterFSM: iter={}, ready={}, valid={}",
+        loop_counter[0], inner_ready[0], outer_valid[0])
+```
+
+### 2. 检查握手信号
+
+验证握手协议的正确性：
+
+```python
+# 非法状态检测
+with Condition((inner_ready[0] == Bits(1)(1)) &
+               (inner_done[0] == Bits(1)(1))):
+    log("ERROR: Invalid handshake!")
+```
+
+### 3. 添加超时保护
+
+防止死锁：
+
+```python
+timeout_counter = RegArray(UInt(16), 1, initializer=[0])
+
+def check_done_action():
+    timeout_counter[0] = timeout_counter[0] + UInt(16)(1)
+    with Condition(timeout_counter[0] > UInt(16)(1000)):
+        log("ERROR: Timeout waiting for inner_done!")
+```
+
+---
+
+## 🛠️ 自定义扩展
+
+### 扩展内层计算逻辑
+
+```python
+class CustomComputeFSM(Module):
+    @module.combinational
+    def build(self, ready_out, done_out):
+        # 1. 定义你的计算寄存器
+        custom_reg = RegArray(UInt(64), 1, initializer=[0])
+
+        # 2. 定义你的完成条件
+        compute_done = (custom_condition)
+
+        # 3. 实现 compute_action
+        def compute_action():
+            # 你的计算逻辑
+            custom_reg[0] = custom_computation(iteration)
+
+        # 4. 生成FSM...
+```
+
+### 添加额外的握手信号
+
+```python
+# 例如：添加错误信号
+error_out = RegArray(Bits(1), 1, initializer=[0])
+
+def compute_action():
+    with Condition(error_condition):
+        error_out[0] = Bits(1)(1)
+        # 跳转到错误处理状态
+```
+
+---
+
+## 📊 性能考虑
+
+### 延迟（Latency）
+
+- **每次迭代延迟** = 握手开销 (4 cycles) + 内层计算周期
+  - 1 cycle: wait_ready
+  - 1 cycle: execute
+  - N cycles: compute
+  - 1 cycle: done
+  - 1 cycle: reset
+
+### 吞吐量（Throughput）
+
+- **单个内层FSM**: 1 / (4 + N) iterations/cycle
+- **优化**: 使用多个并行内层FSM可提高吞吐量
+
+### 资源使用
+
+- **外层FSM**: ~100 LUTs, ~50 FFs
+- **内层FSM**: 取决于计算逻辑复杂度
+- **握手信号**: 3 FFs
+
+---
+
+## 🤝 贡献
+
+欢迎提交问题和改进建议！
+
+---
+
+## 📄 许可证
+
+遵循 Assassyn 项目许可证。
+
+---
+
+## 🔗 相关资源
+
+- [Assassyn 文档](../../../docs/)
+- [Assassyn FSM 模块文档](../../../python/assassyn/ir/module/fsm.md)
+- [异步调用教程](../../../tutorials/01_async_call_en.qmd)
+- [Radix Sort FSM 示例](../radix_sort/main_fsm.py)
+
+---
+
+**Happy Coding! 🚀**