AGENT SKILL

petalinux

当用户需要创建 PetaLinux 工程、配置 Linux 内核/rootfs/U-Boot、编写设备树(system-user.dtsi)、添加自定义应用程序 recipe、构建嵌入式 Linux 镜像、打包 BOOT.BIN 启动镜像、生成 WIC SD 卡镜像、部署到 SD 卡/QSPI、通过 QEMU 仿真启动、通过 JTAG 下载调试、动态加载 FPGA 比特流、或解决 PetaLinux 构建/版本问题时使用此技能。涵盖 petalinux-create、petalinux-config、petalinux-build、petalinux-package 全流程命令。当用户提及嵌入式 Linux、Yocto、meta-user、kernel config、rootfs 配置、u-boot、FSBL、PMU firmware、ATF、FIT image、设备树覆盖或 Zynq/MPSoC/Versal Linux 系统构建时触发。如需生成 XSA 文件使用 vivado-synth 和 vivado-impl,如需编写时序约束使用 vivado-constraints,如需硬件调试使用 vivado-debug,如需 PYNQ 镜像构建使用 pynq。

适用职业开发工程师
使用场景运维与部署
License 许可
GPL-2.0
最近更新
2026-05-07
Stars
★ 3
Forks
0

01 前言 Front Matter

name
petalinux
description
当用户需要创建 PetaLinux 工程、配置 Linux 内核/rootfs/U-Boot、编写设备树(system-user.dtsi)、添加自定义应用程序 recipe、构建嵌入式 Linux 镜像、打包 BOOT.BIN 启动镜像、生成 WIC SD 卡镜像、部署到 SD 卡/QSPI、通过 QEMU 仿真启动、通过 JTAG 下载调试、动态加载 FPGA 比特流、或解决 PetaLinux 构建/版本问题时使用此技能。涵盖 petalinux-create、petalinux-config、petalinux-build、petalinux-package 全流程命令。当用户提及嵌入式 Linux、Yocto、meta-user、kernel config、rootfs 配置、u-boot、FSBL、PMU firmware、ATF、FIT image、设备树覆盖或 Zynq/MPSoC/Versal Linux 系统构建时触发。如需生成 XSA 文件使用 vivado-synth 和 vivado-impl,如需编写时序约束使用 vivado-constraints,如需硬件调试使用 vivado-debug,如需 PYNQ 镜像构建使用 pynq。

02 资源文件 1

03 SKILL.md 正文

PetaLinux 开发决策指南

PetaLinux 是 Xilinx 基于 Yocto Project 的嵌入式 Linux 开发工具,专用于 Zynq/MPSoC/Versal 平台。此技能提供流程决策引导,完整命令语法和示例请参阅 REFERENCE.md。

何时使用此技能

  • 需要从 Vivado XSA 文件创建 PetaLinux 工程
  • 需要从官方 BSP 创建 PetaLinux 工程
  • 需要配置 Linux 内核驱动和功能
  • 需要定制 rootfs 包含的软件包
  • 需要编写设备树覆盖(system-user.dtsi)添加自定义硬件节点
  • 需要添加自定义应用程序到 rootfs
  • 需要构建和打包 BOOT.BIN 启动镜像
  • 需要生成 WIC 格式 SD 卡镜像
  • 需要部署镜像到 SD 卡
  • 需要 QEMU 仿真测试
  • 需要 JTAG 下载和调试
  • 需要 Linux 运行时动态加载 FPGA 比特流
  • 遇到 PetaLinux 构建错误或版本不匹配问题

工作流决策

选择工程创建方式

场景 命令 适用
已有 Vivado 导出的 XSA petalinux-create --type project --template zynqMP --name <proj> + petalinux-config --get-hw-description=<xsa> 自定义硬件设计
有官方板卡 BSP petalinux-create --type project -s <board.bsp> 官方开发板,快速启动
已有工程更换硬件 petalinux-config --get-hw-description=<new.xsa> 硬件升级,保留配置

选择 rootfs 类型

类型 menuconfig 位置 特点 适用
INITRD Image Packaging → Root filesystem type → INITRD rootfs 在 RAM,启动快 快速启动、开发调试
EXT4 Image Packaging → Root filesystem type → EXT4 rootfs 在 SD 卡第 2 分区 生产部署
NFS Image Packaging → Root filesystem type → NFS rootfs 网络挂载 开发阶段快速迭代

选择构建范围

需求 命令 耗时
首次完整构建 petalinux-build 30-90 分钟
仅改内核配置 petalinux-build -c kernel 数分钟
仅改设备树 petalinux-build -c device-tree < 1 分钟
仅改 rootfs petalinux-build -c rootfs 数分钟
仅改自定义应用 petalinux-build -c <app-name> 很快
仅 U-Boot petalinux-build -c u-boot 数分钟
强制重建某组件 petalinux-build -c <component> -x distclean && petalinux-build -c <component> 取决于组件

选择部署方式

方式 命令 适用
WIC 镜像 petalinux-package --wic --wic-extra-args "-c gzip" → dd 写入 SD 卡 最简单,推荐
手动分区 独立复制 BOOT.BIN、image.ub、rootfs 需要完全控制分区布局
QEMU petalinux-boot --qemu --kernel 无硬件时的功能验证
JTAG petalinux-boot --jtag --kernel --fpga <bit> 硬件调试

选择动态加载 bitstream 方式

方式 适用 工具
BOOT.BIN 包含 bitstream bitstream 固定,启动即加载 petalinux-package --boot --fpga <bit>
Linux 运行时加载 需要多 bitstream 切换 echo <bit> > /sys/class/fpga_manager/fpga0/firmware
PYNQ Overlay 加载 Python 生态,动态管理 PL 使用 pynq skill

完整流程

XSA(来自 Vivado)→ 创建工程 → 配置(系统/内核/rootfs/设备树)→ 构建 → 打包 → 部署

详细命令和完整 8 阶段示例见 REFERENCE.md。

关键规则

  1. PetaLinux 版本必须与 Vivado 版本完全一致(如均用 2024.2),否则 petalinux-config 报 XSA 版本不匹配
  2. 每次新终端都需要 source /path/to/petalinux/<version>/settings.sh 设置环境
  3. 设备树定制使用 system-user.dtsi 覆盖文件,不要直接修改 ./components/plnx_workspace/ 下自动生成的文件
  4. 构建主机需要 Linux(Ubuntu 20.04/22.04 推荐),需安装 gawk/python3/gcc-multilib/build-essential 等依赖包

相关技能

  • vivado-synth — 生成 PetaLinux 工程所需的 XSA(含 bitstream)的综合流程
  • vivado-impl — 布局布线和 bitstream 生成,导出硬件描述文件
  • vivado-constraints — 为 Vivado 硬件设计编写时序和物理约束
  • vivado-debug — 通过 JTAG 调试硬件、ILA/VIO 观测信号
  • pynq — 如果目标是构建 PYNQ 镜像而非纯 PetaLinux,使用 pynq skill
  • vivado-tcl — 自动化 Vivado 构建和 XSA 导出流程

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