AGENT SKILL

pynq

当用户需要为自己定制的开发板或已有开发板创建 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。

适用职业开发工程师
License 许可
GPL-2.0
最近更新
2026-05-07
Stars
★ 3
Forks
0

01 前言 Front Matter

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。

02 资源文件 124

03 SKILL.md 正文

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")  # 自动下载 bitstream 并解析 HWH

# 查看 Overlay 包含的 IP
help(overlay)

# BaseOverlay(封装了板载外设驱动)
from pynq.overlays.base import BaseOverlay
base_overlay = BaseOverlay("base.bit")

xsa overlay 工作流

  1. 硬件工程师导出 xsa 文件
  2. 软件工程师在运行 PYNQ 的板卡上执行 Overlay("design.xsa")
  3. 通过 ip_dict 查看 overlay 中包含的 IP
  4. 调用 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。

关键规则

  1. PYNQ 镜像中 pynq-venv 为完整 pynq 框架的 Python 环境,路径:/usr/local/share/pynq-venv/
  2. 参考文档按需加载,不要读暂时没用到的文件
  3. HWH 文件名必须与 .bit 文件名一致(如 my_overlay.bit ↔ my_overlay.hwh)
  4. 已有 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),板上信号观测

04 同仓库更多 Skills

ra9fael
ra9fael/xilinx-skills

xilinx-docs

当用户需要查找xilinx官方文档时使用该技能

★ 3
ra9fael
ra9fael/xilinx-skills

vivado-tcl

当用户想要生成、编写或执行 Vivado/Vitis TCL 脚本用于 FPGA 设计流程时使用此技能。包括创建项目、运行综合/实现、编程设备、使用 IP Integrator 块设计、插入调试核、管理约束、仿真以及任何 Vivado 自动化任务。当用户提及 Vivado、Vitis、FPGA、硬件设计的 TCL 脚本、比特流生成、XDC 约束、ILA/VIO 调试或任何 Xilinx/AMD FPGA 工具链任务时触发。此技能生成并执行 TCL——它不分析 Vivado 输出或报告。对于调试策略和调试核配置决策使用 vivado-debug,对于时序分析使用 vivado-analysis。

视觉设计
★ 3
ra9fael
ra9fael/xilinx-skills

vivado-synth

当用户需要 Vivado 综合策略选择、综合属性配置、synth_design 选项调优、资源推断控制(RAM/DSP/SRL/BRAM)、层次结构优化(flatten_hierarchy、KEEP_HIERARCHY)、OOC(离屏)综合、增量综合、RTL linting、块级综合(BLOCK_SYNTH)或任何综合优化决策时使用此技能。当用户提及综合策略、综合指令、综合属性、资源映射控制、FSM 编码、重定时或询问如何优化综合结果以获得更好的面积/时序/功耗时触发。此技能提供决策知识——如需执行 TCL 命令,请使用 vivado-tcl 技能。

视觉设计
★ 3
ra9fael
ra9fael/xilinx-skills

vivado-sim

当用户需要 Vivado 仿真策略、流程选择和调试方面的帮助时使用此技能。这包括行为仿真(RTL 功能验证)、综合后仿真(网表功能验证)、实现后时序仿真(SDF 反标注,时序验证)、Vivado 仿真器 xsim 使用(xvlog/xvhdl/xelab/xsim 三步流程,launch_simulation 工程模式)、第三方仿真器集成(Questa/ModelSim/VCS/Xcelium/Riviera/ActiveHDL,compile_simlib,export_simulation)、SAIF/VCD 功耗仿真(open_saif/log_saif,open_vcd/log_vcd,read_saif + report_power)、仿真网表生成(write_verilog -mode funcsim/timesim,write_sdf)、xsim 调试命令(add_force、add_wave、log_wave、add_bp、step、run、restart、get_objects、get_value)、仿真属性和设置、glbl.v 使用,或选择正确仿真方法进行验证或功耗分析的任何问题。

★ 3
ra9fael
ra9fael/xilinx-skills

vivado-impl

当用户需要 Vivado 实现策略选择和优化方面的帮助时使用此技能。这包括 opt_design(逻辑优化指令和选项)、place_design(布局指令、拥塞分析、PSIP 物理综合)、phys_opt_design(物理优化 - 扇出/布局/布线/SLR 交叉/寄存器优化、hold 修复)、route_design(布线指令、拥塞解决、预布线关键网络)、power_opt_design(时钟门控、BRAM 功耗优化)、增量实现(read_checkpoint -incremental、auto_incremental、reuse 分析)、ECO 流程、实现运行策略(Performance/Congestion/Area 策略)或选择实现指令或解决实现过程中时序/拥塞问题的任何问题。此技能为实现阶段提供决策知识——如需执行 TCL 命令使用 vivado-tcl,如需综合使用 vivado-synth,如需约束使用 vivado-constraints,如需时序报告解释和分析使用 vivado-analysis。

视觉设计
★ 3
ra9fael
ra9fael/xilinx-skills

vivado-git

当用户需要实现Vivado工程GIT化的时候使用该技能。

★ 3