# -*- coding: utf-8 -*-
"""
CAM 读取噪声（read_noise）集成测试。

本文件针对 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 子目标
  启用，测试代码内部已兼容两种配置。
"""

from __future__ import annotations

import cocotb
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,
    random_hashes,
    unpack_score_debug_flat,
)
from tests.top.utils import (
    dut_hash_bits,
    dut_lanes,
    dut_num_rows,
    get_param,
    query_once,
    reset_dut,
    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，查询，比对结果
    """
    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)
    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)

    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,
    )

    assert top1_index == expected.top1_index
    assert top1_score == expected.top1_score
    if score_debug is not None:
        assert np.array_equal(score_debug, expected.scores)