1. 先把 petalinux 工程骨架这块拼图摆正如果你刚接触 Zynq 这类带 FPGA 的嵌入式平台想用 petalinux 给板卡做一套 Linux 系统第一反应大概率是找一份教程敲几条命令生成 BOOT.BIN烧进 SD 卡完事。我最早也这么想结果折腾了整整一个周末卡在最基本的三件事上设备树到底怎么改、boot.scr 和 image.ub 分别负责什么、以及 SD 卡里每个文件为什么非放那个位置不可。后来回头看这些问题不是因为工具复杂而是因为我一开始没有把 petalinux 工程骨架这件事弄明白。这篇文章就把我反复踩坑之后整理出来的东西写下来作为这个系列的第 1 篇目标读者是三类人用过 Vivado 但没碰过 petalinux 的人、被各种启动报错吓退的新手、以及想从“会敲命令”升级到“知道每步在干什么”的人。1.1 很多人学 petalinux 的第一道坎不知道整套流程在干什么大多数教程都会告诉你运行petalinux-create、petalinux-config、petelinux-build、petalinux-package这几条命令但很少有人讲清楚这几条命令背后到底发生了什么。结果就是你照着敲完了板子没起来不知道去查哪里就算板子起来了换一块板子、换一个外设又不会了。我后来把整个流程重新拆了一遍发现 petalinux 做的事情其实是一个“硬件描述 - 软件组件 - 可启动镜像”的三级转换第一级Vivado 导出的.xsa文件里面包含硬件平台信息比如 CPU 型号、DDR 地址、外设地址、时钟频率以及可选的 FPGA bitstream。第二级petalinux 拿到.xsa之后生成对应的设备树源文件、U-Boot 配置、内核配置和根文件系统骨架。第三级petalinux-build和petalinux-package把这些东西编译、组装成 BOOT.BIN、boot.scr、image.ub 这一套启动文件。所以 petalinux 不是简单帮你“编一个 Linux 内核”它更像一条流水线输入是硬件工程师给的 XSA输出是嵌入式 Linux 工程师可以直接烧到板子上的镜像。1.2 一套嵌入式 Linux 方案的完整组成在 Zynq 平台上一套能跑起来的嵌入式 Linux 方案至少包含下面几个部分层次组件作用来源FPGA 逻辑bitstream (.bit)配置 PL 侧的硬件逻辑比如 AXI GPIO、DMA、AD9361 接口Vivado 生成启动引导FSBL U-Boot初始化 DDR、时钟、MIO加载 bitstream引导内核FSBL 由 Vivado 生成U-Boot 由 petalinux 编译内核kernel Image / uImage负责进程调度、内存管理、驱动框架petalinux 编译设备树.dtb告诉内核“硬件长什么样、地址在哪里、中断是几号”petalinux 的 DTG 根据 XSA 生成根文件系统rootfs提供 /bin、/etc、/lib 这些用户态环境petalinux 生成这里最容易忽略的是设备树。很多刚从单片机转过来的朋友习惯把所有硬件信息写在代码里但 Linux 内核不一样它面对的是千奇百怪的板卡不可能每块板子都编译一个专用内核所以采用设备树这种“数据驱动”的方式。设备树里写清楚外设基地址、中断号、引脚复用内核再去匹配对应驱动。1.3 petalinux 在中间扮演什么角色把上面五层放在一起看petalinux 的定位就很清晰了它是连接硬件工程师交付物和嵌入式 Linux 工程师日常工作的“组装车间”。没有 petalinux你也能手动下载 U-Boot 源码、Linux 内核源码、Buildroot然后一个一个交叉编译再自己拼启动镜像。这样做不是不行但你得同时维护 U-Boot、内核、设备树、rootfs 四套东西的版本关系第一次搞十有八九会乱。petalinux 把这些事情封装成了 Yocto 层的 recipe并提供了一套相对统一的命令行接口。它的好处是你只要维护一个project-spec目录下的配置就能反复构建出可复现的启动镜像。缺点是Yocto 构建系统本身很复杂命令被封裝得越简单出问题时越难排查。所以我一直建议学 petalinux 的人不要只背命令而是要把每一层对应到实际文件上不然遇到“编译过了但启动不了”这种问题会很痛苦。2. 从 Vivado 到 petalinux用最简单工程串起整条链路2.1 我建议的第一个工程只保留这些东西很多人一上来就想把完整板卡支持、AD9361、DMA、Ethernet 全部塞进去结果系统起不来根本不知道是硬件问题、设备树问题还是 rootfs 问题。我做第一块板子的经验是先做一个“最小可启动系统”能打印 U-Boot 日志、能进 Linux 命令行就算赢。在 Vivado 里这个最小工程只需要三样东西Zynq PS也就是processing_system7_0开好 UART、SD、QSPI 这三个最基本的 MIO 配置。AXI GPIO用来点一颗 LED验证 PL 和 PS 之间的 AXI 通路。一个简单的 Block Design把 PS 和 AXI GPIO 连起来跑综合、实现生成 bitstream。这里有一个新手很容易踩的坑导出.xsa的时候忘记勾选Include bitstream。如果你不勾后面 petalinux 打包 BOOT.BIN 时就没有 FPGA 配置文件PL 侧永远是空的AXI GPIO 自然不工作。正确的导出方式在 Vivado 的 Tcl Console 里执行write_hw_platform -force -include_bit ./system.xsa或者在 GUI 菜单里点击File - Export Hardware务必确认勾选Include bitstream。导出的system.xsa就是 petalinux 的输入。2.2 为什么需要 XSA、bitstream 和设备树“三方对账”把 Vivado 工程和 petalinux 工程放在一起看你会发现它们之间有一个三角关系XSA 描述硬件架构告诉 petalinux 有哪些外设、地址是多少。Bitstream 描述 FPGA 逻辑它会在启动早期被 FSBL 加载进 PL。设备树描述内核视角的硬件视图告诉内核哪个地址对应哪个驱动。这三者必须保持一致。最常见的翻车现场是你改了 Vivado Block Design给某外设换了基地址然后只重新导出了 XSA忘了重新生成 bitstream或者只重新生成了 bitstream没有重新导入 petalinux。结果就是设备树里的地址和实际 PL 逻辑对不上驱动 probe 失败日志里出现一堆乱码。所以我的习惯是每次改动 Vivado 硬件后统一执行一次“重新综合实现 - 导出带 bitstream 的 XSA - 在 petalinux 工程里重新导入 XSA - 重新 build”。这个过程看起来啰嗦但能省下大量排错时间。3. petalinux 命令的“入坑顺序”先创建再逐层配置3.1 工程创建与硬件描述导入创建 petalinux 工程本身不复杂但有几个前置条件容易被忽略。我建议先确认这几件事petalinux 安装路径下没有中文和空格。当前终端用的是 bash不是 sh 或者 dash。已经执行过安装目录下的settings.sh环境脚本。磁盘剩余空间至少留 80GB整个构建过程会消耗大量空间。确认完环境之后按下面步骤操作source /opt/petalinux/2025.1/settings.sh petalinux-create -t project -n zynq-led --template zynq cd zynq-led petalinux-config --get-hw-description../hardware/system.xsa--template zynq的意思是创建一个 Zynq-7000 系列的工程模板。如果你的芯片是 Zynq UltraScale MPSoC这里要改成zynqMP如果是 Versal要改成versal。选错模板后面会有一堆奇怪的错误比如找不到 PMU 固件、U-Boot 配置不匹配等。执行完最后一条命令后会进入一个菜单配置界面。这里大多数人就直接按 F1 保存退出了但我建议第一次老老实实把菜单翻一遍至少要知道下面这些选项在哪里。3.2 进入配置菜单后先看这几个关键项petalinux-config打开的是基于 Kconfig 的菜单界面和 Linux 内核的menuconfig很像。新手一进去容易懵我先帮你划几个重点Subsystem AUTO Hardware Settings - Serial console查看串口控制台参数Zynq 默认通常是ttyPS0波特率 115200。Subsystem AUTO Hardware Settings - Advanced bootable images storage Settings选择 boot 镜像从哪里读取可以是 SD、QSPI、EMMC。Image Packaging Configuration - Root filesystem type选择根文件系统类型这里决定后面 SD 卡怎么分区、image.ub 里装什么。u-Boot Configuration - boot script控制是否生成 boot.scr以及启动命令的默认配置。菜单里按/可以搜索符号按?可以看当前项的帮助说明。改完配置不要直接关终端要一路按Esc退到最底层选择保存否则你的修改不会生效。3.3 Rootfs 类型的选择直接影响 SD 卡内容这是第一课里最值得展开讲的地方。很多教程没区分根文件系统类型导致有人把 ext4 的 rootfs 要求硬套在 initramfs 上被人说“你怎么不把根文件系统分区拷进去”。先看这张表模式根文件系统在哪里适用场景SD 卡内容initramfs打进 image.ub第一版验证、临时测试BOOT.BIN boot.scr image.ubext4 / SD独立 ext4 分区需要持久化存储、跑实际应用上述三件套 rootfs 分区WIC 整卡镜像整个 SD 卡镜像量产、发布、复制给同事用 dd 直接写整卡如果你是第一次做最小系统验证我建议先选 initramfs。好处是 SD 卡只需要一个 FAT32 分区把三个文件丢进去就能启动不用纠结分区表错乱、rootfs 没格式化等问题。坏处是根文件系统在内存里重启后修改不保留不适合实际产品。如果你选择 ext4 / SD 模式那么 SD 卡需要两个分区第一个 FAT32 分区放 BOOT.BIN、boot.scr、image.ub第二个 ext4 分区放 rootfs。这个分区结构一定要记住后续所有启动问题里至少有三成是分区结构不对。3.4 构建、打包、制作 SD 卡三步走当硬件配置和 menuconfig 都设置好之后就可以开始构建和打包了petalinux-build petalinux-package --boot --fsbl images/linux/zynq_fsbl.elf \ --fpga images/linux/system.bit --u-boot第一条命令会把内核、U-Boot、设备树、rootfs 全部编译出来。第二条命令把这些文件按启动顺序打包成BOOT.BIN。构建完成后images/linux目录下会多出几个关键文件BOOT.BIN启动镜像包含 FSBL、bitstream、U-Boot。boot.scrU-Boot 启动脚本告诉 U-Boot 去哪里找 image.ub。image.ubFIT 格式镜像通常包含内核和设备树如果配置了 initramfs也会包含根文件系统。制作 SD 卡我的做法是先用lsblk确认 SD 卡设备名然后分区、格式化、拷贝sudo fdisk /dev/sdX # 分区1: 512M, 类型 c (W95 FAT32) # 分区2: 剩余空间, 类型 83 (Linux) sudo mkfs.vfat -F 32 -n BOOT /dev/sdX1 sudo mkfs.ext4 -L rootfs /dev/sdX2 sudo mount /dev/sdX1 /mnt/boot sudo cp images/linux/BOOT.BIN images/linux/boot.scr images/linux/image.ub /mnt/boot/ sudo umount /mnt/boot如果你选择的是 initramfs 模式只需要准备一个 FAT32 分区就够了第二个 ext4 分区可以不要。但请注意U-Boot 启动脚本里的 bootcmd 是根据 rootfs 类型生成的你改了 rootfs 类型之后最好重新执行一次petalinux-package生成新的 boot.scr不要自己手动改 bootcmd。4. 最容易翻车的文件设备树、boot.scr 和 SD 卡分区4.1 设备树不是“配置文件”是“硬件对账表”我见过不少新手把设备树当成配置文件随手改结果改出来的东西既没有语法错误也编译过去了但内核就是认不到外设。原因很简单设备树的本质是一份“硬件对账表”它必须和 Vivado 里实际生成的地址、中断号、时钟频率完全一致。在 petalinux 工程里用户自定义设备树主要改这个文件project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi这个文件会被自动 include 到整棵设备树里。你想追加一个 AXI GPIO 节点或者改某个已有节点的属性都可以写在这里。举个例子#include dt-bindings/gpio/gpio.h axi_gpio_0 { compatible xlnx,axi-gpio-2.0; xlnx,gpio-width 8; };编译设备树可以用petalinux-build -c device-tree这条命令很快只重新生成设备树不重新编译内核适合调试设备树时反复试。这里有个红线不要直接去改project-spec下自动生成的pl.dtsi或system.dts。因为每次重新导入 XSA这些文件都会被覆盖。你把改动写在这里面等于白改。所有用户自定义改动都应该放到system-user.dtsi或对应的 bbappend 里。4.2 我见过最多的三个启动失败原因第一课先帮你把最容易踩的三个坑列出来后面排错会省很多事现象根因处理方式上电后串口完全没有输出BOOT.BIN 没放到 SD 卡第一个 FAT32 分区或者分区类型不对重新分区第一个分区必须是 FAT32文件放在分区根目录U-Boot 能启动但停在Zynq提示符找不到 boot.scr 或 image.ubU-Boot 进入了命令模式确认 boot.scr 和 image.ub 都在 FAT32 分区根目录文件名大小写一致内核启动后报VFS: Unable to mount root fs根文件系统类型选错或内核 bootargs 里的 root 分区不存在检查 menuconfig 里的 rootfs 类型如果用 ext4确认 ext4 分区格式化且 bootargs 指向正确设备第二个坑特别典型。U-Boot 进入命令行之后不会告诉你“文件找不到”它只是跳过了 boot.scr然后停在提示符等你输入命令。这时候你可以先检查环境变量printenv bootcmd printenv bootargs然后手动执行一遍启动流程看看卡在哪一步ls mmc 0:1 load mmc 0:1 0x2000000 image.ub bootm 0x2000000这样能快速判断是文件路径问题、FIT 镜像格式问题还是 rootfs 问题。4.3 设备树错误排查方法设备树出问题日志通常不会直接告诉你“设备树第几行错”而是驱动 probe 失败、failed to get clock、no node found这类模糊信息。排查时我一般按这个顺序来先确认生成的 DTB 里有没有你要的节点。用fdtdump或dtc把 DTB 反编译出来搜索外设名字fdtdump images/linux/system.dtb | grep -A 20 axi_gpio再确认节点属性值对不对。重点看reg、interrupts、clocks这三项它们必须和 Vivado 的 Address Editor 里显示的一致。最后去看 Linux 内核日志里对应驱动的报错信息dmesg | grep -i gpio dmesg | grep -i ad9361设备树调试不建议靠猜把 DTB 反编译出来和 Vivado 里的硬件信息一列一列对通常很快能找到问题。5. 实战心得版本匹配、增量构建、AD9361 设备树迁移5.1 版本没对齐是百分之六十奇葩报错的根因这是我用了几年 petalinux 之后最深的体会。Vivado、Vitis、petalinux 这三个工具的版本必须严格对应。比如你用 Vivado 2025.1 导出的 XSA丢给 petalinux 2024.2 去导入大概率会出现设备树生成错误、U-Boot 源码不兼容、FSBL 版本不匹配等一堆奇怪问题。这些问题有时候报错信息很直白有时候完全不报错但最终的启动镜像就是跑不起来。所以我现在的习惯是建一个版本清单写清楚 Vivado 版本、petalinux 版本、内核版本、U-Boot 版本。所有工具链尽量用同一年份的 release。XSA 文件名里带上日期和 Vivado 版本号比如system_20250110_v2025.1.xsa。petalinux 工程根目录放一个 README记录这次构建用的 XSA 是哪一个。这套习惯看起来很基础但能避免很多“明明代码没变为什么换台电脑就编不过”的诡异问题。5.2 一线工程师应该掌握的几个增量构建命令petalinux-build全量构建一次可能要几个小时不可能每次改一行代码就全量编译。下面这几个命令我几乎天天用# 只重编设备树适合改 dtsi 后快速验证 petalinux-build -c device-tree # 只重编内核 petalinux-build -c kernel # 只重编 U-Boot petalinux-build -c u-boot # 导入新 XSA 后需要清理旧配置再重新生成 petalinux-config --get-hw-description/path/to/system.xsa --silentconfig petalinux-build -x mrproper petalinux-build注意最后那个mrproper它会把大部分编译产物清掉所以不要随便执行。只有当你改了硬件描述、换了 XSA发现增量编译结果出现诡异问题时才需要做一次彻底清理。另外一个小技巧build 完之后images/linux下会保留上一次的镜像。如果你想确认当前这个 image.ub 是什么时候编的可以直接看文件时间戳。我每次打包之前都会检查时间戳避免把旧镜像误当成新镜像烧到板子上。5.3 如何把 AD9361 原有设备树移到新 petalinux 工程里你搜到的热搜词里有“如何将 ad9361 原有设备树移到新建 petalinux 工程里”这个需求很常见。很多人手里有一套老工程里面关于 AD9361 的设备树已经调通了现在想移植到新的 petalinux 工程里省得重新调。直接复制粘贴肯定不行因为老工程里的设备树可能依赖某些 include 路径、宏定义、或者自定义驱动节点。我的建议是按下面两步走第一步把老工程里的ad9361.dtsi或相关节点清理干净放进新工程的project-spec/meta-user/recipes-bsp/device-tree/files/目录下。然后在同目录下的device-tree.bbappend里加上FILESEXTRAPATHS:prepend : ${THISDIR}/files: SRC_URI file://ad9361.dtsi这样 petalinux 构建设备树时就会把这个文件加入搜索路径。第二步在system-user.dtsi里 include 并覆盖需要的节点/include/ ad9361.dtsi axi_ad9361 { /* 新工程里这里可能要改时钟、GPIO 引脚或 SPI 片选 */ };这里要注意AD9361 的设备树节点通常不只是“把一个 dtsi 复制过来”那么简单。它依赖内核里的 IIO 驱动依赖 FPGA 里的 AXI 接口地址依赖时钟树配置。如果你新工程里的 PL 地址和原来的不一样设备树里的reg属性必须同步修改。还有一种更稳妥的做法是直接在system-user.dtsi里用${SOMETHING}这样的宏去引用 XSA 生成的硬件节点而不是写死地址。但这对初学者来说理解门槛较高所以如果你只是先跑通复制过来改地址是最直接的。迁移方式优点缺点直接 include 原 dtsi快改动少如果原 dtsi 依赖老工程路径可能编译报错放到 files 目录 SRC_URI干净、可复现、不影响原文件需要理解一点 Yocto 的 bbappend 机制在新工程里重新写节点最干净完全和当前硬件匹配工作量大需要非常熟悉 AD9361 的寄存器配置我个人推荐第二种。它既能保留老工程调试好的内容又不会污染自动生成的文件后续升级也方便。6. 第一版系统起来之后还要做什么6.1 系统启动后先检查这三件事当你第一次看到 Linux 登录提示符出现时先别急着高兴至少做三项检查确认这套系统是真的可用而不是“恰好能启动”。第一检查设备树到底有没有被内核正确解析cat /proc/device-tree/model如果打印出来的是你板子的型号名称说明设备树加载正常。如果这个文件不存在或者内容乱码说明设备树没配对。第二检查你关心的外设节点有没有被驱动绑定。以 AXI GPIO 为例ls /sys/class/gpio/ cat /proc/device-tree/axi/gpio40000000/status如果能在/sys/class/gpio下看到对应的 gpiochip说明驱动 probe 成功。第三检查启动日志里有没有被忽略的严重错误dmesg | grep -i error dmesg | grep -i fail不是说有 error 就一定不能用但你要知道每个 error 来自哪里。比如 SD 卡驱动的 error 可能只是 probe 顺序问题而 DMA 驱动的 error 很可能影响实际业务。6.2 把常用命令固化成脚本别靠记忆力我发现很多初学者喜欢一条一条敲命令敲完就忘下次重新配环境又要从头查。我的建议是一旦板子能正常启动立刻把整个构建流程写成一个脚本保存下来。下面这个脚本是我常用的模板#!/usr/bin/env bash set -e XSA${1:-system.xsa} source /opt/petalinux/2025.1/settings.sh petalinux-config --get-hw-description$XSA --silentconfig petalinux-build petalinux-package --boot \ --fsbl images/linux/zynq_fsbl.elf \ --fpga images/linux/system.bit \ --u-boot BOOT_DIR/tftpboot/zynq-led mkdir -p $BOOT_DIR cp -v images/linux/BOOT.BIN images/linux/boot.scr images/linux/image.ub $BOOT_DIR/这个脚本的作用不只是省时间它还保证了每一次构建用的流程是一致的。你不会因为某次忘了重新导入 XSA而拿到一个和硬件不匹配的旧镜像。后续就算换一台装机环境只要把脚本拷过去改一下 petalinux 安装路径就能跑出一套可复现的启动镜像。这一篇先讲到这里。下一篇文章我打算拿一块具体的 Zynq 板子完整走一遍“Vivado 点灯工程 - petalinux 最小系统 - 启动到命令行”的过程再把过程中遇到的报错和排查思路贴出来。如果你在迁移 AD9361 设备树或者制作 SD 卡时遇到过什么典型问题欢迎留言我会把高频问题补充到后续的排错清单里。