📚 课程目录第4章 PetaLinux工程创建与配置

4. PetaLinux工程创建与配置

在 Kria 平台上做嵌入式 Linux 开发，PetaLinux 工程是承载硬件描述、内核配置、设备树、根文件系统与启动镜像的“总装车间”。本节围绕一条完整链路展开：用 petalinux-create 基于 Kria BSP 建立工程，用 petalinux-config 完成机器与子系统配置，导入 Vivado 导出的 XSA 硬件描述，生成设备树，最后打包出可烧录的镜像并理解各输出物的用途。理解这条链路，才能把“硬件设计”和“可启动系统”真正对接起来。

一、用 BSP 创建工程：起点决定省力程度

PetaLinux 工程有两种常见起点：从零创建（--template 指定类型）和从 BSP 创建。对 Kria 而言，强烈建议从官方 BSP 起步，因为 BSP 已经预置了与具体 SOM（如 K26）匹配的机器配置、U-Boot 环境、PS 端外设定义和参考设备树，能避免大量底层适配工作。

# 从 Kria K26 BSP 创建工程
petalinux-create -t project -s xilinx-k26-starterkit-v2023.2-10141622.bsp -n kria_led

# 进入工程目录
cd kria_led

# 查看工程结构
ls
# 关键目录：project-spec/  hardware/  components/  images/  build/

创建完成后，工程目录中 project-spec/ 是配置核心，hardware/ 用于放置 XSA，images/linux/ 是最终产物落地点。BSP 方式创建时，机器名通常已由 BSP 指定，例如 k26-starter-kit 或 kria-k26，这决定了后续内核与设备树的默认选择。

二、petalinux-config 菜单结构与配置层次

petalinux-config 是工程配置的总入口，其菜单按“系统级 → 子系统级 → 组件级”分层。理解菜单结构，比记住每个选项更重要。

Linux System Configuration：机器名、启动方式、串口、根文件系统类型、SD/MMC 启动参数等，属于系统级。
Subsystem AUTO Hardware Settings：从 XSA 自动提取的硬件信息，如以太网、串口、Flash 分区，通常保持 AUTO。
Device Tree Configuration：设备树源文件选择、自定义 DTS 包含、设备树覆盖（overlay）配置。
Kernel / Root Filesystem / U-Boot：分别进入内核、根文件系统、引导程序的子配置。
Yocto Settings：镜像类型、包管理、下载目录、sstate 缓存等构建层参数。

实际操作中，最常改的是机器名、根文件系统类型和镜像格式。例如把根文件系统从 INITRD 改为 EXT4，或把启动介质从 QSPI 改为 SD。每次修改后，PetaLinux 会在 project-spec/configs/config 中记录，便于版本管理。

三、导入 XSA：让软件工程认识硬件

XSA 是 Vivado 导出的硬件描述归档，包含 PS 配置、PL 逻辑、地址映射和 IP 信息。Kria 的 PL 端设计（如自定义 AXI GPIO、LED 控制器）必须通过 XSA 进入 PetaLinux，才能生成对应的设备树节点和驱动匹配信息。

# 将 XSA 放入 hardware 目录
cp kria_led.xsa hardware/

# 导入硬件描述
petalinux-config --get-hw-description=hardware/

# 导入后检查
ls hardware/
# 会生成 xsa 解压后的硬件信息，供子系统 AUTO 配置使用

导入后，Subsystem AUTO Hardware Settings 会自动识别 PS 外设。若 PL 端有自定义 IP，需要在设备树中手动补充节点，或通过 system-user.dtsi 追加。判断导入是否成功，可查看 components/plnx_workspace/device-tree/ 下是否出现与 XSA 对应的 DTSI 片段。

四、机器配置与设备树生成

机器配置（machine configuration）决定内核、U-Boot、设备树的默认组合。Kria BSP 中，机器名通常对应 k26-starter-kit。设备树生成分两层：一层是 PetaLinux 根据 XSA 和机器配置自动生成的 pl.dtsi、pcw.dtsi；另一层是用户自定义的 system-user.dtsi，用于覆盖或追加节点。

# 查看生成的设备树
ls components/plnx_workspace/device-tree/device-tree/
# pl.dtsi  pcw.dtsi  system-top.dts  system-user.dtsi

# 在 system-user.dtsi 中追加自定义节点示例
/ {
    amba_pl: amba_pl {
        #address-cells = <1>;
        #size-cells = <1>;
        compatible = "simple-bus";
        ranges ;
        axi_gpio_led: gpio@a0000000 {
            compatible = "xlnx,axi-gpio-2.0";
            reg = <0xa0000000 0x10000>;
            xlnx,all-inputs = <0x0>;
            xlnx,gpio-width = <0x4>;
        };
    };
};

设备树生成后，可用 petalinux-build -c device-tree 单独编译验证。若出现地址冲突或 compatible 不匹配，内核启动日志中会出现 of_platform 相关报错，这是判断设备树是否正确的重要依据。

五、镜像打包格式与输出物解析

构建完成后，images/linux/ 下会生成一组输出物。理解每个文件的用途，才能正确选择烧录方式。

输出物	用途	典型烧录位置
BOOT.BIN	FSBL + PMU + U-Boot 打包，引导第一阶段	SD 分区或 QSPI
image.ub	内核 + 设备树 + INITRD 的 FIT 镜像	SD 分区或 QSPI
boot.scr	U-Boot 启动脚本	SD 分区
rootfs.ext4	EXT4 根文件系统	SD 第二分区
system.dtb	独立设备树二进制	调试或覆盖使用

若根文件系统为 INITRD，则 image.ub 已包含根文件系统，只需 BOOT.BIN 和 image.ub 即可启动；若为 EXT4，则需额外烧录 rootfs.ext4。Kria 常见做法是 SD 启动：第一分区放 BOOT.BIN、image.ub、boot.scr，第二分区放 rootfs.ext4。

六、实操检查清单

完成一次工程创建与配置后，建议按以下顺序核对，避免把问题带到烧录阶段：

确认 BSP 版本与 Kria SOM 型号匹配，机器名在 petalinux-config 中可见且正确。
确认 XSA 已放入 hardware/ 并成功导入，Subsystem AUTO 中能看到 PL 外设。
确认根文件系统类型与启动介质一致：INITRD 只需 image.ub，EXT4 需额外 rootfs.ext4。
确认 system-user.dtsi 中自定义节点地址不与 PS 外设冲突。
构建后检查 images/linux/ 下 BOOT.BIN、image.ub、boot.scr、rootfs.ext4 是否齐全。

提示：Kria 的 QSPI 启动与 SD 启动对输出物要求不同。QSPI 通常需要 BOOT.BIN 和 image.ub 写入 Flash；SD 启动则把 BOOT.BIN、image.ub、boot.scr 放第一分区，rootfs.ext4 放第二分区。切换启动方式时，务必同步修改 petalinux-config 中的启动介质选项。

注意：不要跳过 XSA 导入直接手动改设备树。Kria 的 PS 端配置与 PL 地址映射由 XSA 决定，手动修改容易遗漏时钟、复位和中断控制器节点，导致内核启动后外设无法工作。

把上述链路走通后，PetaLinux 工程就不再是一个黑盒。后续无论是添加自定义 PL IP、裁剪根文件系统，还是调整启动参数，都可以在明确的配置层次和设备树结构上定位问题，而不是反复重建整个工程。