PetaLinux Gotchas with XSA Templates and PL Programming

---

Key Points

• Creating a PetaLinux project from a template does not fully auto-detect the board from the XSA
• Device Tree Generator (DTG) must be explicitly configured
• Linux kernel may fail to boot if the Programmable Logic (PL) is not programmed
• These issues can appear as early boot hangs or RCU stalls

Examples & Details

References:

• PetaLinux Tools Reference Guide: https://docs.amd.com/r/en-US/ug1144-petalinux-tools-reference-guide

• DTG Configuration Settings: https://docs.amd.com/r/en-US/ug1144-petalinux-tools-reference-guide/DTG-Settings

• When importing an .xsa into a PetaLinux project, DTG is not automatically set to infer configuration from hardware

• DTG must be manually set to AUTO:

                petalinux-config
                → DTG Settings
                → (DTG_AUTOCONFIG) AUTO
              
            

• In another case, the Linux kernel would not boot because PL-based peripherals were expected
• The kernel stalled because the PL bitstream was never loaded

Questions & Clarifications

• Is DTG behavior consistent across PetaLinux versions?
• Which boot stage is best for PL programming in this setup (FSBL vs U-Boot)?
• Can missing PL programming always be detected via boot logs?

Action Items / Next Steps

• Review AMD documentation for DTG behavior and defaults

  • PetaLinux Tools Reference Guide: https://docs.amd.com/r/en-US/ug1144-petalinux-tools-reference-guide
  • DTG Settings Reference: https://docs.amd.com/r/en-US/ug1144-petalinux-tools-reference-guide/DTG-Settings

• Always verify DTG settings after importing an XSA

• Confirm PL programming is included in the boot flow

• Add a pre-boot checklist for PetaLinux projects

• Document boot dependencies between PS and PL peripherals

Summary

PetaLinux templates simplify project creation but do not eliminate the need for explicit configuration. DTG must be set to AUTO to properly generate the device tree from an XSA, and Linux will not boot correctly if it depends on PL-based hardware that has not been programmed. Making these steps explicit early prevents long debugging sessions.

---