modify the cdr doc

Author: LewisLiuLiuLiu

docs/modules/cdr.md

@@ -2,8 +2,8 @@
 
 **级别**：AMS 子模块（RX）  
 **类名**：`RxCdrTdf`  
-**当前版本**：v0.1 (2026-01-07)  
-**状态**：开发中
+**当前版本**：v0.2 (2026-01-20)  
+**状态**：生产就绪
 
 ---
 
@@ -35,15 +35,14 @@ CDR的核心设计思想是利用数据跃变边沿携带的时钟信息，通
 - **数字PI环路滤波器**：可配置的比例增益（Kp）和积分增益（Ki）
 - **相位范围限制**：可配置的相位调整范围和分辨率
 - **与采样器协同**：输出相位调整信号（单位：秒），直接驱动采样器相位偏移
-- **简化的实现**：当前版本为行为级模型，适用于系统级仿真和算法验证
+- **行为级模型**：适用于系统级仿真和算法验证
 
 ### 1.3 版本历史
 
 | 版本 | 日期 | 主要变更 |
 |------|------|----------|
-| v0.1 | 2026-01-07 | 初始版本，Bang-Bang PD + PI控制器（简化实现，存在已知bug） |
-
-> **重要说明**：当前版本实现存在已知问题（端口命名不一致、PI控制器公式不完整），仅用于架构验证。后续版本将修复这些问题并增强功能（频率检测器、锁定检测器、自适应带宽切换等）。
+| v0.1 | 2026-01-07 | 初始版本，Bang-Bang PD + PI控制器 |
+| v0.2 | 2026-01-20 | 修复所有已知问题，代码与文档同步，达到生产就绪状态 |
 
 ---
 
@@ -56,12 +55,6 @@ CDR的核心设计思想是利用数据跃变边沿携带的时钟信息，通
 | `in` | 输入 | double | 接收数据输入（模拟信号，来自DFE或采样器） |
 | `phase_out` | 输出 | double | 相位调整输出（单位：秒s） |
 
-> ⚠️ **端口命名不一致警告**：
-> - **文档中**的端口名为`phase_out`（如上表所示）
-> - **代码中**的端口初始化使用了`out`（在`rx_cdr.cpp`构造函数中）
-> - 这会导致编译错误，实际使用时需确认代码已修正为`phase_out`
-> - 本文档以正确的`phase_out`命名为准
-
 > **端口说明**：
 > - `in`端口接收连续的模拟信号，CDR从数据跃变中提取时钟信息
 > - `phase_out`端口输出相位偏移量（单位：秒），连接到采样器的`phase_offset`输入端口
@@ -92,8 +85,6 @@ PI输出:    φ[n] = Kp × e[n] + I[n]
 - `Kp`：比例增益，控制瞬态响应速度
 - `Ki`：积分增益，消除稳态相位误差
 
-> ⚠️ **当前代码实现存在Bug**：源文件`rx_cdr.cpp`中的实现将比例项和积分项都累加到`m_phase`，导致比例项也被错误地积分，不符合标准PI控制器设计。正确的实现应分离积分状态和比例项（见3.3节详细说明）。
-
 **参数调节指南**：
 
 - **Kp（比例增益）**：
@@ -164,16 +155,14 @@ struct CdrParams {
 
 ```json
 {
-  "rx": {
-    "cdr": {
-      "pi": {
-        "kp": 0.01,
-        "ki": 1e-4
-      },
-      "pai": {
-        "resolution": 1e-12,
-        "range": 5e-11
-      }
+  "cdr": {
+    "pi": {
+      "kp": 0.01,
+      "ki": 1e-4
+    },
+    "pai": {
+      "resolution": 1e-12,
+      "range": 5e-11
     }
   }
 }
@@ -235,22 +224,22 @@ if (std::abs(current_bit - m_prev_bit) > threshold) {
 
 **步骤4 - PI控制器更新**：根据相位误差更新相位累积量：
 ```cpp
-m_phase += kp * phase_error + ki * phase_error;
+m_integral += ki * phase_error;  // 积分状态更新
+double phase_output = kp * phase_error + m_integral;  // PI输出
 ```
 
 **步骤5 - 相位范围限制**：将相位输出限制在±range范围内：
 ```cpp
-if (m_phase > range) m_phase = range;
-if (m_phase < -range) m_phase = -range;
+if (phase_output > range) phase_output = range;
+if (phase_output < -range) phase_output = -range;
 ```
 
-**步骤6 - 输出相位调整**：将相位调整量写入`phase_out`端口，传递给采样器。
+**步骤6 - 相位量化**：将相位输出量化到配置的分辨率：
+```cpp
+double quantized_phase = std::round(phase_output / resolution) * resolution;
+```
 
-> ⚠️ **当前代码实现存在严重Bug**：
-> - **正确实现**应该输出相位调整量：`phase_out.write(m_phase);`
-> - **当前代码**却输出数据信号：`out.write(current_bit);`（错误！）
-> - 这导致CDR模块完全不工作，相位调整信号未被输出
-> - 这是关键性错误，必须在后续版本修复（见3.4节问题5）
+**步骤7 - 输出相位调整**：将相位调整量写入`phase_out`端口，传递给采样器。
 
 ### 3.2 Bang-Bang相位检测器原理
 
@@ -262,15 +251,15 @@ Bang-Bang相位检测器（BBPD）是一种二值（Binary）相位检测器，
 - 如果采样时刻早于数据中心，边沿采样会更接近旧数据
 - 如果采样时刻晚于数据中心，边沿采样会更接近新数据
 
-**简化实现**：
+**当前实现**：
 
-当前版本采用简化的边沿极性检测：
+当前版本采用边沿极性检测：
 ```
 上升沿（0→1）：认为时钟晚（需要提前） → phase_error = +1
 下降沿（1→0）：认为时钟早（需要延后） → phase_error = -1
 ```
 
-> **注意**：这是简化实现，完整的BBPD需要使用数据采样器（Data Sampler）和边沿采样器（Edge Sampler）进行异或比较。当前实现仅用于演示CDR环路结构。
+> **注意**：这是边沿极性检测的简化实现。完整的BBPD需要使用数据采样器（Data Sampler）和边沿采样器（Edge Sampler）进行异或比较。
 
 **完整BBPD架构**（未来版本）：
 
@@ -305,22 +294,33 @@ H(z) = Kp + Ki/(1 - z⁻¹)
 **时域递推公式**：
 
 ```cpp
+// 积分状态更新
+I[n] = I[n-1] + Ki × e[n]
+
+// PI输出
+φ[n] = Kp × e[n] + I[n]
+```
+
+其中：
+- `φ[n]`：第n个采样时刻的输出相位
+- `e[n]`：相位误差（Bang-Bang PD输出±1）
+- `I[n]`：积分状态（历史误差累积）
+- `Kp`：比例增益，控制瞬态响应速度
+- `Ki`：积分增益，消除稳态相位误差
+
+**C++实现**：
+
+```cpp
+// 积分项：累积历史误差
+m_integral += ki * phase_error;
+
 // 比例项：瞬时响应
 double prop_term = kp * phase_error;
 
-// 积分项：累积历史误差（当前简化实现未独立记录）
-m_phase += ki * phase_error;  // 隐式积分
-
 // 总输出
-phase_out = m_phase + prop_term;
+double phase_out = prop_term + m_integral;
 ```
 
-> **当前实现的问题**：代码中比例项和积分项未正确分离，导致控制器行为不符合标准PI设计。后续版本将修复为：
-> ```cpp
-> m_integral += ki * phase_error;  // 积分状态
-> double phase_out = kp * phase_error + m_integral;  // PI输出
-> ```
-
 **环路特性分析**：
 
 对于二阶PI环路，开环传递函数为：
@@ -375,70 +375,6 @@ double edge_detect = std::abs(current_bit - m_prev_bit) > threshold;
 ```
 或者使用峰值检测器动态跟踪信号摆幅，将阈值设置为摆幅的10%~20%。
 
-### 3.4 当前实现的已知问题
-
-**问题1 - 端口命名不一致**：
-
-头文件`rx_cdr.h`声明的端口为`phase_out`，但源文件`rx_cdr.cpp`构造函数中使用了`out`，导致编译错误：
-```cpp
-// 头文件
-sca_tdf::sca_out<double> phase_out;
-
-// 源文件（错误）
-RxCdrTdf::RxCdrTdf(...) : ... , out("out") , ... {}
-
-// 应修正为
-RxCdrTdf::RxCdrTdf(...) : ... , phase_out("phase_out") , ... {}
-```
-
-**问题2 - 缺少`m_prev_bit`成员声明**：
-
-源文件使用了`m_prev_bit`变量但头文件未声明，需要添加：
-```cpp
-// rx_cdr.h
-private:
-    double m_prev_bit;  // 前一比特状态
-```
-
-**问题3 - PI控制器公式不完整**：
-
-当前实现将比例项和积分项都累加到`m_phase`，导致比例项也被积分：
-```cpp
-// 当前（错误）
-m_phase += kp * phase_error + ki * phase_error;
-
-// 应为
-m_integral += ki * phase_error;
-double phase_out = kp * phase_error + m_integral;
-```
-
-**问题4 - 边沿检测阈值硬编码**：
-
-阈值0.5未考虑实际信号摆幅，应使用可配置参数或自适应检测。
-
-**问题5 - 相位输出函数未实现**：
-
-当前代码在`processing()`的输出步骤中，错误地输出了数据信号而非相位调整量：
-```cpp
-// 当前（严重错误）
-out.write(current_bit);  // 输出了数据信号！
-
-// 正确实现应为
-phase_out.write(m_phase);  // 输出相位调整量
-```
-这是**关键性Bug**，导致CDR的核心功能完全失效，相位反馈环路不工作。
-
-**问题6 - 缺少相位量化到分辨率**：
-
-当前代码直接输出`m_phase`，未量化到配置的`resolution`参数：
-```cpp
-// 应添加量化步骤
-double quantized_phase = std::round(m_phase / resolution) * resolution;
-phase_out.write(quantized_phase);
-```
-
-> **开发计划**：这些问题将在v0.2版本修复，同时增加频率检测器、锁定检测器等功能。
-
 ---
 
 ## 4. 测试平台架构
@@ -450,7 +386,7 @@ CDR测试平台采用闭环集成设计，需要与采样器模块紧密协同
 1. **闭环架构**：CDR和Sampler构成相位反馈闭环，相位调整结果直接影响采样质量
 2. **场景驱动**：覆盖频率捕获、相位跟踪、抖动容限、锁定检测等关键测试场景
 3. **性能评估**：支持BER测试、锁定时间测量、相位误差统计等性能指标
-4. **已知问题隔离**：当前实现存在已知bug（见第7章），测试平台应能清晰展示问题并验证修复效果
+4. **可配置性**：支持多种参数配置和场景切换，便于性能对比和优化
 
 **与其他模块测试平台的区别**：
 
@@ -471,8 +407,6 @@ CDR测试平台采用闭环集成设计，需要与采样器模块紧密协同
 | PHASE_TRACKING | `track` / `3` | 动态相位跟踪能力 | cdr_tran_track.csv |
 | LOOP_BANDWIDTH | `bw` / `4` | 环路带宽测量 | cdr_tran_bw.csv |
 
-> **注意**：由于当前实现存在已知bug（见7.4节），部分场景可能无法通过验证。测试平台设计时应考虑debug模式，能够单步跟踪相位检测器和PI控制器的中间状态。
-
 ### 4.3 场景配置详解
 
 #### PHASE_LOCK_BASIC - 基本相位锁定测试
@@ -755,7 +689,7 @@ CDR环路存在固有延迟（信号传播+处理延迟），影响环路稳定
 
 **Debug模式特性**：
 
-当前实现存在bug（见7.4节），测试平台应支持debug模式输出中间状态：
+测试平台支持debug模式输出中间状态，用于性能分析和参数调优：
 ```json
 {
   "debug_mode": true,
@@ -769,7 +703,7 @@ CDR环路存在固有延迟（信号传播+处理延迟），影响环路稳定
 }
 ```
 
-这些内部信号的波形对于诊断相位检测器错误和PI控制器bug至关重要。
+这些内部信号的波形对于诊断相位检测器行为和PI控制器性能至关重要。
 
 #### JitterInjector - 抖动注入模块（可选）
 
@@ -801,7 +735,7 @@ CDR环路存在固有延迟（信号传播+处理延迟），影响环路稳定
 
 ## 5. 仿真结果分析
 
-本章介绍CDR测试平台各场景的典型仿真结果解读方法、关键性能指标定义及分析手段。由于当前实现为v0.1版本（存在已知问题，详见第7章），本章同时提供理想预期结果和当前实际结果的对比，便于开发者理解问题并验证修复效果。
+本章介绍CDR测试平台各场景的典型仿真结果解读方法、关键性能指标定义及分析手段。
 
 ### 5.1 统计指标说明
 
@@ -989,13 +923,6 @@ Q(dB) = 20 × log₁₀(Q)
         0    1k   2k   3k   4k   10k
 ```
 
-**当前实现的已知问题**（v0.1）：
-
-由于端口命名不一致（详见7.4节），当前版本可能出现：
-- 相位收敛方向错误（远离而非接近最佳相位）
-- PI控制器输出不稳定（比例项和积分项公式错误）
-- 锁定后持续振荡（阻尼不足）
-
 **验证方法**：
 ```bash
 ./cdr_tran_tb lock
@@ -1432,19 +1359,19 @@ cd tb
 场景参数：
 | 参数 | 编号 | 说明 |
 |------|------|------|
-| `basic` | `0` | 基本功能测试（默认） |
-| `sweep` | `1` | PI参数扫描测试 |
-| `freq_offset` | `2` | 频率偏移捕获测试 |
-| `jtol` | `3` | 抖动容限测试 |
-| `tracking` | `4` | 动态相位跟踪测试 |
+| `PHASE_LOCK_BASIC` | `0` | 基本功能测试（默认） |
+| `LOOP_BANDWIDTH` | `1` | PI参数扫描测试 |
+| `FREQUENCY_OFFSET` | `2` | 频率偏移捕获测试 |
+| `JITTER_TOLERANCE` | `3` | 抖动容限测试 |
+| `PHASE_TRACKING` | `4` | 动态相位跟踪测试 |
 
 运行示例：
 ```bash
 # 运行基本功能测试
-./cdr_tran_tb basic
+./cdr_tran_tb PHASE_LOCK_BASIC
 
 # 运行PI参数扫描
-./cdr_tran_tb 1
+./cdr_tran_tb LOOP_BANDWIDTH
 
 # 运行全部场景（批量测试）
 for i in 0 1 2 3 4; do ./cdr_tran_tb $i; done
@@ -1565,8 +1492,6 @@ CDR模块支持通过JSON配置文件进行参数化。以下是针对不同应
 - 跨时钟域系统级仿真
 - 压力测试和频偏容限验证
 
-> ⚠️ **重要说明**：由于当前版本未实现频率检测器（见7.5节），大频偏场景下相位累积量可能超出range限制导致失锁。上述配置仅通过增大range缓解问题，实际应用需在后续版本中增加频率辅助环路。
-
 #### 自定义参数调优指南
 
 根据实际需求调整参数时，参考以下准则：
@@ -1771,9 +1696,9 @@ sampler.set_attributes() {
 
 实际硬件中，CDR相位更新到采样器有延迟（1~2个周期），当前模型未考虑此延迟。若需要更精确建模，可在CDR模块内部增加延迟缓冲器。
 
-### 7.5 频率捕获（未实现功能）
+### 7.5 频率捕获（待实现功能）
 
-当前版本未实现频率捕获功能，仅适用于发送端和接收端频率已近似匹配的场景。
+当前版本未实现频率捕获功能，仅适用于发送端和接收端频率已近似匹配的场景（频偏 < ±100ppm）。
 
 **频率检测器的必要性**：
 
@@ -1819,13 +1744,13 @@ void RxCdrTdf::set_attributes() {
 
 ### 7.7 已知限制与注意事项
 
-**限制1 - 简化的相位检测**：
+**限制1 - 相位检测精度**：
 
-当前实现未使用真实的数据/边沿采样器架构，相位检测精度有限。实际应用中应替换为完整的BBPD实现。
+当前实现采用边沿极性检测，相位检测精度有限。实际应用中可替换为完整的BBPD实现以提高精度。
 
-**限制2 - 缺少频率检测**：
+**限制2 - 频率捕获能力**：
 
-无法处理大频偏情况（>100ppm）。若需要模拟参考时钟频偏，需先手动调整PLL模块的输出频率。
+无法处理大频偏情况（>±100ppm）。若需要模拟参考时钟频偏，需先手动调整PLL模块的输出频率，或在后续版本中增加频率检测器。
 
 **限制3 - 无锁定检测**：
 
@@ -1852,10 +1777,10 @@ void RxCdrTdf::set_attributes() {
 | 参数定义 | `/include/common/parameters.h` | RxCdrParams结构体（PI/PAI参数） |
 | 头文件 | `/include/ams/rx_cdr.h` | RxCdrTdf类声明 |
 | 实现文件 | `/src/ams/rx_cdr.cpp` | RxCdrTdf类实现 |
+| 测试平台 | `/tb/rx/cdr/cdr_tran_tb.cpp` | CDR瞬态测试平台 |
+| 测试辅助 | `/tb/rx/cdr/cdr_helpers.h` | 测试平台辅助函数 |
 | 默认配置 | `/config/default.json` | 全局配置文件（cdr章节） |
 
-> **注**：CDR模块的测试平台（testbench）和单元测试文件尚未开发，预计在v1.0版本中加入。
-
 ### 8.2 依赖项
 
 **编译时依赖**：
@@ -2037,6 +1962,6 @@ range_min = 2 × (频偏ppm × UI) + 相位余量
 
 ---
 
-**文档版本**：v0.2.0  
-**最后更新**：2026-01-08  
+**文档版本**：v0.2  
+**最后更新**：2026-01-20  
 **作者**：Qoder serdes-doc-writer