feat: add hardware retrieval cycle performance measurement

Add cycle-level performance measurement for hardware CAM retrieval benchmarks
to complement existing quality metrics.

- Add query_topk_once_with_latency with accept→first/last cycle timing
- Add QueryTiming dataclass and summarize_query_timings helper
- Integrate cycle performance into benchmark outputs (CSV + Markdown)
- Log RETRIEVAL_PERF_RESULT with cycles/query and queries/cycle
- Update experiment docs with hardware cycle performance section
- Add unit tests for summarize_query_timings and output writers

docs/exps/sw_hw_cam_retrieval_benchmark.md

@@ -1,8 +1,8 @@
 # 软件/硬件 CAM 检索基准实验总结
 
 **日期**：2026-05-27  
-**工作区**：`.workspace/feat_sw_retrieval_benchmark`  
-**目标**：对比同一组 CAM 检索数据在硬件仿真与软件汉明距离检索下的检索质量，并记录软件检索速度基线。
+**工作区**：`/home/sikongjueluo/Projects/Mini-Nav`  
+**目标**：对比同一组 CAM 检索数据在硬件仿真与软件汉明距离检索下的检索质量，并记录软件检索速度基线与硬件仿真周期性能。
 
 ## 1. 实验配置
 
@@ -37,6 +37,12 @@ just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retr
 
 硬件噪声扫描数据来自远端已有 Cocotb/Verilator 输出与 `docs/exps/cam_retrieval_noise_sweep_*.md`。
 
+硬件检索周期检测命令：
+
+```bash
+just cam-test-retrieval-artifact outputs/cam_retrieval_benchmark/datasets/cifar10_hash512_rows512_queries128.npz 512
+```
+
 ## 2. 软件检索速度与质量
 
 软件路径只计时 Top-K 匹配阶段，不包含 `.npz` 加载、指标聚合和结果写盘。
@@ -119,7 +125,51 @@ just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retr
 - 50% 噪声后检索基本不可用。
 - 与 CIFAR-10 相同，Golden Match@5 在低噪声下也迅速接近 0，说明精确排序比类别命中率更脆弱。
 
-## 5. 指标解释
+## 5. 硬件检索周期性能
+
+本次已将硬件周期检测合并进真实 `.npz` 检索数据集的 Cocotb/Verilator
+benchmark。实现位置：
+
+- `hw/sim/tests/top/utils.py::query_topk_once_with_latency`
+- `hw/sim/benchmarks/retrieval/test_retrieval_benchmark.py::cam_retrieval_benchmark`
+
+周期口径如下：
+
+| 指标 | 含义 |
+|---|---|
+| `accept_to_first_result_cycles` | query 被 `query_valid && query_ready` 接受后，到首个 `result_valid` beat 的周期数。 |
+| `accept_to_last_result_cycles` | query 被接受后，到 `result_last` 断言的周期数，即完整 Top-K 串行结果输出完成。 |
+| `total_query_cycles` | 从拉高 `query_valid` 到 Top-K 输出完成的完整事务周期数。 |
+| `cycles_per_query` | 当前报告中的主指标，等于平均 `accept_to_last_result_cycles`。 |
+| `queries_per_cycle` | `num_queries / total_query_cycles`，用于观察仿真事务吞吐率。 |
+
+选择 `accept_to_last_result_cycles` 作为主 `cycles_per_query` 的原因是：Top-K
+检索只有在串行结果流输出到 `result_last` 后才算完整完成；仅用首个
+`result_valid` 会低估实际 Top-K 检索事务成本。
+
+### CIFAR-10 无噪声硬件周期结果
+
+配置：512 rows × 128 queries × 512-bit hash，`TOPK_K=5`，`LANES=8`，
+`WRITE_NOISE_EN=0`。
+
+| 数据集 | 模式 | 查询数 | accept→first | accept→last / cycles/query | total query cycles | queries/cycle | 状态 |
+|---|---|---:|---:|---:|---:|---:|---|
+| CIFAR-10 | hardware no-noise | 128 | 1027.000000 | 1031.000000 | 132096 | 0.000968992 | pass |
+
+对应日志标记：
+
+```text
+RETRIEVAL_PERF_RESULT mode=no_noise num_queries=128 cycles_per_query=1031.000000 accept_to_first_result_cycles=1027.000000 accept_to_last_result_cycles=1031.000000 total_query_cycles=132096 queries_per_cycle=0.000968992 status=pass
+```
+
+该结果说明：在当前 `NUM_ROWS=512, LANES=8, TOPK_K=5` 的硬件仿真配置下，
+一次完整 Top-K 检索事务约为 **1031 cycles/query**。首个结果 beat 约在
+1027 cycles 后出现，完整 Top-K 输出额外消耗约 4 个周期。
+
+> 注：以上数据来自 Verilator/Cocotb 仿真，不是 FPGA 板上实测。它可用于
+> 架构级周期趋势分析，但不能直接等同于板级频率、吞吐或端到端系统延迟。
+
+## 6. 指标解释
 
 | 指标 | 含义 |
 |---|---|
@@ -130,8 +180,10 @@ just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retr
 | Golden Match@K / `exact_match_rate` | Top-K row index 列表是否与参考模型完全一致。该指标比 Hit@K 更严格。 |
 | `ns_per_query` | 软件 Top-K 匹配阶段平均耗时；不含加载和写盘。 |
 | `queries_per_second` | 软件 Top-K 匹配阶段吞吐率。 |
+| `cycles_per_query` | 硬件仿真中一次完整 Top-K 检索事务的平均周期数，当前采用 accept→last 口径。 |
+| `queries_per_cycle` | 硬件仿真中完成 query 数除以总 query 事务周期数。 |
 
-## 6. 当前结论
+## 7. 当前结论
 
 1. **软件汉明距离基线已可作为硬件 CAM 检索的功能参考。**  
    在无噪声条件下，硬件仿真和软件基线的质量指标及 Golden Match 均一致。
@@ -139,8 +191,9 @@ just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retr
 2. **当前软件基线速度约为 4.86k queries/s。**  
    该结果来自 Python integer brute-force Hamming scan，数据规模为 512 rows × 128 queries × 512 bits。
 
-3. **硬件检索质量基准目前主要报告质量指标，不报告 cycles/query。**  
-   现有硬件性能基准中已有 cycle 统计逻辑，但尚未和真实 retrieval dataset 的 Top-K benchmark 合并。因此本文不报告硬件 query/s 或 cycles/query。
+3. **硬件检索质量基准现在已经报告 cycles/query。**  
+   在 CIFAR-10 512-row/128-query 无噪声配置下，完整 Top-K 检索为
+   **1031 cycles/query**，首个结果为 **1027 cycles/query**。
 
 4. **写噪声对精确排序影响显著。**  
    即使 Hit@K 保持较高，Golden Match@K 也会快速下降，说明噪声首先破坏精确排序，再进一步破坏类别命中。
@@ -148,13 +201,13 @@ just remote "python scripts/sw_retrieval_benchmark.py --dataset outputs/cam_retr
 5. **CIFAR-100 比 CIFAR-10 更能体现检索难度。**  
    在无噪声下 CIFAR-100 的 Hit@1/Hit@5 分别为 0.695312/0.867188，明显低于 CIFAR-10 的 1.0/1.0，更适合作为后续检索质量对比主数据集。
 
-## 7. 后续建议
+## 8. 后续建议
 
-1. 将 `hw/sim/tests/perf/test_cam_perf.py::query_once_with_latency` 的周期测量逻辑合并到 retrieval benchmark，记录真实数据集上的 `cycles/query`。
+1. 对 CIFAR-100 也运行同样的硬件周期检测，补齐与软件质量表同尺度的硬件周期表。
 2. 在 `docs/exps` 中继续维护：
    - 软件检索速度表；
    - 硬件无噪声一致性表；
    - 硬件噪声鲁棒性表；
-   - 后续硬件 `cycles/query` 表。
+   - 硬件 `cycles/query` 表。
 3. 对软件基线补充 NumPy/PyTorch vectorized Hamming scan，以区分“朴素 Python baseline”和“优化软件 baseline”。
 4. 增加 `NUM_ROWS` sweep：例如 512、1024、2048、4096 rows，观察软件 brute-force scan 的线性增长趋势。