refactor(hw/sim): reorganize CAM top-level tests into per-noise-config suites

Split the monolithic test_cam_basic.py into separate test suites
organized by noise configuration (no_noise, write_noise, read_noise),
with shared utilities extracted to tests/top/utils.py.

- Remove test_cam_basic.py; add no_noise/, write_noise/, read_noise/
  test suites with Makefiles that set noise parameters statically
- Extract helpers (reset_dut, write_rows, query_once, collect_topk,
  etc.) into tests/top/utils.py
- Update hw/sim/Makefile with per-config test targets and a
  test-top-all meta-target
- Update scripts/run_cam_correctness.py to build per-directory
  instead of centrally, removing inline parameter overrides
- Add __init__.py for result_serializer and topk_tracker module tests
- Expand docstrings in test_ref_model_noise.py with architectural
  context and test rationale

hw/sim/tests/model/test_ref_model_noise.py

@@ -1,3 +1,17 @@
+# -*- coding: utf-8 -*-
+"""
+参考模型（ref_model）的纯 Python 单元测试。
+
+本文件不涉及任何 RTL / Verilator 仿真，仅验证 Python 参考模型的正确性。
+所有 RTL-vs-模型 的对比测试（如顶层 test_cam_basic.py）都依赖此参考模型，
+因此这里是整个测试体系的「基石」——参考模型如果有 bug，所有对比测试都将失效。
+
+测试覆盖：
+  1. 分组翻转掩码 — 完全速率 (rate=1/1) 的正确位翻转模式
+  2. 分组翻转掩码 — 零速率 (rate=0/100) 不应产生任何翻转
+  3. 评分函数语义 — 确认是「匹配位数」而非「汉明距离」
+  4. 读取噪声模型 — 相同输入 + 相同种子 = 可复现结果
+"""
 from __future__ import annotations
 
 from model.ref_model import (
@@ -7,7 +21,26 @@ from model.ref_model import (
 )
 
 
+# ==============================================================================
+# 测试 1：完全速率下的分组翻转掩码生成
+# ==============================================================================
+
+
 def test_grouped_flip_mask_full_rate_one_bit_per_64_bit_group():
+    """
+    验证 generate_grouped_flip_mask 在 rate_num=1, rate_den=1 时的行为。
+
+    背景：
+      - CAM 的 write noise 模块将 512-bit 哈希按 64-bit 分组，每组最多翻转 1 位。
+      - random_value 的位域含义（每 group 14 bits）：
+        bits [5:0]   → sample（未使用）
+        bits [13:6]  → bit_idx（选择该组内翻转哪一位）
+
+    本测试：
+      - 构造一个 random_value，使每个 group 的 bit_idx = group+1
+      - 断言生成的 mask 恰好有 8 个位被置位（每 group 一个）
+      - 断言每个被翻转的位位置与预期一致
+    """
     random_value = 0
     for group in range(8):
         bit_idx = group + 1
@@ -17,38 +50,88 @@ def test_grouped_flip_mask_full_rate_one_bit_per_64_bit_group():
 
     mask = generate_grouped_flip_mask(
         random_value=random_value,
-        hash_bits=512,
-        noise_bits=8,
-        rate_num=1,
-        rate_den=1,
+        hash_bits=512,      # 8 组 × 64 bits/组
+        noise_bits=8,       # 每组的 bit_idx 位宽
+        rate_num=1,         # 分子 = 1
+        rate_den=1,         # 分母 = 1 → 100% 概率，每组都翻转
     )
 
+    # 预期：每组的 bit_idx 位被翻转
     expected = 0
     for group in range(8):
         expected |= 1 << (group * 64 + group + 1)
 
     assert mask == expected
-    assert mask.bit_count() == 8
+    assert mask.bit_count() == 8   # 恰好 8 位被翻转（每组一位）
+
+
+# ==============================================================================
+# 测试 2：零速率下不应产生任何翻转
+# ==============================================================================
 
 
 def test_grouped_flip_mask_zero_rate_no_flips():
+    """
+    验证 rate_num=0 时，无论 random_value 为何值，mask 都应为 0。
+
+    这是写入噪声的「零噪声」配置边界测试——
+    确保 RTL 参数 WRITE_NOISE_RATE_NUM=0 能真正关闭噪声注入。
+    """
     mask = generate_grouped_flip_mask(
-        random_value=(1 << 128) - 1,
+        random_value=(1 << 128) - 1,  # 全 1 的 random_value
         hash_bits=512,
         noise_bits=8,
-        rate_num=0,
+        rate_num=0,                   # 分子 = 0 → 翻转概率为 0
         rate_den=100,
     )
-    assert mask == 0
+    assert mask == 0                  # mask 必须全 0，一个位都不翻
+
+
+# ==============================================================================
+# 测试 3：评分函数语义 — 确认是「XNOR 匹配位数」而非「汉明距离」
+# ==============================================================================
 
 
 def test_score_is_bit_match_popcount_not_hamming_distance():
+    """
+    关键语义验证：xnor_popcount_score 计算的是匹配位的数量，不是汉明距离。
+
+    示例：
+      query  = 0b1010
+      stored = 0b1000
+      XNOR   = 0b1101  → popcount = 3（有 3 个位匹配）
+      汉明距离 = 1       → 只有一个位不同
+
+    为什么这个区分很重要：
+      - 如果 RTL 或模型错误地使用了汉明距离作为分数，则：
+        完全匹配的分数会是 0 而非 hash_bits（512）
+        Top-K 排序会颠倒（分数低的反而排前面）
+      - 这会导致整个 CAM 检索系统返回错误结果
+    """
     query = 0b1010
     stored = 0b1000
     assert xnor_popcount_score(query, stored, width=4) == 3
 
 
+# ==============================================================================
+# 测试 4：读取噪声模型的可复现性（确定性种子）
+# ==============================================================================
+
+
 def test_read_noise_model_is_reproducible_after_reset_seed():
+    """
+    验证 match_top1_with_read_noise 在相同参数下产生相同结果。
+
+    为什么这个测试至关重要：
+      - RTL 中的 read noise PRNG 使用固定种子 (0x6A09E667F3BCC909)
+      - 参考模型必须使用相同的种子来复现 RTL 的噪声行为
+      - 如果两次调用结果不同，说明模型存在非确定性 bug
+        （如未重置 PRNG 状态、或使用了非确定性随机源）
+
+    测试数据：
+      - 8 行不同模式的 512-bit 哈希（全0、全1、稀疏值）
+      - 噪声配置：rate=1%, lanes=8, noise_bits=8
+    """
     rows = [0, (1 << 512) - 1, 0x1234, 0x5678, 0x9ABC, 0xDEF0, 0x1357, 0x2468]
     query = rows[2]
     kwargs = dict(
@@ -65,6 +148,7 @@ def test_read_noise_model_is_reproducible_after_reset_seed():
     first = match_top1_with_read_noise(**kwargs)
     second = match_top1_with_read_noise(**kwargs)
 
+    # 两次调用的 Top-1 结果和分数数组必须完全一致
     assert first.top1_index == second.top1_index
     assert first.top1_score == second.top1_score
     assert first.scores.tolist() == second.scores.tolist()