chip-spyglass-cdc-resolver

name	chip-spyglass-cdc-resolver
description	Use when processing SpyGlass CDC reports to resolve violations. Triggers on 'cdc违例', 'cdc violation', 'cdc report', 'cdc分析', 'cdc waive', 'cdc修复', 'cdc resolver'. Maps CDC rules to priority levels, proposes RTL fixes or generates waiver files.

Chip SpyGlass CDC Resolver

分析 SpyGlass CDC 报告，通过 LLM 与知识库中的 CDC 规则信息，对 RTL 进行分析，给出修改建议或生成 waiver 文件。

When to Use

• 处理 chip-spyglass-cdc-chk 生成的 CDC 报告（cdc_summary.log、cdc_verify.log）
• 需要分析 CDC 违例的根因并给出 RTL 修改建议
• 需要为可接受的违例生成 waiver 文件
• CDC 签核前的违例清理

核心工作流

0. 加载 Blackbox 模块列表
1. 解析 CDC 报告 → 提取 (rule, severity, file, line, message) 元组
2. 过滤 Blackbox → 模块在 blackbox 列表中的违例自动 waive
3. 按优先级分类违例 → P0~P7
4. 对 P0 违例：必须修复，LLM 分析 RTL 给出修改方案
5. 对 P1~P7 违例：LLM 分析判断是否真问题，修复或 waive
6. 输出：RTL 修改建议 + waiver 文件

Step 0: 加载 Blackbox 模块列表

读取 blackbox-modules.md（本 SKILL.md 同目录），加载 blackbox 模块列表。

判定规则：

• 模块名匹配 blackbox 列表条目，或
• 违例文件路径包含 blackbox 模块名（如 ip/pll_top/pll_clk_gen.v 匹配 pll_top）

Blackbox 模块典型类型：

• 第三方 IP（非团队所有）
• 已验证 IP（已 tape-out 证明）
• 硬宏或模拟封装
• 明确排除在 CDC 检查范围外的模块

如果 blackbox-modules.md 为空或不存在，跳过此步骤。

Step 1: 解析 CDC 报告

CDC 报告来自 chip-spyglass-cdc-chk 的输出，典型路径：

• {module}_work/ds/report/cdc/cdc_summary.log — 汇总报告
• {module}_work/ds/report/cdc/5_cdc_verify.log — 详细违例
• {module}_work/ds/report/cdc/4_cdc_verify_struct.log — 结构检查

SpyGlass 日志格式：

Warning [<rule_name>] <file>:<line> <message>
Error [<rule_name>] <file>:<line> <message>

提取：rule_name、severity、file path、line number、violation message。

如果日志格式未知，要求用户粘贴样本或指定格式。

Step 2: 过滤 Blackbox 违例

对每个解析出的违例，检查其模块是否在 blackbox 列表中：

module_name ← 从文件路径提取（如 "pll_top" 从 "ip/pll_top/pll_clk_gen.v"）
if module_name in blackbox_list:
    → 标记为 BLACKBOX_WAIVED，跳过优先级分析

所有 blackbox waive 的违例在 waiver 文件中单独一节输出。

Step 3: 按优先级分类违例

查 cdc-rules-reference.md（本 SKILL.md 同目录）中的规则映射表。

rule_name → P0/P1/P2/P3/P4/P5/P6/P7

如果规则不在映射表中：

• 标记为 "unknown rule"
• 提示用户手动分类

Step 4: 执行优先级动作

优先级	动作	输出
P0 (Ac_unsync01/02)	必须修复，禁止 waive。 LLM 分析 RTL，给出同步器添加方案	RTL 修改建议
P1 (Ac_conv01~05)	分析判断。 LLM 检查是否真收敛问题。若是 → 用 gray_signals 或异步 FIFO 修复；若否 → waive	修复或 waive
P2 (Ac_glitch*)	分析判断。 LLM 检查同步器输入是否来自寄存器。若否 → 修复；若是 → waive	修复或 waive
P3 (Ac_cdc01)	分析判断。 LLM 检查快→慢时钟域信号是否需要脉冲展宽	修复或 waive
P4 (Ac_datahold01a)	分析判断。 LLM 检查 qualifier 保护下数据是否稳定	修复或 waive
P5 (Ac_cdc08)	分析判断。 LLM 检查多 bit 信号是否需要异步 FIFO	修复或 waive
P6 (Ar_*)	分析判断。 LLM 检查异步复位是否需要同步释放	修复或 waive
P7 (Ac_fifo01)	分析判断。 LLM 确认异步 FIFO 正确性	修复或 waive

关键规则：P0（Ac_unsync01/02）绝对禁止 waive，必须从设计层面修复。

Step 5: 生成输出

5a. RTL 修改建议 (cdc_fix_proposal.md)

# CDC Fix Proposal

## Summary
- Total violations: N
- Blackbox waived: N
- P0 must-fix: N (Ac_unsync01/02)
- P1~P7 reviewed: N
  - Fix required: N
  - Waived: N
- Unknown rules: N

## P0 — Must Fix (NEVER Waive)

### [P0] Ac_unsync01 — <file>:<line>
**Violation:** <message>
**Root Cause:** <分析>
**Fix:**
```verilog
// Before
<原始代码>

// After — 添加双触发器同步器
<修复代码>

P1~P7 — Reviewed

[P1] Ac_conv01 — :

Violation: Assessment: <真收敛问题 / 误报> Action: Fix / Waive Fix (if applicable): ...

[P6] Ar_unsync01 — :

Violation: Assessment: <需要同步释放 / 已正确处理> Action: Fix / Waive

#### 5b. Waiver 文件 (`{module}.cdc.waiver`)

SpyGlass waiver 文件格式：

```waiver
// Auto-generated CDC waiver file
// Module: {module}
// Date: YYYY-MM-DD
// Generated by chip-spyglass-cdc-resolver

// === Blackbox Module Waives ===
waive -rule <rule> -file <file> -line <line> -message "BLACKBOX: <module> is in blackbox list (<reason>)"

// === P1~P7 Conditional Waives ===
waive -rule <rule> -file <file> -line <line> -message "<reason>"

// === Constraint-based Waives (推荐替代方案) ===
// quasi_static -name "cfg_*"           — 准静态信号
// set_case_analysis -value 0 [get_ports test_mode]  — MUX 选择端
// cdc_false_path -from src -to dst     — 非功能路径

Waive 理由：

• BLACKBOX 模块："BLACKBOX: <module> is in blackbox list (<reason>)"
• P1~P7 无真实问题："Reviewed: no functional impact, <explanation>"
• 误报："False positive: <explanation>"
• 约束可解决："Can be resolved by <quasi_static|set_case_analysis|cdc_false_path>"

注意：对于 quasi_static、set_case_analysis、cdc_false_path 可解决的违例，优先建议修改 SGDC 约束而非 waive。

Step 6: Wiki 知识查询

对复杂违例，查询 wiki 获取规则详情：

wiki query: "<rule_name> CDC violation fix"

Wiki 提供：

• 规则定义和原理
• 常见违例模式
• 标准修复方案
• 相关编码规范

利用 wiki 知识提高根因分析和修复建议的质量。

输出文件

文件	用途	位置
cdc_fix_proposal.md	RTL 修改建议	与 CDC 报告同目录
{module}.cdc.waiver	CDC waiver 文件	ds/run/ 目录

参考文件

文件	说明
cdc-rules-reference.md	CDC 规则 → 优先级映射（P0~P7）+ 分析指引
blackbox-modules.md	可配置的 blackbox 模块列表（自动 waive）

常见错误

问题	处理
规则不在映射表	标记 unknown，提示用户分类
日志格式未知	要求用户粘贴样本
用户要求 waive P0	拒绝，提示 P0 必须修复
wiki 知识不可用	使用通用知识继续，标注 "wiki unavailable"
blackbox-modules.md 为空	跳过 blackbox 检查，处理所有违例
模块名不明确	同时匹配文件路径和模块声明

与 chip-spyglass-cdc-chk 的关系

chip-spyglass-cdc-chk → 执行 CDC 检查 → 生成 cdc_summary.log
                    ↓
chip-spyglass-cdc-resolver → 分析违例 → 生成修复建议 + waiver 文件