---
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。
---

# PetaLinux 开发决策指南

PetaLinux 是 Xilinx 基于 Yocto Project 的嵌入式 Linux 开发工具，专用于 Zynq/MPSoC/Versal 平台。此技能提供流程决策引导，完整命令语法和示例请参阅 [REFERENCE.md](./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](./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 导出流程