PDM MCP Server

AI 驱动的 FPGA 功耗评估助手 — 将 Xilinx Power Design Manager (PDM) 的 Python API 封装为 MCP (Model Context Protocol) 服务，供 AI Agent 通过自然语言进行功耗建模与分析。

前置条件

• Python ≥ 3.10
• Xilinx PDM (Power Design Manager) 已安装
  • PDM 的 Python API (xv_pdm_pytasks) 必须可用
  • 安装路径会被自动检测（详见下方「PDM 路径配置」）

安装

从源码安装

git clone <repo-url>
cd pdm_mcp
pip install .

安装后可使用 pdm-mcp 命令：

pdm-mcp version   # 显示版本
pdm-mcp serve     # 启动 MCP server

PDM 路径配置

MCP Server 启动时会按以下优先级自动查找 PDM 安装路径：

1. PDM_HOME 环境变量 → $PDM_HOME/pdm.bat
2. 项目根目录的 path.txt 文件（格式：PDM：H:\path\to\PDM\bin）
3. 系统 PATH 中的 pdm.bat / pdm
4. 默认安装路径回退（C:/Xilinx/*/PDM/bin/pdm.bat 等）

若自动检测失败，可创建 path.txt 指定路径，或设置环境变量：

set PDM_HOME=H:\AMDDesignTools\PDM_2026.1\PDM\bin

MCP 客户端配置

在 AI 客户端（如 Kimi Code、Claude Desktop 等）中添加 MCP Server 配置：

{
  "mcpServers": {
    "pdm-mcp": {
      "command": "pdm-mcp",
      "args": ["serve"]
    }
  }
}

如果未安装到系统 PATH，指定完整路径：

{
  "mcpServers": {
    "pdm-mcp": {
      "command": "python",
      "args": ["-m", "pdm_mcp", "serve"],
      "cwd": "H:/path/to/pdm_mcp"
    }
  }
}

使用

MCP Server 提供 10 个工具，每个工具通过 action 参数选择具体操作。

---

1. session — 会话管理

action	参数	说明
start	session_id (默认 "default"), mode (默认 "py"), pdm_path, timeout	启动 PDM 子进程会话
stop	session_id	关闭指定会话
list	无	列出所有活跃会话

session(action="start")
session(action="list")
session(action="stop", session_id="my_session")

---

2. project — 项目管理

action	关键参数	说明
open	path	打开 .pdm 项目文件
create	name, part	创建新项目
close	无	关闭当前项目
save	save_path (可选)	保存/另存为
info	无	项目基本信息
list_blocks	无	列出所有 Block
list_architectures	无	列出可用 FPGA 架构
list_parts	architecture, package_filter	筛选器件型号
list_processes	无	列出工艺角 (Maximum/Typical)
select_part	part, process	更换器件
import_xpe	file, append	导入 XPE 文件
export_xdc	file, thermal, rails, overwrite	导出 XDC 约束
export_power_design	file, overwrite	导出 Power Design XML
reset	无	重置项目数据

project(action="open", path="my_design.pdm")
project(action="save")
project(action="info")
project(action="list_parts", architecture="Artix-7", package_filter="csg324")

---

3. power — 功耗查询

action	关键参数	说明
summary	无	总功耗摘要（自动保存快照）
block_power	block_name	指定 Block 功耗分解
rails	无	电源轨电压/电流/功耗
thermal	无	热分析（结温/θ-JA/裕量）
clock_power	无	各时钟域功耗
export_report	output_path	导出功耗报告

power(action="summary")
power(action="block_power", block_name="logic")
power(action="export_report", output_path="report.txt")

---

4. scenario — 场景配置

action	关键参数	说明
set_environment	temp, airflow, heatsink	温度/风流量/散热器
set_clock_frequency	name, freq_mhz	修改时钟频率
set_toggle_rate	block, pct	修改翻转率
set_resource_util	block, lut, ff, bram, dsp	修改资源用量（绝对数量）
recalculate	无	触发功耗重算
compare	无	对比两次功耗快照

scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
scenario(action="set_clock_frequency", name="clk_main", freq_mhz=200)
scenario(action="set_resource_util", block="logic", lut=50000, ff=60000, bram=80, dsp=100)
scenario(action="recalculate")
scenario(action="compare")

---

5. clock — 时钟管理

action	关键参数	说明
list	无	列出所有时钟
create	name, freq, io_type, io_standard, is_gated, min_freq	创建时钟
delete	name	删除时钟
edit	name, freq, io_type, ...	编辑时钟参数
settings	name	获取时钟设置
sample_settings	无	获取示例设置模板
replace	name, other, blocks	替换时钟引用
mgr_types	无	列出时钟管理器类型
mgr_list	无	列出现有时钟管理器
mgr_create	name, type, input_clock, vco_range	创建时钟管理器
mgr_delete	name	删除时钟管理器
mgr_settings	name	获取时钟管理器设置

clock(action="create", name="clk_200", freq=200, io_type="HD")
clock(action="mgr_create", name="mmcm1", type="MMCM", input_clock="clk_200")

---

6. ip — IP 核管理

action	关键参数	说明
types	无	列出可用 IP 类型
list	ip_type	列出指定类型的 IP 实例
create	ip_type, ip_name	创建 IP
delete	ip_type, ip_name	删除 IP
settings	ip_type, ip_name	获取 IP 当前设置
sample_settings	ip_type	获取 IP 设置模板

ip(action="types")
ip(action="list", ip_type="GTH")
ip(action="create", ip_type="GTH", ip_name="gth_0")

---

7. power_design — 电源设计

action	关键参数	说明
info	无	电源域/电源名称概览
rail_characteristics	无	电源轨特性详情
delivery_design	无	电源交付设计汇总
set_consolidation	mode	设置电源轨整合模式

power_design(action="info")
power_design(action="rail_characteristics")
power_design(action="set_consolidation", mode="Consolidated")

---

8. vivado — Vivado 数据导入

action	关键参数	说明
import_report	report_path, label	导入 Vivado 功耗报告
compare	label	与 PDM 结果逐项对比
import_utilization	util_report_path, block_name	导入利用率报告

vivado(action="import_report", report_path="post_route_power.rpt")
vivado(action="compare", label="vivado_import")
vivado(action="import_utilization", util_report_path="utilization.rpt")

---

9. estimate — 快速估算（无需 PDM 会话）

action	关键参数	说明
quick	part, clock_mhz, lut_pct, ...	快速功耗估算 (±40%)
recommend	budget, logic_cells, family	根据预算推荐器件
families	无	列出支持的 FPGA 系列

estimate(action="quick", part="xc7a100tcsg324-1", clock_mhz=200, lut_pct=60)
estimate(action="recommend", budget=3.0, logic_cells=50000, family="7series")
estimate(action="families")

---

10. explore — 属性探索

action	关键参数	说明
block_resources	block	列出 Block 的资源名
block_summaries	block	列出 Block 的汇总表名
resource_info	block, resource	获取资源字段名/记录名
resource_defaults	block, resource	获取资源默认值
resource_valid_values	block, resource, fields	获取字段有效值范围
summary_info	target, summary	获取汇总表详情
list_property	target	列出对象属性名
report_property	target, pattern, all_props, detail	报告对象属性
reset_property	target, prop	重置属性为默认值

explore(action="block_resources", block="logic")
explore(action="resource_defaults", block="logic", resource="logic_config")
explore(action="report_property", target="project", pattern="*", all_props=True)

---

使用模板

以下是常见场景的操作模板。直接将这些指令告诉 AI Agent 即可。

---

模板 A：设计前期最大功耗快速评估（无 PDM 项目）

器件尚未确定，需要快速估算最坏情况功耗，给出电源设计余量。

1. 调用 estimate(action="families")，了解有哪些 FPGA 系列可选。
2. 用 estimate(action="quick") 做粗估。关键参数：
   - part: 候选器件，如 "xc7a100tcsg324-1"
   - clock_mhz: 主时钟频率
   - lut_pct / ff_pct / bram_pct / dsp_pct: 设为预期的最大值（如 80-90）
   - io_count / io_standard / io_toggle: IO 数量和翻转率
   - temp / airflow / heatsink: 环境条件
3. 多选几个候选器件重复 quick 估算，比较结温。
4. 用 estimate(action="recommend")，传入功耗预算和资源需求，验证选型。
5. 电源余量建议：总功耗 × 1.3 ~ 1.5 作为电源设计目标。

示例对话：

用户: 我在设计一个 200MHz 主频、占用约 70% LUT 的逻辑，用 xc7a100t，
      想知道最大功耗大概多少，电源要留多少余量。
      (AI 自动调用 estimate quick → 返回总功耗和结温 → 建议余量)

---

模板 B：精确功耗评估（基于 PDM 项目）

已有 RTL / Vivado 工程，需要精确评估并导出约束到 PCB 设计。

1. session(action="start")
2. project(action="create", name="my_design", part="xc7a100tcsg324-1")
3. 用 explore(action="block_resources", block="logic") 查看可用资源字段。
4. 用 scenario(action="set_resource_util") 填入综合后的 LUT/FF/BRAM/DSP 用量（绝对数量）。
   例如 ``lut=50000, ff=60000, bram=80, dsp=100``。
5. 用 clock(action="create") 创建设计中的时钟，或 scenario(action="set_clock_frequency")
   修改已有时钟。
6. 用 scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
   设置工作环境。
7. scenario(action="recalculate") 重算功耗。
8. power(action="summary") 查看总功耗，power(action="thermal") 检查结温是否超标。
9. 如结温过高，调整 airflow 或 heatsink，重复步骤 7-8。
10. project(action="export_xdc", file="thermal.xdc") 导出散热约束。
11. power_design(action="rail_characteristics") 查看电源轨特性，确定每路电源需求。
12. project(action="save")
13. session(action="stop")

---

模板 C：导入 Vivado 结果并验证

综合/布线已完成，导入 Vivado 报告验证 PDM 建模精度。

1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. vivado(action="import_report", report_path="post_route_power.rpt")
4. vivado(action="import_utilization", util_report_path="utilization.rpt", block_name="logic")
5. scenario(action="recalculate")
6. vivado(action="compare")  → 总功耗和各项逐项对比，>10% 差异标记 WARN。
7. 根据差异调整 PDM 参数（调用 scenario / clock），重复步骤 5-6。
8. project(action="save")
9. session(action="stop")

---

模板 D：多场景功耗对比

同一设计在不同频率、温度下的功耗差异。

1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. power(action="summary")                         → 保存快照 A（基准）
4. scenario(action="set_clock_frequency", 
            name="clk_main", freq_mhz=300)         → 调整频率
5. scenario(action="recalculate")
6. power(action="summary")                         → 保存快照 B
7. scenario(action="compare")                      → 对比 A vs B
8. scenario(action="set_environment", 
            temp=85, airflow=0, heatsink="none")   → 调整环境
9. scenario(action="recalculate")
10. power(action="summary")                        → 保存快照 C
11. scenario(action="compare")                     → 对比 B vs C
12. session(action="stop")

---

模板 E：器件选型与 Part 替换

当前器件功耗超标，需要更换器件并重新评估。

1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. project(action="list_parts", architecture="Artix-7")  → 查看同架构备选器件
4. power(action="summary")                                → 当前功耗
5. project(action="select_part", part="xc7a200tfbg484-2") → 换更大器件
6. scenario(action="recalculate")
7. power(action="summary")                                → 验证新器件功耗和结温
8. 若不满意，重复步骤 5-7。
9. project(action="save", save_path="my_design_a200t.pdm")
10. session(action="stop")

---

模板 F：时钟系统规划

从零配置复杂时钟网络（含 MMCM/DPLL）。

1. session(action="start")
2. project(action="create", name="clock_design", part="xcku3p-ffva676-1-i")
3. clock(action="sample_settings")                           → 了解时钟设置模板结构
4. clock(action="create", name="sys_clk", freq=125, 
         io_type="HD", io_standard="LVCMOS 1.8V")            → 创建系统时钟
5. clock(action="mgr_types")                                 → 查看可用的时钟管理器
6. clock(action="mgr_create", name="mmcm_sys",
         type="MMCM", input_clock="sys_clk", vco_range="Low") → 创建 MMCM
7. clock(action="mgr_settings", name="mmcm_sys")             → 查看 MMCM 产生的输出时钟
8. scenario(action="recalculate")
9. project(action="save")
10. session(action="stop")

---

模板 G：电源轨设计与原理图检查

导出电源设计数据，提供给硬件工程师做原理图检查。

1. session(action="start")
2. project(action="open", path="my_design.pdm")
3. scenario(action="set_environment", temp=85,
            airflow=250, heatsink="medium")
4. scenario(action="recalculate")
5. power_design(action="info")                               → 查看电源域和电源名称
6. power_design(action="rail_characteristics")               → 查看每路电压/电流
7. power_design(action="delivery_design")                    → 查看电源交付方案
8. power_design(action="set_consolidation", 
               mode="Consolidated")                          → 尝试整合模式
9. power_design(action="delivery_design")                    → 对比整合后的方案
10. project(action="export_power_design", 
            file="power_design.xml")                         → 导出 XML 供原理图检查
11. project(action="export_xdc", file="thermal.xdc",
            thermal="Ambient")                               → 导出环境温度约束
12. project(action="save")
13. session(action="stop")

---

模板 H：导入 XPE 快速起步

已有 Vivado XPE 文件，直接导入作为起点。

1. session(action="start")
2. project(action="create", name="from_xpe", part="xc7a100tcsg324-1")
3. project(action="import_xpe", file="baseline.xpe")          → 导入 XPE 数据
4. power(action="summary")                                    → 查看导入后的功耗
5. explore(action="block_resources", block="logic")           → 查看 XPE 填充了哪些资源
6. scenario(action="set_environment", temp=85, airflow=250,
            heatsink="medium")
7. scenario(action="recalculate")
8. power(action="summary")
9. project(action="save")
10. session(action="stop")

---

模板 I：同设计跨器件功耗对比（基于 PDM）

同一套设计参数（资源、时钟、环境），在不同 FPGA 型号上的功耗和结温差异。

1. session(action="start")
2. project(action="open", path="my_design.pdm")

   # ---- 器件 A ----
3. scenario(action="set_resource_util", block="logic",
            lut=50000, ff=60000, bram=80, dsp=100)
4. clock(action="create", name="clk_main", freq=200)
5. scenario(action="set_environment", temp=85, airflow=250, heatsink="medium")
6. scenario(action="recalculate")
7. power(action="summary")                                → 保存快照（器件 A）

   # ---- 器件 B ----
8. project(action="select_part", part="xc7a200tfbg484-2") → 切换到更大器件
9. scenario(action="recalculate")
10. power(action="summary")                               → 保存快照（器件 B）
11. scenario(action="compare")                            → 对比 A vs B

    # ---- 器件 C ----
12. project(action="select_part", part="xcku3p-ffva676-1-i") → 切换到 UltraScale
13. scenario(action="recalculate")
14. power(action="summary")                               → 保存快照（器件 C）
15. scenario(action="compare")                            → 对比 B vs C

16. session(action="stop")

说明：compare 对比的是最近两次 power(summary) 的快照。三器件以上需两两依次对比，每次 compare 后记录输出即可。

---

模板 J：纯快速估算跨器件对比（无需 PDM）

连 PDM 项目都不需要，直接用 estimate quick 快速比较多个器件。

1. estimate(action="quick", part="xc7a35tcsg324-1", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A35T → 功耗 X.XW, 结温 YY°C

2. estimate(action="quick", part="xc7a100tcsg324-1", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A100T → 功耗 X.XW, 结温 YY°C

3. estimate(action="quick", part="xc7a200tfbg484-2", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: A200T → 功耗 X.XW, 结温 YY°C

4. estimate(action="quick", part="xcku3p-ffva676-1-i", clock_mhz=200,
            lut_pct=70, temp=85, airflow=250, heatsink="medium")
   → 记录: KU3P → 功耗 X.XW, 结温 YY°C

5. 横向比较四个器件的总功耗和结温，选择最优性价比型号。

---

11. guide — 引导式评估向导

只需告诉 AI "我想评估 xxx 的功耗"，AI 会调用本工具一步步询问所需参数， 每步给出可选值，无需记忆任何工具名。

流程：器件型号 → 评估模式（quick/pdm/vivado） → 逐步填参 → 自动计算结果。

# 用户: "我想评估 xc7a100t 的功耗"
# AI 自动调用:
guide(step="start")
# → 返回: "请输入 FPGA 器件型号"
guide(step="device", value="xc7a100tcsg324-1")
# → 返回: "选择评估模式: quick / pdm / vivado"
guide(step="mode", value="quick", device="xc7a100tcsg324-1")
# → 返回: "主时钟频率是多少 (MHz)？"
guide(step="quick_clock_mhz", value="200", device="xc7a100tcsg324-1")
# → 返回: "LUT 利用率大约多少 (%)？"
# ... 逐步收集参数 ...
# → 最终返回: 功耗估算结果（含 breakdown、结温）

示例对话：

用户: 我想评估 xc7a100t 的功耗，200MHz 主频，资源用了大概 70%
AI:   (自动调用 guide → 收集参数 → 返回总功耗 1.2W，结温 45°C，建议电源余量 1.8W)

开发

运行测试

pip install -e ".[dev]"
pytest tests/ -v

项目结构

pdm_mcp/
├── src/pdm_mcp/
│   ├── __main__.py           # CLI 入口 (pdm-mcp serve)
│   ├── server.py             # FastMCP 实例 + 工具注册
│   ├── config.py             # PDM 路径检测
│   ├── analysis/
│   │   ├── estimator.py      # 快速功耗估算模型
│   │   └── power_parser.py   # Vivado 报告解析器
│   ├── session/
│   │   ├── pdm_session.py    # PDM 子进程管理（哨兵协议）
│   │   ├── session_manager.py # 多会话生命周期
│   │   └── base_session.py   # 抽象基类 + PdmResult
│   └── tools/                # 10 个 MCP 工具
│       ├── session_tools.py
│       ├── project_tools.py
│       ├── power_tools.py
│       ├── scenario_tools.py
│       ├── clock_tools.py
│       ├── ip_tools.py
│       ├── power_design_tools.py
│       ├── import_tools.py
│       ├── estimate_tools.py
│       └── exploration_tools.py
├── scripts/mainloop.py       # PDM 子进程 REPL
├── tests/                    # 测试
├── docs/                     # UG1781 参考文档
└── pyproject.toml

Bug 反馈

请通过以下任一方式提交反馈：

• GitHub Issues: 在项目仓库提交 Issue，附上以下信息：

  • pdm-mcp version 输出
  • 完整的错误信息 / 堆栈跟踪
  • 复现步骤
  • PDM 版本 (pdm.bat 所在目录名即为版本号)

• 日志: 启动 MCP Server 时会输出日志到 stderr，包含 PDM 路径检测信息和运行时错误。如果遇到问题，请附上日志。

• 常见问题排查:

  问题	可能原因	解决方法
  PDM 路径检测失败	PDM 未安装或路径不在默认位置	设置 PDM_HOME 或创建 path.txt
  会话 'xxx' 不存在	未调用 session(action="start")	先启动会话再操作
  No project open	未调用 project(action="open")	先打开项目再查询
  功耗值为 0	未设置资源利用率或时钟频率	调用 scenario 配置参数后 recalculate