Rtl Scanner

RTL Scanner 2.0 - 智能 RTL 代码质量工具

一站式 RTL 代码扫描、filelist 生成、编译验证工具，支持多 LLM 集成

](https://github.com/your-org/rtl-scanner)  

📑 目录

• 5分钟快速开始
• 重要：LLM 使用说明
• 功能特性
• 安装
• 使用指南

- CLI 命令 - Cursor 集成

• 配置
• 常见问题
• 高级功能

🚀 5分钟快速开始

第 1 步：安装

# 克隆或下载项目
cd RTL-TB

# 安装依赖
pip install -r requirements.txt

第 2 步：第一次扫描

# 扫描测试目录
python -m rtl_scan_cli.cli scan ./test

# 输出：
# 🔍 RTL 代码扫描结果
# 📁 扫描文件: 4
# ⚠️  发现问题: 10
#   ❌ Error: 3
#   ⚠️  Warning: 5
#   ℹ️  Info: 2

🎉 完成！

这就是最基本的使用！更多功能请继续阅读下面的章节。

⚡ 重要：LLM 使用说明

核心概念

并非所有功能都使用 LLM！ 你可以完全控制是否使用 LLM。

推荐策略

# ✅ 推荐：日常使用（免费）
rtl-scan scan ./rtl                    # 扫描代码
rtl-scan filelist-custom my_config     # 生成 filelist（通过构建系统）

# ✅ 可选：复杂场景（需要 API Key）
export OPENAI_API_KEY="sk-xxx"
rtl-scan ask "帮我检查代码质量"

# ✅ CI/CD：永远用直接命令（免费、快速）
rtl-scan scan ./rtl --format json

成本对比

🎯 功能特性

核心工具（4个）

核心特性

• ✅ 智能扫描：40 条检测规则，覆盖常见 testbench/仿真痕迹
• ✅ 定制化构建：集成项目构建系统（如 dj 命令），自动过滤 testbench 文件
• ✅ 自动修复：支持 9 种规则的自动补丁生成
• ✅ 白名单机制：3 层白名单（文件级、行级、下一行）
• ✅ 多 LLM 支持：OpenAI/Claude/Ollama 三选一
• ✅ 零依赖 LLM：核心功能完全免费，无需 API Key

40 条扫描规则

完整规则列表: 查看 DEVELOPER_GUIDE.md

白名单机制

// 1. 整个文件豁免
// mcp:allow-file

// 2. 单行豁免
$display("debug"); // mcp:allow

// 3. 下一行豁免
// mcp:allow-next-line
initial begin
  reset = 1;
end

📦 安装

方式 1：从源码（当前推荐）

git clone 
cd RTL-TB
pip install -r requirements.txt

方式 2：从 PyPI（未来）

pip install rtl-scanner

验证安装

python -m rtl_scan_cli.cli --version
# 输出：rtl-scan, version 2.0.0

📖 使用指南

CLI 命令

scan - 扫描代码

# 基础扫描
python -m rtl_scan_cli.cli scan 

# 选项
--format json|markdown|pretty  # 输出格式
--max-findings 100            # 限制结果数
--no-color                    # 禁用颜色

# 示例
python -m rtl_scan_cli.cli scan ./rtl
python -m rtl_scan_cli.cli scan ./rtl --format json > result.json

输出示例：

🔍 RTL 代码扫描结果

📁 扫描文件: 156
⚠️  发现问题: 23
  ❌ Error: 5
  ⚠️  Warning: 15
  ℹ️  Info: 3

详细问题（前10条）：
1. ❌ rtl/core/alu.sv:45
   规则: initial_block
   说明: initial 在 RTL 中通常不允许

filelist-custom - 生成 Filelist（用构建系统）

# 使用项目构建系统
python -m rtl_scan_cli.cli filelist-custom 

# 示例
python -m rtl_scan_cli.cli filelist-custom my_chip_config

背后执行（根据你的项目配置）：

source /proj/verif_release_ro/cbwa_initscript/current/cbwa_init.csh;
bootenv;
clobber all;
dj -c -m 8 -v -J local bs my_chip_config

ask - 智能模式（需要 LLM）

# 自然语言交互
python -m rtl_scan_cli.cli ask ""

# 示例
python -m rtl_scan_cli.cli ask "扫描 rtl 目录并生成报告"
python -m rtl_scan_cli.cli ask "用 my_config 配置生成 filelist"
python -m rtl_scan_cli.cli ask "检查代码质量给出建议"

注意：需要先设置 API Key（见配置章节）

config - 配置管理

# 初始化配置文件
python -m rtl_scan_cli.cli config init

# 显示当前配置
python -m rtl_scan_cli.cli config show

Cursor 集成

配置方法

1. 打开 Cursor 设置（Ctrl+, 或 Cmd+,）
2. 搜索 "MCP"
3. 添加以下配置：

{
  "mcpServers": {
    "rtl-scanner": {
      "command": "python",
      "args": ["-m", "rtl_scan_server.server"],
      "cwd": "C:/Users/nanyang2/Downloads/RTL-TB"
    }
  }
}

注意：修改 cwd 为你的实际项目路径。

使用方式

在 Cursor 中直接对话：

你："扫描 rtl 目录"
→ Cursor 自动调用 scan_rtl 工具

你："生成 filelist"
→ Cursor 自动调用 generate_filelist 工具

你："用 my_config 配置生成 filelist"
→ Cursor 自动调用 generate_filelist_custom 工具

⚙️ 配置

初始化配置文件

python -m rtl_scan_cli.cli config init

配置文件位置：~/.rtl-scan/config.yaml（Windows）或 ~/.rtl-scan/config.yaml（Linux/Mac）

配置示例

# LLM 配置
llm:
  default: openai  # 默认使用哪个 LLM
  
  # OpenAI GPT-4
  openai:
    model: gpt-4-turbo
    api_key: ${OPENAI_API_KEY}  # 从环境变量读取
    base_url: https://api.openai.com/v1
  
  # Anthropic Claude
  anthropic:
    model: claude-3-sonnet-20240229
    api_key: ${ANTHROPIC_API_KEY}
  
  # Ollama 本地模型（免费）
  ollama:
    model: llama3
    base_url: http://localhost:11434
    enabled: true
  
  # 降级策略
  fallback:
    enabled: true
    order: [openai, anthropic, ollama]

# 扫描配置
scan:
  exclude:
    - "**/tb/**"
    - "**/test/**"
  max_findings: 500

# Filelist 配置（定制化构建）
filelist:
  default_init_script: /proj/verif_release_ro/cbwa_initscript/current/cbwa_init.csh
  default_build_command: "dj -c -m 8 -v -J local bs {config_name}"

设置 API Keys

# Windows PowerShell
$env:OPENAI_API_KEY="sk-xxx"
$env:ANTHROPIC_API_KEY="sk-ant-xxx"

# Linux/Mac
export OPENAI_API_KEY="sk-xxx"
export ANTHROPIC_API_KEY="sk-ant-xxx"

# 或使用免费的本地 Ollama
# 1. 安装 Ollama: https://ollama.ai
# 2. 启动服务: ollama serve
# 3. 下载模型: ollama pull llama3
# 4. 在配置中设置 default: ollama

❓ 常见问题

Q1：什么时候会使用 LLM？

A：只有以下情况会使用 LLM：

• CLI 的 ask 命令
• Cursor 中的自然语言交互（使用 Cursor 的 LLM）

其他所有直接命令（scan、filelist-custom）都不使用 LLM，完全免费。

Q2：我需要 API Key 吗？

A：看情况：

Q3：扫描速度如何？

A：

• 1000 个文件约 3-5 秒
• 支持大型项目（10000+ 文件）

Q4：会误报吗？

A：可能会有误报，提供 3 层白名单机制：

1. 代码注释：// mcp:allow
2. 路径白名单：配置中排除特定目录
3. 编译宏：用 ifdef 条件编译

Q5：支持哪些文件类型？

A：.v、.sv、.vh、.svh（可自定义）

Q6：如何处理第三方 IP？

A：在配置中添加路径白名单：

scan:
  exclude:
    - "ip/vendor_x/**"
    - "external/**"

Q7：CI/CD 如何集成？

A：使用直接命令 + JSON 输出：

# .gitlab-ci.yml
rtl_check:
  script:
    - python -m rtl_scan_cli.cli scan ./rtl --format json > scan.json
    - python -m rtl_scan_cli.cli filelist-custom my_config

Q8：中文乱码怎么办？

A：

# Windows PowerShell
$env:PYTHONIOENCODING="utf-8"

🎨 高级功能

路径白名单

在 filelist 生成时使用：

# 配置文件中
scan:
  pathWhitelist:
    - "ip/vendor_**"
    - "rtl/legacy/**"

编译宏白名单

在 VCS 验证时使用：

# 在代码中
`ifdef ALLOW_INITIAL
initial begin
  data = 0;
end
`endif

# 验证时添加宏
python -m rtl_scan_cli.cli filelist-custom my_config --defines ALLOW_INITIAL

自动修复补丁

扫描后生成修复建议（通过 Cursor 或 ask 命令）。

📊 典型使用流程

流程 1：日常开发

# 1. 修改代码后扫描
python -m rtl_scan_cli.cli scan ./rtl/core

# 2. 查看问题并修复

# 3. 重新扫描确认
python -m rtl_scan_cli.cli scan ./rtl/core

流程 2：提交前检查

# 1. 扫描所有代码
python -m rtl_scan_cli.cli scan ./rtl

# 2. 生成 filelist（通过构建系统）
python -m rtl_scan_cli.cli filelist-custom soc_config

# 3. 通过后提交
git commit -m "Fix RTL issues"

流程 3：定制化项目

# 使用项目构建系统
python -m rtl_scan_cli.cli filelist-custom my_chip_config -o build/chip.f

# 验证生成的 filelist
python -m rtl_scan_cli.cli filelist-custom chip_config

📚 附录

快速参考

常用命令速查：

# 扫描代码
python -m rtl_scan_cli.cli scan 

# 生成 filelist（用构建系统）
python -m rtl_scan_cli.cli filelist-custom 

# 验证编译
python -m rtl_scan_cli.cli filelist-custom 

# 智能模式（LLM）
python -m rtl_scan_cli.cli ask "
"

# 配置管理
python -m rtl_scan_cli.cli config init
python -m rtl_scan_cli.cli config show

# 帮助
python -m rtl_scan_cli.cli --help
python -m rtl_scan_cli.cli  --help

项目结构

RTL-TB/
├── rtl_scan_server/     # MCP Server
├── rtl_scan_cli/        # CLI 工具
├── config/              # 配置模板
├── examples/            # VCS 参数示例
├── test/                # 测试文件
└── README.md            # 本文档

配置文件示例

完整示例见 config/config.yaml.example

VCS 参数示例

• examples/vcs_general.json - 通用项目
• examples/vcs_soc.json - SoC 项目
• examples/vcs_ip_block.json - IP 模块

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

📞 获取帮助

• 查看本文档的常见问题章节
• 运行 python -m rtl_scan_cli.cli --help
• 提交 Issue

🎉 开始使用 RTL Scanner，享受自动化的代码质量保障！

_Version: 2.0.0 | Last Updated: 2025-01-13_