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
- 其他Makefile13.8 KB
- 参考文档REFERENCE.md8.1 KB
- 参考文档references/appendix/assign_a_static_ip.rst2.2 KB
- 参考文档references/appendix/glossary.rst6.4 KB
- 参考文档references/appendix/references.rst1.6 KB
- 参考文档references/appendix/sdcard.rst5.9 KB
- 参考文档references/appendix/technology_backgrounder.rst5.2 KB
- 参考文档references/appendix/verification.rst5.1 KB
- 参考文档references/getting_started/alveo_getting_started.rst5.4 KB
- 参考文档references/getting_started/jupyter_notebooks_advanced_features.ipynb843.5 KB
- 参考文档references/getting_started/jupyter_notebooks.ipynb29.4 KB
- 参考文档references/getting_started/network_connection.rst1.6 KB
- 参考文档references/getting_started/other_boards.rst1.3 KB
- 参考文档references/getting_started/pynq_alveo.rst7.8 KB
- 参考文档references/getting_started/pynq_sdcard_getting_started.rst4.7 KB
- 参考文档references/getting_started/pynq_z1_setup.rst2.4 KB
- 参考文档references/getting_started/pynq_z2_setup.rst2.3 KB
- 参考文档references/getting_started/python_environment.ipynb17.2 KB
- 参考文档references/getting_started/terminal.rst1.5 KB
- 参考文档references/getting_started/zcu104_setup.rst2.2 KB
- 参考文档references/overlay_design_methodology/board_settings.rst1.9 KB
- 参考文档references/overlay_design_methodology/overlay_design.rst4.5 KB
- 参考文档references/overlay_design_methodology/overlay_tutorial.ipynb20.0 KB
- 参考文档references/overlay_design_methodology/partial_reconfiguration.rst3.4 KB
- 参考文档references/overlay_design_methodology/pspl_interface.rst4.9 KB
- 参考文档references/overlay_design_methodology/pynq_and_asyncio.rst10.9 KB
- 参考文档references/overlay_design_methodology/pynq_microblaze_subsystem.rst34.8 KB
- 参考文档references/overlay_design_methodology/pynq_utils.rst4.6 KB
- 参考文档references/overlay_design_methodology/python_overlay_api.rst5.4 KB
- 参考文档references/overlay_design_methodology/python_packaging.rst8.1 KB
- 参考文档references/overlay_design_methodology/python-c_integration.rst1.8 KB
- 参考文档references/pynq_libraries/allocate.rst2.4 KB
- 参考文档references/pynq_libraries/arduino.rst2.8 KB
- 参考文档references/pynq_libraries/audio.rst1.6 KB
- 参考文档references/pynq_libraries/axigpio.rst3.0 KB
- 参考文档references/pynq_libraries/axiiic.rst893 B
- 参考文档references/pynq_libraries/debugbridge.rst2.6 KB
- 参考文档references/pynq_libraries/dma.rst2.9 KB
- 参考文档references/pynq_libraries/grove.rst3.6 KB
- 参考文档references/pynq_libraries/interrupt.rst7.4 KB
- 参考文档references/pynq_libraries/logictools.rst12.2 KB
- 参考文档references/pynq_libraries/mmio.rst1.5 KB
- 参考文档references/pynq_libraries/overlay.rst1.8 KB
- 参考文档references/pynq_libraries/pl.rst3.7 KB
- 参考文档references/pynq_libraries/pmbus.rst2.5 KB
- 参考文档references/pynq_libraries/pmod.rst3.6 KB
- 参考文档references/pynq_libraries/psgpio.rst1.5 KB
- 参考文档references/pynq_libraries/pynq_microblaze_subsystem.rst4.1 KB
- 参考文档references/pynq_libraries/pynqmb_python.rst3.8 KB
- 参考文档references/pynq_libraries/pynqmb_reference.rst8.1 KB
- 参考文档references/pynq_libraries/rpi.rst1.8 KB
- 参考文档references/pynq_libraries/video.rst10.5 KB
- 参考文档references/pynq_overlays/loading_an_overlay.ipynb19.3 KB
- 参考文档references/pynq_overlays/pynqz1.rst1.1 KB
- 参考文档references/pynq_overlays/pynqz1/pynqz1_base_overlay.rst7.7 KB
- 参考文档references/pynq_overlays/pynqz1/pynqz1_logictools_overlay.rst4.0 KB
- 参考文档references/pynq_overlays/pynqz2.rst1.1 KB
- 参考文档references/pynq_overlays/pynqz2/pynqz2_base_overlay.rst7.0 KB
- 参考文档references/pynq_overlays/pynqz2/pynqz2_logictools_overlay.rst4.6 KB
- 参考文档references/pynq_overlays/zcu104.rst1.3 KB
- 参考文档references/pynq_overlays/zcu104/zcu104_base_overlay.rst5.3 KB
- 参考文档references/pynq_package/pynq.bitstream.rst568 B
- 参考文档references/pynq_package/pynq.buffer.rst182 B
- 参考文档references/pynq_package/pynq.devicetree.rst301 B
- 参考文档references/pynq_package/pynq.gpio.rst262 B
- 参考文档references/pynq_package/pynq.interrupt.rst155 B
- 参考文档references/pynq_package/pynq.lib.rst1.9 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.arduino.rst3.2 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.audio.rst337 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.axigpio.rst342 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.button.rst285 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.cmac.rst148 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.dma.rst146 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.iic.rst233 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.led.rst234 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.logictools.rst1.0 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.pmod.rst4.7 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.pynqmicroblaze.rst1.1 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.rgbled.rst252 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.rpi.rst372 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.switch.rst262 B
- 参考文档references/pynq_package/pynq.lib/pynq.lib.video.rst1.6 KB
- 参考文档references/pynq_package/pynq.lib/pynq.lib.wifi.rst304 B
- 参考文档references/pynq_package/pynq.metadata.rst1.6 KB
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst595 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.gpio_dict_view.rst461 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.hierarchy_dict_view.rst1.7 KB
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.interrupt_controllers_view.rst642 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.ip_dict_view.rst689 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.mem_dict_view.rst457 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.metadata_view.rst393 B
- 参考文档references/pynq_package/pynq.metadata/pynq.metadata.runtime_metadata_parser.rst1.3 KB
- 参考文档references/pynq_package/pynq.mmio.rst137 B
- 参考文档references/pynq_package/pynq.overlay.rst524 B
- 参考文档references/pynq_package/pynq.pl_server.rst1.1 KB
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.device.rst591 B
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.embedded_device.rst339 B
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.global_state.rst733 B
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.hwh_parser.rst483 B
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.xclbin_parser.rst373 B
- 参考文档references/pynq_package/pynq.pl_server/pynq.pl_server.xrt_device.rst317 B
- 参考文档references/pynq_package/pynq.pl.rst375 B
- 参考文档references/pynq_package/pynq.pmbus.rst141 B
- 参考文档references/pynq_package/pynq.ps.rst306 B
- 参考文档references/pynq_package/pynq.registers.rst423 B
- 参考文档references/pynq_package/pynq.uio.rst133 B
- 参考文档references/pynq_package/pynq.utils.rst503 B
- 参考文档references/pynq_remote/.gitignore24 B
- 参考文档references/pynq_remote/cpp_index.rst1.1 KB
- 参考文档references/pynq_remote/cppindex.rst—
- 参考文档references/pynq_remote/env_variables.rst2.5 KB
- 参考文档references/pynq_remote/image_build.rst2.0 KB
- 参考文档references/pynq_remote/pynq_cpp/cpp_api.rst1.1 KB
- 参考文档references/pynq_remote/pynq_cpp/cpp_install.rst890 B
- 参考文档references/pynq_remote/pynq_cpp/cpp_usage.rst1.8 KB
- 参考文档references/pynq_remote/quickstart.rst4.9 KB
- 参考文档references/pynq_remote/remote_device.rst1.3 KB
- 参考文档references/pynq_remote/status.rst711 B
- 参考文档references/pynq_remote/troubleshooting.rst268 B
- 脚本scripts/.pkgverify.env—
- 脚本scripts/flashsd.sh—
- 脚本scripts/imgshell.sh—
- 脚本scripts/pkgverify.sh19.3 KB
- 脚本scripts/yoctoenv.sh2.5 KB
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 工作流
- 硬件工程师导出 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),板上信号观测
04 同仓库更多 Skills
xilinx-docs
当用户需要查找xilinx官方文档时使用该技能
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。
vivado-synth
当用户需要 Vivado 综合策略选择、综合属性配置、synth_design 选项调优、资源推断控制(RAM/DSP/SRL/BRAM)、层次结构优化(flatten_hierarchy、KEEP_HIERARCHY)、OOC(离屏)综合、增量综合、RTL linting、块级综合(BLOCK_SYNTH)或任何综合优化决策时使用此技能。当用户提及综合策略、综合指令、综合属性、资源映射控制、FSM 编码、重定时或询问如何优化综合结果以获得更好的面积/时序/功耗时触发。此技能提供决策知识——如需执行 TCL 命令,请使用 vivado-tcl 技能。
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 使用,或选择正确仿真方法进行验证或功耗分析的任何问题。
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。
vivado-git
当用户需要实现Vivado工程GIT化的时候使用该技能。