| name | pynq |
| description | 当用户需要为自己定制的开发板或已有开发板创建 PYNQ 工程、编译生成 PYNQ 镜像、定制板卡 BSP、编写板卡 .spec 文件、构建 SD 卡镜像、管理 PetaLinux BSP 层（meta-user、device-tree、kernel patch）、配置 PYNQ packages（pre.sh/qemu.sh/post.sh）、运行 pkgverify.sh 验证包、使用 flashsd.sh 烧写 SD 卡、使用 imgshell.sh 挂载编辑镜像、开发或加载 Overlay（BaseOverlay、自定义 Overlay、xsa overlay 工作流）、解析 HWH 文件、使用 PYNQ Python API（MMIO、DMA、GPIO、Interrupt 等）、在运行 PYNQ 镜像的板卡上编写/调试 Jupyter Notebook 代码时使用此技能。如需生成 bitstream 和 HWH 文件使用 vivado-synth、vivado-impl，如需编写时序约束使用 vivado-constraints，如需 TCL 自动化使用 vivado-tcl，如需硬件调试使用 vivado-debug。 |
PYNQ 开发指南
概述
PYNQ 是 Xilinx 的开源框架，通过 Python 和 Jupyter Notebook 简化 Zynq/MPSoC/RFSoC/Versal 平台的 FPGA 开发。此技能涵盖 PYNQ 镜像定制构建和 PYNQ 应用开发两部分。
完整命令语法、脚本帮助和参考文件索引请参阅 REFERENCE.md。
何时使用此技能
- 需要为自定义板卡构建 PYNQ 镜像
- 需要定制 PetaLinux BSP（device-tree、kernel patch、u-boot）
- 需要编写板卡 .spec 配置文件
- 需要创建自定义 Overlay（bitstream + HWH + Python API）
- 需要通过 xsa 文件加载 Overlay
- 需要在运行 PYNQ 的板卡上使用 Python API（MMIO、DMA、GPIO 等）
- 需要烧写 SD 卡镜像
- 需要调试 PYNQ packages（pre.sh / qemu.sh / post.sh）
- 需要挂载和编辑 PYNQ 镜像文件
工作流决策
选择正确的路径
| 你的目标 | 路径 | 关键步骤 |
|---|
| 从零为自定义板卡构建 PYNQ 镜像 | 自定义镜像构建 | 建立板卡目录 → 编写 .spec → 定制 BSP → 构建 base overlay → sdbuild |
| 使用已有板卡的 PYNQ 镜像开发应用 | Overlay 开发 | 加载已有 Overlay → 查看 ip_dict → 调用 PYNQ API |
| 已有 bitstream/xsa，只需 Python 封装 | xsa overlay 工作流 | 提供 xsa → Overlay("design.xsa") → 自动解析 |
| 给已有镜像添加/修改 packages | Package 开发 | 编写 pre.sh/qemu.sh/post.sh → pkgverify.sh 验证 |
Overlay 类型选择
| Overlay 类型 | 输入 | 适用场景 |
|---|
| 完整 bitstream + HWH | .bit + .hwh 文件 | Vivado 完整构建的参考设计 |
| xsa overlay | .xsa 文件 | 硬件工程师导出 xsa，软件工程师直接加载 |
| BaseOverlay（继承 pynq.Overlay） | bitstream + 自定义驱动类 | 需要封装板载外设 IP 驱动 |
加载 Overlay
from pynq import Overlay
overlay = Overlay("base.bit")
help(overlay)
from pynq.overlays.base import BaseOverlay
base_overlay = BaseOverlay("base.bit")
xsa overlay 工作流
- 硬件工程师导出 xsa 文件
- 软件工程师在运行 PYNQ 的板卡上执行
Overlay("design.xsa")
- 通过
ip_dict 查看 overlay 中包含的 IP
- 调用 PYNQ API 实现功能
Overlay Design
覆盖层由两个主要部分组成：PL 设计（bitstream）和 HWH 文件。
PL 设计
使用 Vivado 创建 Zynq 设计时，生成 bitstream（.bit）用于编程 Zynq PL。建议使用支持可编程性的 IP，通过内存映射连接到 GPIO 或具有与 PS 的主连接。PYNQ 提供 Python 库与 PL 设计交互。
如需生成 bitstream，使用 vivado-synth 和 vivado-impl 技能。
HWH 文件
HWH（硬件交接）文件由 Vivado IP Integrator 自动生成，PYNQ 通过它识别 Zynq 系统配置（IP 版本、中断、复位等）。HWH 文件名需与 .bit 文件名匹配（如 my_overlay.bit 和 my_overlay.hwh），缺失或文件名不匹配会报错。
HWH 位置：<prj>.gen/sources_1/bd/<bd_name>/hw_handoff/<bd_name>.hwh
Zynq PS 设置
PYNQ 镜像在启动时配置 Zynq PS（DRAM、SD 卡、以太网、USB、UART）。PS 配置包含系统时钟设置（包括 PL 时钟）。下载新 Overlay 时，时钟配置从 HWH 文件中解析并在下载前自动应用。
板卡目录结构
<your board name>/
├── base/ # Base Overlay 硬件抽象层
│ ├── notebooks/ # Jupyter 演示
│ ├── __init__.py # Python 包初始化
│ ├── base.py # BaseOverlay 类（继承 pynq.Overlay）
│ ├── Makefile # 构建脚本：调用 Vivado 生成 .bit 和 .hwh
│ └── <other files> # RTL 源码、IP 配置、XDC 约束
│
├── notebooks/ # 高级应用 Notebook
├── packages/ # 系统级软件包（由 .spec 控制加载）
│ └── <pkg_name>/
│ ├── pre.sh # 构建前钩子
│ ├── qemu.sh # QEMU 仿真启动
│ └── post.sh # 构建后钩子
│
├── petalinux_bsp/ # PetaLinux BSP 定制层
│ └── meta-user/ # Yocto meta-user 层
│ ├── conf/petalinuxbsp.conf
│ ├── recipe-bsp/ # device-tree、fsbl、u-boot
│ └── recipe-kernel/ # 内核配置片段和补丁
│
└── <board name>.spec # 板卡构建规格文件（核心入口）
完整 .spec 格式、代码示例和脚本帮助见 REFERENCE.md。
关键规则
- PYNQ 镜像中 pynq-venv 为完整 pynq 框架的 Python 环境，路径：
/usr/local/share/pynq-venv/
- 参考文档按需加载，不要读暂时没用到的文件
- HWH 文件名必须与
.bit 文件名一致（如 my_overlay.bit ↔ my_overlay.hwh）
- 已有 Overlay（包括官方 base overlay）位于
<PYNQ repository>/boards/<board>/base，可作为新设计的起点
相关技能
- vivado-synth — 生成 Overlay 所需的 bitstream（综合策略、资源推断）
- vivado-impl — bitstream 的布局布线和实现策略
- vivado-constraints — 为 base overlay 编写时序和物理约束（XDC）
- vivado-tcl — 自动化 Vivado 构建和报告生成
- vivado-debug — 硬件调试（ILA/VIO），板上信号观测
