mirror of
https://github.com/SikongJueluo/Mini-Nav.git
synced 2026-07-12 20:15:31 +08:00
refactor(cam): remove read noise from noise architecture (Phase 2)
- Make cam_read_noise a pass-through module, removing all noise injection logic - Switch write noise to use noise_mask_bernoulli instead of noise_mask_grouped - Add state machine to cam_write_noise for mask generation timing - Remove noise_mask_grouped.sv (no longer needed) - Remove read noise parameters from cam_noisy and cam_top - Update simulation and benchmark code to reflect read noise removal - Sync documentation to reflect Phase 2 architecture
This commit is contained in:
@@ -1,94 +1,31 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
参考模型（ref_model）的纯 Python 单元测试。
|
||||
参考模型（ref_model）的纯 Python 单元测试 — Phase 2 cleaned.
|
||||
|
||||
本文件不涉及任何 RTL / Verilator 仿真，仅验证 Python 参考模型的正确性。
|
||||
所有 RTL-vs-模型 的对比测试（如顶层 test_cam_basic.py）都依赖此参考模型，
|
||||
因此这里是整个测试体系的「基石」——参考模型如果有 bug，所有对比测试都将失效。
|
||||
Phase 2 后只保留 pure matching 函数；所有 grouped/read-noise helpers 已删除。
|
||||
|
||||
测试覆盖：
|
||||
1. 分组翻转掩码 — 完全速率 (rate=1/1) 的正确位翻转模式
|
||||
2. 分组翻转掩码 — 零速率 (rate=0/100) 不应产生任何翻转
|
||||
3. 评分函数语义 — 确认是「匹配位数」而非「汉明距离」
|
||||
4. 读取噪声模型 — 相同输入 + 相同种子 = 可复现结果
|
||||
1. XNOR 评分语义 — 确认是「匹配位数」而非「汉明距离」
|
||||
2. Top-1 matching — 纯匹配，正确选出最高分索引
|
||||
3. Top-K matching — 返回排序后的行索引列表
|
||||
4. Top-K 排序规则 — 分数降序、平局行号升序
|
||||
5. Top-K k 超过行数时 clamp
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from model.ref_model import (
|
||||
generate_grouped_flip_mask,
|
||||
match_top1_with_read_noise,
|
||||
match_top1,
|
||||
match_topk,
|
||||
match_topk_from_scores,
|
||||
xnor_popcount_score,
|
||||
)
|
||||
import numpy as np
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 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
|
||||
sample = 0
|
||||
random_value |= bit_idx << (group * 14)
|
||||
random_value |= sample << (group * 14 + 6)
|
||||
|
||||
mask = generate_grouped_flip_mask(
|
||||
random_value=random_value,
|
||||
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 # 恰好 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, # 全 1 的 random_value
|
||||
hash_bits=512,
|
||||
noise_bits=8,
|
||||
rate_num=0, # 分子 = 0 → 翻转概率为 0
|
||||
rate_den=100,
|
||||
)
|
||||
assert mask == 0 # mask 必须全 0，一个位都不翻
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 3：评分函数语义 — 确认是「XNOR 匹配位数」而非「汉明距离」
|
||||
# 测试 1：评分函数语义 — 确认是「XNOR 匹配位数」而非「汉明距离」
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
@@ -114,64 +51,27 @@ def test_score_is_bit_match_popcount_not_hamming_distance():
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 4：读取噪声模型的可复现性（确定性种子）
|
||||
# 测试 2：Top-1 matching
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
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(
|
||||
query=query,
|
||||
rows=rows,
|
||||
width=512,
|
||||
lanes=8,
|
||||
noise_bits=8,
|
||||
rate_num=1,
|
||||
rate_den=100,
|
||||
seed=0x6A09_E667_F3BC_C909,
|
||||
)
|
||||
|
||||
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()
|
||||
def test_match_top1_selects_highest_xnor_score_with_row_index_tiebreak():
|
||||
"""Top-1 应选出 XNOR 分最高的行；平局时选最小行号。"""
|
||||
rows = [0b0000, 0b1111, 0b0011, 0b0101]
|
||||
query = 0b0000
|
||||
result = match_top1(query, rows, width=4)
|
||||
assert result.top1_index == 0
|
||||
assert result.top1_score == 4
|
||||
assert result.scores.tolist() == [4, 0, 2, 2]
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 5：Top-K 排序 — 分数降序、平局行号升序
|
||||
# 测试 3：Top-K matching
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
def test_match_topk_from_scores_uses_score_desc_then_row_asc():
|
||||
"""Top-K 排序规则：分数越大越优先；分数相同时行号越小越优先。"""
|
||||
from model.ref_model import match_topk_from_scores
|
||||
import numpy as np
|
||||
|
||||
scores = np.array([7, 9, 9, 2, 7], dtype=np.int32)
|
||||
assert match_topk_from_scores(scores, 4) == [1, 2, 0, 4]
|
||||
|
||||
|
||||
def test_match_topk_scores_rows_by_xnor_popcount():
|
||||
"""match_topk 通过 xnor_popcount 计算分数，返回排序后的行索引和分数数组。"""
|
||||
from model.ref_model import match_topk
|
||||
|
||||
rows = [0b0000, 0b1111, 0b0011, 0b0101]
|
||||
query = 0b0000
|
||||
indices, scores = match_topk(query, rows, width=4, k=3)
|
||||
@@ -179,43 +79,24 @@ def test_match_topk_scores_rows_by_xnor_popcount():
|
||||
assert indices == [0, 2, 3]
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 4：Top-K 排序 — 分数降序、平局行号升序
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
def test_match_topk_from_scores_uses_score_desc_then_row_asc():
|
||||
"""Top-K 排序规则：分数越大越优先；分数相同时行号越小越优先。"""
|
||||
scores = np.array([7, 9, 9, 2, 7], dtype=np.int32)
|
||||
assert match_topk_from_scores(scores, 4) == [1, 2, 0, 4]
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 5：Top-K k 超过行数时 clamp
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
def test_match_topk_clamps_k_to_row_count():
|
||||
"""当 k 超过实际行数时，返回所有行（按排序）。"""
|
||||
from model.ref_model import match_topk
|
||||
|
||||
indices, scores = match_topk(0, [0, 1], width=1, k=5)
|
||||
assert scores.tolist() == [1, 0]
|
||||
assert indices == [0, 1]
|
||||
|
||||
|
||||
# ==============================================================================
|
||||
# 测试 6：读取噪声 stateful 评分助手的跨查询状态推进
|
||||
# ==============================================================================
|
||||
|
||||
|
||||
def test_score_rows_with_read_noise_stateful_across_queries():
|
||||
"""score_rows_with_read_noise 在多次调用间正确推进 lane PRNG 状态。
|
||||
|
||||
两次调用使用相同的 rows/query 和零噪声率：
|
||||
- 分数应一致（无噪声翻转）
|
||||
- 但 lane states 应该变化（PRNG 已推进）
|
||||
"""
|
||||
from model.ref_model import score_rows_with_read_noise
|
||||
|
||||
rows = [0, 0, 0, 0]
|
||||
query = 0
|
||||
lane_states = [1, 2]
|
||||
|
||||
scores_1, next_states_1 = score_rows_with_read_noise(
|
||||
query, rows, lane_states=lane_states, width=128, lanes=2,
|
||||
noise_bits=2, rate_num=0, rate_den=100,
|
||||
)
|
||||
scores_2, next_states_2 = score_rows_with_read_noise(
|
||||
query, rows, lane_states=next_states_1, width=128, lanes=2,
|
||||
noise_bits=2, rate_num=0, rate_den=100,
|
||||
)
|
||||
|
||||
assert scores_1.tolist() == [128, 128, 128, 128]
|
||||
assert scores_2.tolist() == [128, 128, 128, 128]
|
||||
assert next_states_1 != lane_states
|
||||
assert next_states_2 != next_states_1
|
||||
|
||||
@@ -7,9 +7,5 @@ COCOTB_TEST_MODULES := tests.modules.cam_read_noise.test_cam_read_noise
|
||||
VERILOG_SOURCES := $(RTL_READ_NOISE)
|
||||
|
||||
HASH_BITS ?= 512
|
||||
READ_NOISE_EN ?= 0
|
||||
READ_NOISE_RATE_NUM ?= 0
|
||||
READ_NOISE_RATE_DEN ?= 100
|
||||
READ_NOISE_BITS ?= $(shell echo $$(( $(HASH_BITS) / 64 )))
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
@@ -2,7 +2,7 @@ from __future__ import annotations
|
||||
|
||||
import cocotb
|
||||
from cocotb.clock import Clock
|
||||
from cocotb.triggers import RisingEdge
|
||||
from cocotb.triggers import RisingEdge, Timer
|
||||
|
||||
|
||||
async def reset_read_noise(dut):
|
||||
@@ -38,11 +38,45 @@ async def read_noise_disabled_forwards_hashes_after_one_stage(dut):
|
||||
dut.row_ids_i.value = rows
|
||||
dut.lane_valid_i.value = all_lanes_valid
|
||||
dut.valid_i.value = 1
|
||||
await RisingEdge(dut.clk)
|
||||
await Timer(1, unit="step")
|
||||
await RisingEdge(dut.clk) # valid_o ← valid_i=1 internally
|
||||
await Timer(1, unit="step")
|
||||
dut.valid_i.value = 0
|
||||
await RisingEdge(dut.clk)
|
||||
await RisingEdge(dut.clk)
|
||||
|
||||
# One-stage pass-through: valid_o holds the latched value for this cycle
|
||||
assert int(dut.valid_o.value) == 1
|
||||
assert int(dut.hashes_noisy_o.value) == hashes
|
||||
assert int(dut.row_ids_o.value) == rows
|
||||
assert int(dut.lane_valid_o.value) == all_lanes_valid
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def read_noise_enabled_still_forwards_hashes_unmodified(dut):
|
||||
"""With READ_NOISE_EN=1, the pass-through still forwards hashes unmodified."""
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_read_noise(dut)
|
||||
|
||||
LANES = len(dut.lane_valid_i)
|
||||
ROW_BITS = len(dut.row_ids_i) // LANES
|
||||
HASH_BITS_PER_LANE = len(dut.hashes_i) // LANES
|
||||
all_lanes_valid = (1 << LANES) - 1
|
||||
|
||||
hashes = 0
|
||||
rows = 0
|
||||
for lane in range(LANES):
|
||||
hashes |= (lane + 0x55) << (lane * HASH_BITS_PER_LANE)
|
||||
rows |= lane << (lane * ROW_BITS)
|
||||
|
||||
dut.hashes_i.value = hashes
|
||||
dut.row_ids_i.value = rows
|
||||
dut.lane_valid_i.value = all_lanes_valid
|
||||
dut.valid_i.value = 1
|
||||
await Timer(1, unit="step")
|
||||
await RisingEdge(dut.clk) # valid_o ← valid_i=1 internally
|
||||
await Timer(1, unit="step")
|
||||
dut.valid_i.value = 0
|
||||
|
||||
# One-stage pass-through: valid_o holds latched value from previous cycle
|
||||
assert int(dut.valid_o.value) == 1
|
||||
assert int(dut.hashes_noisy_o.value) == hashes
|
||||
assert int(dut.row_ids_o.value) == rows
|
||||
|
||||
@@ -10,6 +10,4 @@ HASH_BITS ?= 512
|
||||
WRITE_NOISE_EN ?= 1
|
||||
WRITE_NOISE_RATE_NUM ?= 1
|
||||
WRITE_NOISE_RATE_DEN ?= 100
|
||||
WRITE_NOISE_BITS ?= $(shell echo $$(( $(HASH_BITS) / 64 )))
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
@@ -2,8 +2,32 @@ from __future__ import annotations
|
||||
|
||||
import cocotb
|
||||
from cocotb.clock import Clock
|
||||
from cocotb.triggers import RisingEdge
|
||||
from model.ref_model import generate_write_flip_mask
|
||||
from cocotb.triggers import RisingEdge, Timer
|
||||
|
||||
# Bernoulli: 1 PRIME + 16 RUN = 17 cycles internal
|
||||
# + 1 cycle for mask_start propagation + 1 cycle for core_wr_valid output = 19
|
||||
DEFAULT_WRITE_NOISE_LATENCY = 19
|
||||
|
||||
|
||||
async def pulse_write(dut, row: int, value: int):
|
||||
dut.wr_row.value = row
|
||||
dut.wr_hash.value = value
|
||||
dut.wr_valid.value = 1
|
||||
await Timer(1, unit="step")
|
||||
assert int(dut.wr_ready.value) == 1
|
||||
await RisingEdge(dut.clk)
|
||||
await Timer(1, unit="step")
|
||||
dut.wr_valid.value = 0
|
||||
|
||||
|
||||
async def wait_core_write(dut, max_cycles: int = 128) -> int:
|
||||
cycles = 0
|
||||
while int(dut.core_wr_valid.value) == 0:
|
||||
assert cycles < max_cycles, "timed out waiting for core_wr_valid"
|
||||
await RisingEdge(dut.clk)
|
||||
await Timer(1, unit="step")
|
||||
cycles += 1
|
||||
return cycles
|
||||
|
||||
|
||||
async def reset_write_noise(dut):
|
||||
@@ -19,23 +43,52 @@ async def reset_write_noise(dut):
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def write_noise_outputs_grouped_noisy_hash(dut):
|
||||
async def write_noise_enabled_applies_bernoulli_mask_after_generation(dut):
|
||||
"""Noise active: FSM enters WAIT_MASK, core_wr_hash deterministic across reset."""
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_write_noise(dut)
|
||||
|
||||
value = 0x123456789ABCDEF
|
||||
dut.wr_row.value = 3
|
||||
dut.wr_hash.value = value
|
||||
dut.wr_valid.value = 1
|
||||
value = (1 << 512) - 1 # all-ones: even low-rate Bernoulli may flip some bits
|
||||
await pulse_write(dut, row=3, value=value)
|
||||
await Timer(1, unit="step")
|
||||
assert int(dut.wr_ready.value) == 0
|
||||
|
||||
cycles = await wait_core_write(dut)
|
||||
assert cycles == DEFAULT_WRITE_NOISE_LATENCY
|
||||
|
||||
assert int(dut.core_wr_row.value) == 3
|
||||
hash_after_first = int(dut.core_wr_hash.value)
|
||||
|
||||
await RisingEdge(dut.clk)
|
||||
await Timer(1, unit="step")
|
||||
assert int(dut.core_wr_valid.value) == 0
|
||||
assert int(dut.wr_ready.value) == 1
|
||||
|
||||
# Deterministic across reset: same seed → same mask → same noisy hash
|
||||
await reset_write_noise(dut)
|
||||
await pulse_write(dut, row=3, value=value)
|
||||
await wait_core_write(dut)
|
||||
assert int(dut.core_wr_hash.value) == hash_after_first
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def write_noise_backpressures_second_write_until_done(dut):
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_write_noise(dut)
|
||||
|
||||
await pulse_write(dut, row=1, value=0xAA55)
|
||||
|
||||
dut.wr_row.value = 2
|
||||
dut.wr_hash.value = 0x55AA
|
||||
dut.wr_valid.value = 1
|
||||
await Timer(1, unit="step")
|
||||
for _ in range(4):
|
||||
assert int(dut.wr_ready.value) == 0
|
||||
assert int(dut.core_wr_valid.value) == 0
|
||||
await RisingEdge(dut.clk)
|
||||
await Timer(1, unit="step")
|
||||
dut.wr_valid.value = 0
|
||||
|
||||
while int(dut.core_wr_valid.value) == 0:
|
||||
await RisingEdge(dut.clk)
|
||||
|
||||
seed = 0xB504_F32D_B504_F32D
|
||||
hash_bits = len(dut.wr_hash)
|
||||
noise_bits = hash_bits // 64
|
||||
flip, _ = generate_write_flip_mask((seed << 64) | seed, hash_bits, noise_bits, 1, 100)
|
||||
assert int(dut.core_wr_row.value) == 3
|
||||
assert int(dut.core_wr_hash.value) == (value ^ flip)
|
||||
cycles = await wait_core_write(dut)
|
||||
assert cycles == DEFAULT_WRITE_NOISE_LATENCY - 4 # 19 - 4 = 15
|
||||
assert int(dut.core_wr_row.value) == 1
|
||||
|
||||
@@ -8,8 +8,5 @@ VERILOG_SOURCES := $(RTL_CAM_TOP)
|
||||
|
||||
HASH_BITS ?= 512
|
||||
WRITE_NOISE_EN := 0
|
||||
READ_NOISE_EN := 0
|
||||
WRITE_NOISE_BITS := $(shell echo $$(( $(HASH_BITS) / 64 )))
|
||||
READ_NOISE_BITS := $(shell echo $$(( $(HASH_BITS) / 64 )))
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
@@ -243,7 +243,6 @@ async def cam_perf_benchmark(dut):
|
||||
hash_bits = dut_hash_bits(dut)
|
||||
lanes = dut_lanes(dut)
|
||||
write_noise_en = _get_param(dut, "WRITE_NOISE_EN", 1)
|
||||
read_noise_en = _get_param(dut, "READ_NOISE_EN", 0)
|
||||
|
||||
# ── Deterministic query ─────────────────────────────────────────────
|
||||
query_hash = 0xAA55_AA55_AA55_AA55_AA55_AA55_AA55_AA55
|
||||
@@ -271,7 +270,7 @@ async def cam_perf_benchmark(dut):
|
||||
)
|
||||
|
||||
# ── Correctness assertions (conditional on noise state) ─────────────
|
||||
if not write_noise_en and not read_noise_en:
|
||||
if not write_noise_en:
|
||||
# Without noise: stored hash at row 0 == query_hash → exact match.
|
||||
assert top1_index == 0, (
|
||||
f"Noise disabled: expected top1_index=0 (exact match), got "
|
||||
@@ -282,7 +281,7 @@ async def cam_perf_benchmark(dut):
|
||||
f"{top1_score}"
|
||||
)
|
||||
else:
|
||||
# With noise: write/read flip masks may corrupt stored values, so
|
||||
# With noise: write flip masks may corrupt stored values, so
|
||||
# we cannot reliably assert the exact match. Instead, confirm a
|
||||
# valid non-zero score was produced (the match engine ran).
|
||||
assert top1_score > 0, (
|
||||
@@ -290,10 +289,10 @@ async def cam_perf_benchmark(dut):
|
||||
"Match engine returned invalid result."
|
||||
)
|
||||
dut._log.info(
|
||||
"Noise enabled (WRITE_NOISE_EN=%s, READ_NOISE_EN=%s) — "
|
||||
"Noise enabled (WRITE_NOISE_EN=%s) — "
|
||||
"skipping exact top1_index/top1_score assertion. "
|
||||
"top1_index=%d top1_score=%d",
|
||||
write_noise_en, read_noise_en, top1_index, top1_score,
|
||||
write_noise_en, top1_index, top1_score,
|
||||
)
|
||||
|
||||
# ── Machine-readable performance marker ─────────────────────────────
|
||||
|
||||
@@ -8,6 +8,5 @@ VERILOG_SOURCES := $(RTL_CAM_TOP)
|
||||
|
||||
# 禁用所有噪声模块
|
||||
WRITE_NOISE_EN := 0
|
||||
READ_NOISE_EN := 0
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
CAM 顶层（cam_top）no_noise 配置集成测试（WRITE_NOISE_EN=0, READ_NOISE_EN=0）。
|
||||
CAM 顶层（cam_top）no_noise 配置集成测试（WRITE_NOISE_EN=0）。
|
||||
|
||||
所有噪声模块禁用，验证 CAM 在无噪声下的标准行为。
|
||||
|
||||
@@ -17,8 +17,8 @@ CAM 顶层（cam_top）no_noise 配置集成测试（WRITE_NOISE_EN=0, READ_NOIS
|
||||
|
||||
=== 配置背景 ===
|
||||
|
||||
本目录固定使用 WRITE_NOISE_EN=0 和 READ_NOISE_EN=0 编译，
|
||||
因此所有测试无需运行时参数门控——Makefile 保证配置正确。
|
||||
本目录固定使用 WRITE_NOISE_EN=0 编译，
|
||||
因此所有测试无需运行时参数门控——Makefile 保证配置正确。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -62,7 +62,7 @@ async def compile_includes_grouped_noise_helper(dut):
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# 测试 A：基线（WRITE_NOISE_EN=0, READ_NOISE_EN=0）
|
||||
# 测试 A：基线（WRITE_NOISE_EN=0）
|
||||
# ── 验证写+查在噪声关闭时与旧 CAM 行为完全一致
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
|
||||
@@ -6,10 +6,7 @@ TOPLEVEL := cam_top
|
||||
COCOTB_TEST_MODULES := tests.top.read_noise.test_read_noise
|
||||
VERILOG_SOURCES := $(RTL_CAM_TOP)
|
||||
|
||||
# 读取噪声开启，写入噪声默认关闭
|
||||
READ_NOISE_EN := 1
|
||||
READ_NOISE_RATE_NUM := 1
|
||||
READ_NOISE_RATE_DEN := 100
|
||||
# 读取噪声开启（Phase 2 后为 pass-through），写入噪声默认关闭
|
||||
WRITE_NOISE_EN := 0
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
@@ -1,27 +1,9 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
CAM 读取噪声（read_noise）集成测试。
|
||||
CAM 读取路径 pass-through 集成测试 — Phase 2 cleaned.
|
||||
|
||||
本文件针对 READ_NOISE_EN=1 的编译配置，验证 RTL 的读取噪声行为
|
||||
与 Python 参考模型（ref_model）一致。
|
||||
|
||||
=== 测试内容 ===
|
||||
|
||||
read_noise_model_match — 读取噪声模型匹配：
|
||||
写入原始哈希，预测含写入噪声（如果 WRITE_NOISE_EN=1）的存储值，
|
||||
再用 match_top1_with_read_noise 计算含读取噪声的期望结果，
|
||||
与 RTL 实际 Top-1 进行比对。
|
||||
|
||||
=== 架构背景 ===
|
||||
|
||||
CAM 硬件由以下流水线组成：
|
||||
Write Noise → Banked Core Storage → Read Noise → Match Engine Pipeline
|
||||
↓
|
||||
Top-K Tracker → Result Serializer
|
||||
|
||||
本测试覆盖的是 Read Noise → Match Engine 段。
|
||||
写入噪声（WRITE_NOISE_EN）通过 Makefile 的 test-with-write-noise 子目标
|
||||
启用，测试代码内部已兼容两种配置。
|
||||
Read noise 已退休；cam_read_noise 是纯 pass-through。
|
||||
本测试验证查询返回的 scores 与 pure matching 一致。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -31,83 +13,40 @@ import numpy as np
|
||||
from cocotb.clock import Clock
|
||||
from cocotb.triggers import RisingEdge
|
||||
from model.ref_model import (
|
||||
generate_write_flip_mask,
|
||||
match_top1_with_read_noise,
|
||||
match_top1,
|
||||
random_hashes,
|
||||
unpack_score_debug_flat,
|
||||
)
|
||||
from tests.top.utils import (
|
||||
collect_topk,
|
||||
dut_hash_bits,
|
||||
dut_lanes,
|
||||
dut_num_rows,
|
||||
get_param,
|
||||
query_once,
|
||||
query_topk_once,
|
||||
reset_dut,
|
||||
write_row,
|
||||
write_rows,
|
||||
)
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# 测试：读取噪声模型匹配
|
||||
# ── READ_NOISE_EN=1 由 Makefile 保证，测试代码中不再重复门控
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def read_noise_model_match(dut):
|
||||
"""读取噪声模型匹配：验证 RTL 的读取噪声行为与 Python 参考模型一致。
|
||||
|
||||
与写入噪声不同，读取噪声发生在查询阶段（每次查询向哈希值注入噪声），
|
||||
因此：
|
||||
- 如果先有写入噪声，存储行已经被翻转过一次
|
||||
- 然后查询时还会再注入一层读取噪声
|
||||
- 两层噪声使用不同的种子（写: 0xB504..., 读: 0x6A09...）
|
||||
|
||||
本测试：
|
||||
1. 用 Python 模型预计算存储后的哈希（含写入噪声）
|
||||
2. 用 match_top1_with_read_noise 预计算含读取噪声的期望结果
|
||||
3. 写入原始值到 RTL，查询，比对结果
|
||||
"""
|
||||
async def read_path_pass_through_produces_pure_matching(dut):
|
||||
"""写 4 行，查询存过的行，验证 Top-1/Top-K 与 pure matching 一致。"""
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_dut(dut)
|
||||
|
||||
num_rows = dut_num_rows(dut)
|
||||
hash_bits = dut_hash_bits(dut)
|
||||
lanes = dut_lanes(dut)
|
||||
rng = np.random.default_rng(123)
|
||||
rng = np.random.default_rng(42)
|
||||
rows = random_hashes(rng, num_rows, width=hash_bits)
|
||||
|
||||
# If write noise is enabled, apply write flip masks to predict stored rows
|
||||
stored_rows = list(rows)
|
||||
if get_param(dut, "WRITE_NOISE_EN", 0):
|
||||
seed = 0xB504_F32D_B504_F32D
|
||||
prng_state = (seed << 64) | seed
|
||||
stored_rows = []
|
||||
for row in rows:
|
||||
flip, prng_state = generate_write_flip_mask(
|
||||
prng_state,
|
||||
hash_bits,
|
||||
get_param(dut, "WRITE_NOISE_BITS", 8),
|
||||
get_param(dut, "WRITE_NOISE_RATE_NUM", 1),
|
||||
get_param(dut, "WRITE_NOISE_RATE_DEN", 100),
|
||||
)
|
||||
stored_rows.append(row ^ flip)
|
||||
|
||||
query = rows[min(5, num_rows - 1)]
|
||||
|
||||
await write_rows(dut, rows)
|
||||
top1_index, top1_score, score_debug = await query_once(dut, query)
|
||||
query = rows[min(50, num_rows - 1)]
|
||||
|
||||
expected = match_top1_with_read_noise(
|
||||
query,
|
||||
stored_rows,
|
||||
width=hash_bits,
|
||||
lanes=lanes,
|
||||
noise_bits=get_param(dut, "READ_NOISE_BITS", 8),
|
||||
rate_num=get_param(dut, "READ_NOISE_RATE_NUM", 1),
|
||||
rate_den=get_param(dut, "READ_NOISE_RATE_DEN", 100),
|
||||
seed=0x6A09_E667_F3BC_C909,
|
||||
)
|
||||
top1_index, top1_score, score_debug = await query_once(dut, query)
|
||||
expected = match_top1(query, rows, width=hash_bits)
|
||||
|
||||
assert top1_index == expected.top1_index
|
||||
assert top1_score == expected.top1_score
|
||||
|
||||
@@ -10,7 +10,6 @@ VERILOG_SOURCES := $(RTL_CAM_TOP)
|
||||
WRITE_NOISE_EN := 1
|
||||
WRITE_NOISE_RATE_NUM := 1
|
||||
WRITE_NOISE_RATE_DEN := 100
|
||||
READ_NOISE_EN := 0
|
||||
|
||||
include $(SIM_ROOT)/mk/cocotb-common.mk
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"""
|
||||
CAM 写入噪声（Write Noise）集成测试 —— 专用配置。
|
||||
|
||||
本文件测试 WRITE_NOISE_EN=1, READ_NOISE_EN=0 配置下，
|
||||
本文件测试 WRITE_NOISE_EN=1 配置下，
|
||||
写入噪声模块的正确性。默认噪声率约 1%（NUM=1, DEN=100）。
|
||||
|
||||
=== 测试列表 ===
|
||||
@@ -14,7 +14,7 @@ CAM 写入噪声（Write Noise）集成测试 —— 专用配置。
|
||||
|
||||
=== 架构背景 ===
|
||||
|
||||
写入噪声流水线位置：Write Noise → Banked Core Storage → Read Noise → Match Engine
|
||||
写入噪声流水线位置：Write Noise → Banked Core Storage → Match Engine
|
||||
本测试覆盖完整的 cam_top 链路，写入噪声为唯一活跃噪声源。
|
||||
|
||||
=== Makefile 子目标 ===
|
||||
@@ -30,7 +30,6 @@ import numpy as np
|
||||
from cocotb.clock import Clock
|
||||
from cocotb.triggers import RisingEdge
|
||||
from model.ref_model import (
|
||||
generate_write_flip_mask,
|
||||
match_top1,
|
||||
random_hashes,
|
||||
)
|
||||
@@ -89,71 +88,7 @@ async def default_noise_reproducible(dut):
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# 测试 2：精确 RTL-vs-模型 PRNG 掩码匹配
|
||||
# ── RTL 存储的哈希与 ref_model.py 生成的掩码逐位一致
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def exact_noise_model_match(dut):
|
||||
"""精确噪声模型匹配：RTL 的 PRNG 输出必须与 Python 参考模型逐位一致。
|
||||
|
||||
测试方法：
|
||||
1. 用固定 RTL seed 和已知噪声参数，在 Python 中预计算每行的 flip 掩码
|
||||
2. 预期存储值 = 原始值 XOR flip_mask
|
||||
3. 写入原始值到 RTL，查询预期存储值
|
||||
4. 断言每行 score = HASH_BITS（完全匹配）
|
||||
|
||||
这验证了 RTL 的 LFSR 实现与 Python 模型的 PRNG 使用相同的
|
||||
多项式、相同的位宽、相同的种子初始化序列。
|
||||
"""
|
||||
if not hasattr(dut, "score_debug_flat"):
|
||||
dut._log.info("Skipping exact_noise_model_match: requires SIM_DEBUG.")
|
||||
return
|
||||
|
||||
rtol = None
|
||||
atol = None
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_dut(dut)
|
||||
|
||||
hash_bits = dut_hash_bits(dut)
|
||||
noise_bits = get_param(dut, "WRITE_NOISE_BITS", 8)
|
||||
rate_num = get_param(dut, "WRITE_NOISE_RATE_NUM", 1)
|
||||
rate_den = get_param(dut, "WRITE_NOISE_RATE_DEN", 100)
|
||||
|
||||
n_test_rows = 4
|
||||
rng = np.random.default_rng(99)
|
||||
rows = random_hashes(rng, n_test_rows, width=hash_bits)
|
||||
|
||||
RTL_SEED = 0xB504_F32D_B504_F32D
|
||||
prng_state = (RTL_SEED << 64) | RTL_SEED
|
||||
expected_stored = []
|
||||
for row in rows:
|
||||
flip, prng_state = generate_write_flip_mask(
|
||||
prng_state,
|
||||
hash_bits,
|
||||
noise_bits,
|
||||
rate_num,
|
||||
rate_den,
|
||||
)
|
||||
expected_stored.append(row ^ flip)
|
||||
|
||||
for idx, val in enumerate(rows):
|
||||
await write_row(dut, idx, val)
|
||||
|
||||
for idx, expected in enumerate(expected_stored):
|
||||
top1_index, top1_score, score_debug = await query_once(dut, expected)
|
||||
assert score_debug is not None, (
|
||||
"score_debug required for mask match verification"
|
||||
)
|
||||
assert int(score_debug[idx]) == hash_bits, (
|
||||
f"Row {idx}: expected stored hash to match model prediction, "
|
||||
f"score={score_debug[idx]} != {hash_bits}"
|
||||
)
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# 测试 3：零噪声率（WRITE_NOISE_EN=1, RATE_NUM=0）
|
||||
# 测试 2：零噪声率（WRITE_NOISE_EN=1, RATE_NUM=0）
|
||||
# ── 噪声模块已连接但翻转概率为 0 → 行为应与无噪声一致
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
@@ -195,80 +130,4 @@ async def zero_rate_noise(dut):
|
||||
assert np.array_equal(score_debug, expected.scores)
|
||||
|
||||
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
# 测试 4：100% 噪声率（RATE_NUM=1, RATE_DEN=1）
|
||||
# ── 每组都翻转 → 精确验证 PRNG 掩码生成
|
||||
# ═══════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
|
||||
@cocotb.test()
|
||||
async def full_rate_noise(dut):
|
||||
"""完全速率噪声：每组 100% 翻转概率。
|
||||
|
||||
使用固定 RTL seed (0xB504F32DB504F32D)，用 Python 模型预计算
|
||||
写入全 0 和全 1 行后应存储的哈希值，然后验证 RTL 实际存储的哈希
|
||||
与模型预测完全一致。
|
||||
|
||||
这是最低容忍度的噪声测试——要求 score_debug_flat（SIM_DEBUG）
|
||||
且每行的分数必须精确等于 HASH_BITS。
|
||||
"""
|
||||
rate_num = get_param(dut, "WRITE_NOISE_RATE_NUM", 1)
|
||||
rate_den = get_param(dut, "WRITE_NOISE_RATE_DEN", 100)
|
||||
if rate_num != 1 or rate_den != 1:
|
||||
dut._log.info(
|
||||
"Skipping full_rate_noise: requires WRITE_NOISE_RATE_NUM=1, RATE_DEN=1."
|
||||
)
|
||||
return
|
||||
if not hasattr(dut, "score_debug_flat"):
|
||||
dut._log.info(
|
||||
"Skipping full_rate_noise: requires SIM_DEBUG (score_debug_flat)."
|
||||
)
|
||||
return
|
||||
|
||||
cocotb.start_soon(Clock(dut.clk, 10, unit="ns").start())
|
||||
await reset_dut(dut)
|
||||
|
||||
hash_bits = dut_hash_bits(dut)
|
||||
num_rows = dut_num_rows(dut)
|
||||
noise_bits = get_param(dut, "WRITE_NOISE_BITS", 8)
|
||||
all_zero = 0
|
||||
all_one = (1 << hash_bits) - 1
|
||||
|
||||
RTL_SEED = 0xB504_F32D_B504_F32D
|
||||
prng_state = (RTL_SEED << 64) | RTL_SEED
|
||||
|
||||
flip0, prng_state = generate_write_flip_mask(
|
||||
prng_state,
|
||||
hash_bits,
|
||||
noise_bits,
|
||||
rate_num,
|
||||
rate_den,
|
||||
)
|
||||
expected_row0 = all_zero ^ flip0
|
||||
|
||||
flip1, prng_state = generate_write_flip_mask(
|
||||
prng_state,
|
||||
hash_bits,
|
||||
noise_bits,
|
||||
rate_num,
|
||||
rate_den,
|
||||
)
|
||||
expected_row1 = all_one ^ flip1
|
||||
|
||||
rows = [0] * num_rows
|
||||
rows[0] = all_zero
|
||||
rows[1] = all_one
|
||||
|
||||
await write_rows(dut, rows)
|
||||
|
||||
top1_index, top1_score, score_debug = await query_once(dut, expected_row0)
|
||||
assert score_debug is not None, "score_debug required for full_rate_noise"
|
||||
assert int(score_debug[0]) == hash_bits, (
|
||||
f"Row 0: expected exact match, score={score_debug[0]} != {hash_bits}"
|
||||
)
|
||||
|
||||
top1_index, top1_score, score_debug = await query_once(dut, expected_row1)
|
||||
assert score_debug is not None
|
||||
assert int(score_debug[1]) == hash_bits, (
|
||||
f"Row 1: expected exact match, score={score_debug[1]} != {hash_bits}"
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user