转眼手里的这块zynqMP板子已经稳定跑起来一个多月了。从画完PCB到点亮Linux中间踩过的坑比想象中多得多。如果你也正在为自研的Zynq UltraScale MPSoC开发板搭建Vivado硬件工程和Petalinux BSP这篇东西应该能帮你少走不少弯路。我说的是“自研开发板”不是官方评估板。官方板的BSP拿到就能跑但换到自己画的板子上DDR型号、时钟芯片、外设地址、PHY的复位脚全都变了Petalinux默认设备树基本没法直接用。你必须要自己从头用Vivado生成硬件描述再喂给Petalinux做系统适配。这个过程说复杂不算复杂但细节极其碎稍有一步对不上轻则启动卡死重则莫名其妙跑飞。这篇文章就把我从零到一的过程完整拆开包括工程怎么建、设备树怎么改、常见报错怎么排查希望能帮到正在折腾的小伙伴。1. 项目背景与整体思路拆解1.1 为什么自研开发板必须走VivadoPetalinux这套流程先明确一个概念Zynq UltraScale MPSoC是一个异构计算平台PS端Processing System是ARM核PL端Programmable Logic是FPGA逻辑。Linux跑在PS端但PS和PL之间怎么连接、DDR走什么参数、MIO引脚用来做什么、外设的中断号怎么分配这些全部要由硬件工程描述出来。官方开发板为什么拿过来就能跑因为Xilinx发布Petalinux BSP时已经按照官方板卡原理图把设备树、启动脚本、U-Boot环境变量全部配好了。自研板卡上面任何一丝差别——比如DDR的芯片颗粒变了、串口换了一组MIO、SD卡接到了不同的控制器都会导致官方BSP跑不起来。这不是能靠修复补丁解决的问题必须重新生成硬件平台再基于它生成Linux系统。所以我们这套流程的核心链路就是Vivado建硬件工程 → 导出XSA硬件描述文件 → Petalinux用XSA创建系统工程 → 修改设备树适配板卡 → 编译生成BOOT.BIN和image.ub → 烧录启动。听起来简单但每一步都有不少讲究下面从Vivado这块说起。1.2 版本搭配与工具链选型这一步决定了后面顺不顺如果只是自己玩版本随你高兴但如果是产品化或者长期维护的项目我强烈建议用固定的稳定组合。我这里使用的版本是Vivado 2020.2 Petalinux 2020.2对应使用的是Zynq UltraScale MPSoC器件型号为XCZU4EV。为什么选这个组合很简单2020.2之后Petalinux和Vivado的版本号强制对齐也就是Petalinux 2020.2只能解析Vivado 2020.2导出的XSA。早期的版本绑定没那么严格但到了2023以后的版本又有一堆新的依赖要求反而麻烦。我见过太多人把Vivado升到新版Petalinux还在用老版本结果XSA版本不兼容直接报“unsupported xsaspec”之类的错误。所以第一件事就是确认版本对应关系。查版本最简单的方法是打开Petalinux安装目录下的文档或者直接看Vivado安装时的配套说明但实际操作中建议不管多新的版本都先去看PetaLinux Release Notes里那个版本匹配表。另外Linux主机系统也需要注意Ubuntu 16.04、18.04、20.04分别对应不同年份的工具版本跨版本安装经常弹依赖错误。我自己就是重装了Ubuntu 20.04来匹配2020.2这套工具链。折腾完这套以后后续所有环节只需要在这个环境里跑省心很多。2. Vivado硬件工程搭建与核心细节2.1 创建工程初期最容易翻车的几个设置Vivado工程看起来是图形界面点一点就能完成但自研板卡和官方评估板最大的区别在于你不能直接从board file里面选板卡所有东西都要手动配置。第一步创建工程时选择RTL Project然后在Board Part那一页选择空板也就是“All Boards”里随便选一个通用型号或者直接把Project Part指定为你的芯片型号。这里有个小技巧如果你用的芯片型号有多个速度等级和封装一定确认封装后缀。比如XCZU4EV有SFVC784和FFVC900两个封装引脚完全不同。如果封装选错后面分配引脚时你会哭的因为原理图上的bank引脚编号根本对不上。接下来是硬件描述语言VHDL和Verilog随便选没差别。关键是后面创建Block Design时就要开始认真对待了。我创建BD的时候习惯把名字改成“system”这样后续导出XSA后Petalinux里引用的硬件名比较规整不至于出现什么top_inst_1之类怪名字。2.2 Block Design配置要点DDR和时钟是重头戏创建好Block Design后先添加Zynq UltraScale MPSoC的IP核。它会弹出一个配置界面里面几百个选项新手看着就头大。但核心只关注三块配置PS侧I/O外设、配置DDR、配置时钟。第一块是PS侧I/O外设。你要对照自己的原理图把用到的接口使能并且分配到正确的MIO引脚上。比如我用的是SD1接口接eMMC、UART1接调试串口、I2C1接板载EEPROM这几个都要在PS-PL Configuration页面里打开并且选择正确的引脚位置。这里特别提醒一下zynqMP的MIO分配不像老Zynq-7000那么松散每个接口都有固定可用的MIO范围不是随便能映射的。比如UART可以映射到MIO0-7但SD1只能从MIO0-15之类的地方选选错了Vivado会直接报错老老实实对照UG1085里的表格来。第二块是DDR配置。自研板卡很难跟官方默认参数完全一致所以DDR页面必须手动改。一般关注三个参数DDR类型DDR4还是LPDDR4、位宽32位还是64位、颗粒型号。如果原理图上用的DDR4颗粒没有直接列在Vivado的型号列表里你可以选一个容量、位宽、速率最接近的型号。但注意这只是让IP核生成可以综合的硬件描述真正的DDR训储算法会由Petalinux里的DDR工具在运行时校正上板后跑一下memtest才算数。第三块是时钟。zynqMP内部有六路PLL你可以给PL侧提供参考时钟。自研板卡如果有外部差分时钟振荡器接到PS的REF_CLK引脚上这个也要在配置界面的Clock Architecture里打开。另外PL侧的时钟输出频率不要超出IP允许范围否则后面生成比特流会报DRC错误。2.3 地址分配与中断连接影响系统能否识别PCIe和DMA如果你的板子有PL侧自定义逻辑比如PCIe、DMA、AXI接口的外设在BD里加完IP后要手动做地址分配。这里最大的坑是地址重叠。Vivado的Address Editor默认会帮你自动分配但多个IP顺序不对时可能导致地址空间不够或者误覆盖。建议把高带宽的数据通路比如DDR映射到地址较高的区域把控制类寄存器映射到低地址区。中断连接也是一个容易忽略的点。PL到PS的中断默认是没连线的必须双击Zynq UltraScale MPSoC IP核在PS-PL中断配置里打开对应的中断端口然后在BD图上把PL IP的中断输出线连到pl_ps_irq0或pl_ps_irq1上。这个要是漏了驱动里request_irq申请不到中断设备工作不起来而且不查原理图根本发现不了。一切配置完成后可以开始综合和实现。在跑实现之前先做一次Address Editor检查再把Board Part的信息核对一遍。实现完成后生成比特流。2.4 Vivado生成比特流失败排查血泪经验热搜词里“vivado生成比特流失败”出现频率特别高我自己第一次也给卡住了但绝大多数情况不是逻辑错误而是时序收敛或DRC没过。常见的失败提示有三种时序错误timing negative slack。解决思路只有一个打开综合后的原理图找到时序报告中路径最长的那几根线看看是哪几个逻辑级数太高然后在Block Design里给关键路径添加AXI寄存器切片或者让综合工具优化努力等级调到ExtraTimingOpt。DRC错误比如IO引脚分配冲突、时钟没有连接到引脚、未使用的bank电压没配。这类错误其实最好解决直接在Message窗口里看具体是哪条规则被违例然后对照原理图调整约束文件。比如FPGA侧的LED和按键如果在同一个bank必须要拥有统一的IO标准一个LVCMOS33一个LVCMOS18就会报DRC错误。资源不足BRAM或DSP不够。这时候只能优化设计或者考虑换更大芯片没太多技巧。生成比特流成功后Vivado会自动把所有硬件信息打包。接下来就是导出XSA文件了。注意哈导出时一定要勾选“Include bitstream”否则后面Petalinux构建时无法生成BOOT.BIN。3. Petalinux工程创建与设备树定制3.1 从XSA创建Petalinux工程这条命令背后发生了什么拿到XSA文件以后进入Petalinux环境创建工程用一行命令petalinux-create -t project -n myboard --template zynqMP cd myboard petalinux-config --get-hw-description/path/to/xsa第一次跑配置时Petalinux会把XSA里描述的硬件信息解析到子系统配置中具体包括启动模式、DDR地址范围、外设配置、PL bitstream。这一步如果报错说XSA版本不兼容基本就是工具版本不匹配问题回查一下版本对应的Petalinux版本即可。配置界面有几个重点需要改。首先是Linux内核版本默认跟随Petalinux版本一般不用动。然后是根文件系统如果你不需要复杂桌面或者图形界面选initramfs就行它会将根文件系统打包进内核启动减少对外部存储的依赖。如果板子有eMMC或SD你可以后面改成ext4把根文件系统放到外部存储。然后注意U-Boot配置。zynqMP的启动流程是BootROM → FSBL → U-Boot → kernelPetalinux会把FSBL、U-Boot、设备树、内核、根文件系统一并打包进BOOT.BIN或image.ub。在U-Boot配置里比较关键的是启动设备如果你的板子从SD启动选SD从QSPI启动选QSPI。选错的话U-Boot起来以后加载不到内核镜像卡在“Wrong Image Format for bootm command”。3.2 petalinux设备树定制主板启动的关键战役Petalinux设备树可能是整个项目里最需要耐心的地方。虽然XSA里已经自动生成了大部分硬件的设备树节点但很多细节还是需要针对自研板卡做手工修改。最常见的问题就是串口别名。zynqMP有两个UART控制器如果XSA里把UART1接成了调试口但U-Boot和内核默认使用的却是UART0启动时console直接没输出看起来像死机一样。遇到这种情况去设备树里检查chosen节点下面的stdout-path务必让它指向实际使用的串口。DDR节点也值得重视。XSA生成的设备树会把DDR的reg属性设置成DDR控制器允许的地址范围。如果你的DDR容量是4GB但地址空间只配了2GB可以在设备树里手动扩展开但前提是U-Boot里DDR training确实已经识别出完整容量。否则改了也白改。网卡设备树节点也是自研板卡的痛点。zynqMP的内置MAC有多个具体使用哪个取决于原理图上的ETH接口连接到哪个RGMII引脚。如果你用的是PS侧的GEM3但设备树默认只启用了GEM0那网卡根本扫描不到。需要在设备树里把对应的ethernet节点status改成okay同时确认phy-mode、phy-handle以及PHY的复位GPIO是否正确。设备树修改后需要重新编译。Petalinux提供了一个很方便的机制你可以直接编辑项目目录下components/plnx_workspace/device-tree/device-tree/里面的dtsi文件然后运行petalinux-build -c device-tree这个命令会重新生成设备树dtb。之后再整体编译时Petalinux会自动打包进boot镜像。3.3 配置与构建三步走流程Petalinux构建整体分三部分内核、U-Boot、根文件系统。第一次全套构建时间比较长大概一两个小时取决于机器性能。但后续增量编译就快多了。内核配置可能出现的坑是缺少某些驱动模块。比如你要用USB转串口调试需要在内核配置里打开USB Serial Gadget或PL2303驱动。如果没有打开硬件正确也枚举不到设备。U-Boot配置里需要关注启动环境变量。zynqMP的U-Boot默认环境变量可以从Petalinux菜单里修改也可以直接改U-Boot源码里的默认env。我建议一开始先用petalinux-config -c u-boot进入菜单把bootargs里面的console参数修正常见格式是consolettyPS0,115200 root/dev/mmcblk0p2 rw确保根文件系统分区编号正确。如果你板子上eMMC是mmcblk0SD卡是mmcblk1这也要对应修改。构建完成后生成的核心文件BOOT.BIN由FSBL、PMU固件、U-Boot、比特流组成image.ub内核设备树根文件系统镜像这些文件写进启动介质就能跑了。4. 常见问题与排查技巧实录4.1 一张问题速查表覆盖启动全流程我把这段时间遇到过的典型问题整理成了表格方便大家对照排查。现象可能原因解决思路上电后调试串口完全无输出FSBL没启动DDR初始化失败或时钟没起来检查电源时序和PS参考时钟确认BOOT引脚拨码正确串口有输出但卡在“U-Boot SPL”DDR training失败或启动设备选错重新检查U-Boot启动设备配置确认DDR型号与参数内核启动时panic挂载不了根文件系统设备树里根文件系统分区指定错误核对内核启动参数root指向的实际分区网卡没有IPGEM没启用或PHY复位脚不对检查设备树ethernet节点用mdio工具扫描PHY地址PL侧寄存器读写无效PL没有正确加载比特流确认BOOT.BIN里包含bitstream且FPGA配置引脚正确U-Boot加载image.ub失败镜像格式不匹配确认petalinux-build正确完成镜像路径和启动命令对应4.2 启动卡死在DDR training的排查思路我这里想单独把DDR training拿出来说因为它太典型了。zynqMP上DDR控制器不是简单上电就能用U-Boot里面会运行一套内存训练算法说白了就是测试内存读写时序校准各种延迟。如果你的板子DDR布线比较长阻抗控制不好或者原理图上参考电压接法不对训练就会失败。遇到DDR training失败第一步不是去调设备树而是回到Vivado那边检查BD里DDR配置的型号和位宽。然后用JTAG连接板子打开Vivado Hardware Manager读取PS端的DDR寄存器状态看看控制器有没有报错误标志。如果实在训练不过可以把DDR频率降低一档再试比如原本配的是2400MT/s可以降到2133MT/s。还有一个小技巧在U-Boot环境变量里设置memtest1让它跑一遍内存自检看看哪些地址范围有问题。我遇到过一种情况单颗粒的DDR4在训练时成功但双面四片总跑不过最后发现是Vivado里位宽选错。4.3 Vivado工程清理和版本迁移老生常谈但必须说热搜词里有“vivado工程清理”和“vivado工程进行版本降级”这确实很常见。因为Vivado工程目录动不动几个GB拷给别人或上传Git很不方便。我建议在工程目录下执行vivado -mode batch -source clean.tcl这个Tcl脚本可以移除临时生成文件但保留源码和约束。或者更简单直接右键工程目录删除*.cache、*.hw、*.runs下的大文件但注意导入的时候要重新综合。版本降级的问题也比较麻烦。Vivado高版本工程没法直接让低版本打开但可以导出到低版本在Vivado里File → Export → Export Block Design再用低版本创建工程后导入BD。但IP版本可能变动有时候需要自己手动升级或降级IP。如果版本差得太多还不如直接在低版本里重新搭BD反正核心配置就那些。4.4 工具链安装问题Java报错和WinPcap这类周边坑“vivado安装时显示a fatel error has been detected by the java runtime envi”和“vivado winpcap安装失败”这种问题严格来说跟项目本身无关但会卡你很久。Java报错一般出现在Windows安装Vivado时原因是安装目录包含中文字符或权限不够。解决办法是安装到纯英文路径以管理员身份运行安装器。Linux环境下则少很多Ubuntu安装时注意用./xsetup而不是普通执行避免权限异常。WinPcap安装失败通常是因为系统没有关闭UAC或者旧版WinPcap残留。Vivado安装时的WinPcap组件是用来做仿真调试的对大多数人来说不是必须。如果装不上可以直接跳过不影响综合实现和生成比特流。后面要用到仿真时再单独装一个兼容版本的WinPcap。5. 验证与调试经验总结5.1 上电启动验证流程用最小系统排除问题板子做回来以后第一次上电千万不要直接跑系统。我习惯先做最小系统验证给板子供电检查所有电源轨的电压是否正常然后测量时钟引脚用示波器看PS参考时钟频率是否正确。接着用JTAG连接Vivado Hardware Manager扫描设备确认能识别到FPGA。这一步通过后再烧录BOOT.BIN。很多人上来就把BOOT.BIN写进SD卡结果启动卡死然后反复改设备树但其实是FPGA都没起来方向完全错了。所以这个顺序一定不能跳。5.2 日志怎么看确实能让问题定位快一倍启动日志里最常见的三个阶段FSBL阶段的日志以“Xilinx Zynq MP First Stage Boot Loader”开头后面会打印DDR信息U-Boot阶段的日志以“U-Boot 2020.01”开头会打印启动设备、内存大小、设备树地址内核阶段的日志以“Starting kernel”开头接着是大量内核初始化信息如果哪个阶段没有对应日志问题范围立刻缩小。比如U-Boot没有打印但FSBL已经打印那大概率是U-Boot镜像损坏或DDR训练的问题。如果U-Boot打印了但内核没有看看是不是启动参数没指定正确的设备树地址。调试时还可以打开Petalinux的日志级别在petalinux-build时添加verbose参数petalinux-build -v这样能输出所有编译细节特别是在怀疑某个驱动没编进去的时候很有用。5.3 把PL端逻辑加进去以后验证AXI通路如果你的板子有PL端自定义IP启动Linux后第一件事是确认设备树里有没有生成对应的platform device节点。Petalinux的XSA解析会自动把带有PCW属性的IP生成为platform驱动节点但有些自定义的AXI IP需要自己写设备树节点。验证AXI通路最简单的方法是写一个小驱动程序直接映射物理地址读写几个寄存器。比如你的IP基地址是0xA0000000在Linux下可以这样测试devmem 0xA0000000这个命令会读32位数据然后再写一个值再读回验证。这个方法很简单但能快速确认PL逻辑地址映射、时钟和复位是否正常。这里有一个经验如果devmem读回的值始终是0或者全是F基本就是地址没映射成功如果读回的值随机跳变可能是时序问题需要检查AXI总线的时钟频率是否满足IP要求。写在最后几个个人经验很多细节在官方文档里都有但真正串起来还是有门槛。我做完这块板子最大的感受是Vivado和Petalinux本身不难难的是理解整个启动链路和设备树机制。你只要把每个阶段在做什么搞清楚遇到问题就不会慌。最后分享一个小技巧每次修改设备树或者硬件配置之前先备份当前能启动的BOOT.BIN和image.ub。这样即便改废了也能快速刷回上一个能用的系统不至于卡死在调试阶段来回折腾。这个习惯帮我省了好多时间。希望这篇文章能给你的zynqMP自研板开发带来一点帮助祝早日跑通Linux。