4. PetaLinux工程创建与硬件描述导入
在 Versal 平台上做嵌入式 Linux 开发，第一步不是写驱动，而是把“硬件长什么样”这件事准确地交给软件。PetaLinux 工程正是承载这一信息的容器：它把 Vivado 导出的 XSA 硬件描述、U-Boot、Linux 内核、设备树和根文件系统组织成一个可配置、可构建、可复现的工程。本节围绕工程初始化、XSA 导入、设备树自动生成、内核与根文件系统配置入口以及目录结构展开，目标是让读者能够独立完成一个可编译的 PetaLinux 工程骨架。
一、petalinux-create：工程初始化
PetaLinux 的所有操作都必须在已 source 的环境中进行。典型流程是先加载安装目录下的 settings.sh，再创建工程。以 Versal 为例，工程模板应选择 versal，而不是 Zynq 的 zynqMP：
source /opt/pkg/petalinux/2023.2/settings.sh
petalinux-create -t project --template versal \
--name vck190_linux -p ~/work
cd ~/work/vck190_linux这里 -t project 表示创建工程，--template versal 决定默认的机器配置、U-Boot 与内核版本基线，-p 指定父目录。创建完成后，PetaLinux 会生成一个包含 project-spec/、build/（构建时才填充）等内容的目录树。需要强调的是：工程名和路径不要包含空格或中文，否则后续 make 阶段容易出现路径解析错误。
二、导入 XSA 硬件描述文件
XSA（Xilinx Support Archive）是 Vivado 在实现（Implementation）完成后导出的硬件描述包，内部包含 .hwh 硬件句柄、块设计信息、PS 配置、时钟与中断拓扑等。导入命令为：
petalinux-config --get-hw-description=/home/user/hw/vck190_base.xsa执行后 PetaLinux 会解析 XSA，把硬件信息抽取到 project-spec/hw-description/ 下，并弹出顶层配置菜单。此时应重点确认三项：
- 机器名（Machine Name）：应与 XSA 中的器件匹配，例如
versal-vck190-reva-x-ebm-01-reva； - 串口与启动介质：确认 UART 控制器、QSPI/SD 启动顺序；
- 内存与地址映射：DDR 容量、外设基地址是否与硬件一致。
如果 XSA 是“仅含 PS”的导出，PL 侧逻辑不会出现在设备树中；若需要 PL 外设，Vivado 导出时必须勾选包含 bitstream 与 block design。导入后若修改了硬件，应重新执行该命令，而不是手工改设备树。
三、设备树自动生成机制
PetaLinux 的设备树不是一份手写文件，而是由多层来源合并生成。理解这一点，才能知道“该改哪里”。其生成链路大致为：
其中 pl.dtsi 由 XSA 中的 PL 信息自动生成，system-user.dtsi 是用户唯一应手工编辑的文件，位于 project-spec/meta-user/recipes-bsp/device-tree/files/。它的作用是“覆盖”而非“重写”，例如要修改某个 I2C 从设备地址，只需在 system-user.dtsi 中写 &i2c0 { ... }; 片段。若直接改自动生成的文件，下次导入 XSA 时会被覆盖。
四、内核与根文件系统配置入口
PetaLinux 把配置分成几个独立入口，避免一个菜单里塞进所有东西：
| 配置入口 | 作用范围 | 典型用途 |
|---|---|---|
petalinux-config | 工程级 | 机器名、启动介质、内存、串口 |
petalinux-config -c kernel | Linux 内核 | 驱动裁剪、文件系统支持、调试选项 |
petalinux-config -c rootfs | 根文件系统 | 安装软件包、添加用户、启动脚本 |
petalinux-config -c u-boot | U-Boot | 启动参数、环境变量、引导方式 |
内核配置基于 Kconfig，保存后写入 project-spec/meta-user/recipes-kernel/linux/linux-xlnx/ 下的 defconfig 或 fragment。根文件系统配置则通过 petalinux-config -c rootfs 选择 busybox、packagegroup 等，最终由 Yocto 的配方系统组装。一个常见误区是：在内核菜单里改了配置，却忘记执行 petalinux-build -c kernel，导致镜像没有更新。
五、工程目录结构解析
创建完成后，工程根目录下几个关键路径需要牢记：
project-spec/：所有用户可编辑内容的根，包含config、meta-user/、hw-description/；project-spec/meta-user/：用户层，设备树、内核 fragment、自定义配方都放这里；build/：构建输出，包含tmp/、images/linux/，最终BOOT.BIN、image.ub、system.dtb都在images/linux/；components/：可选的独立组件源码，如自定义 U-Boot 或内核；config.project：工程级配置的符号链接。
project-spec/ 纳入 Git 版本管理，而 build/ 应加入 .gitignore。这样团队协作时，别人只需 clone 工程、重新导入 XSA、执行 petalinux-build，即可复现一致的镜像，而不必传递几十 GB 的构建产物。
petalinux-config --get-hw-description 报 “XSA not found” 或解析失败，先确认 XSA 是否由匹配版本的 Vivado 导出；跨大版本（如 2022.2 的 XSA 用于 2023.2 的 PetaLinux）通常不兼容。另外，XSA 路径不要放在含中文或空格的目录下。
完成以上步骤后，一个可构建的 PetaLinux 工程骨架就建立起来了。后续的驱动开发、应用部署和系统集成，都将在 project-spec/meta-user/ 这一用户层内展开，而硬件描述始终以 XSA 为唯一权威来源，设备树则通过自动生成加用户覆盖的方式保持与硬件同步。