Distro Boot with Boot.scr

Starting with Petalinux Version 2020.1, the industry standard "distro boot" boot flow for U-boot has been implemented as default by Xilinx. (see xilinx-wiki.atlassian "Using Distro Boot With Xilinx U-Boot")

The distro boot functionality is implemented as an extension of the existing U-Boot bootcmd functionality in U-Boot. It extends its functionality by redirecting the call to bootcmd to a call to the distro_bootcmd variable.

bootcmd=run distro_bootcmd

The distro_bootcmd variable typically contains a sequence of commands that scans a pre-defined list of potential boot targets in search of boot collateral as shown below.

boot_targets=qspi jtag mmc0 mmc1 qspi nand nor usb0 usb1 pxe dhcp
distro_bootcmd=for target in ${boot_targets}; do run bootcmd_${target}; done
bootcmd_qspi=sf probe 0 0 0 && sf read ${scriptaddr} ${script_offset_f} ${script_size_f} && echo QSPI: Trying to boot script at ${scriptaddr} && source ${scriptaddr}; echo QSPI: SCRIPT FAILED: continuing...;

The boot_targets list is defined in the platform definition in the U-Boot source tree.

Depending on the specifics of the target platform, the distro boot infrastructure can either use the boot_targets list to explicitly find specific boot collateral (eg. hard-coded loading once a valid boot target is located) or it can be used to locate some kind of decoupled configuration information.

Boot Method Precedence

The order of precedence for searching for boot components is as follows

1. extlinux.conf file (located in /extlinux/ or /boot/extlinux/)
2. boot.scr file + image.ub file
3. boot.scr file + individual files (Image, system.dtb, etc.)

Using the boot.src method

In absence of a valid extlinux.conf file, U-Boot will scan the boot_targets list looking for a file named boot.scr.uimg or boot.scr (in that order) and run any commands located in the script file. If your environment requires a different sequence of commands or behaviour, you can edit the boot.scr file to suit your needs.

Install u-boot-tools on Linux OS

Before using the mkimage function, the u-boot-tools needs to be installed.

sudo apt-get update
sudo apt install u-boot-tools

Modifying an existing boot.scr file

For the modification of the boot.scr file convert the existing boot.scr file into an boot.script file:

dd if=boot.scr of=boot.script bs=72 skip=1

Than modify the boot.script file based on your needs. For example, when booting from SD card or QSPI flash, the following boot.script file should work after conversion into an boot.scr file.

# This is a boot script for U-Boot
# Generate boot.scr:
# mkimage -c none -A arm -T script -d boot.script boot.scr
#
################
imageub_addr=0x10000000
# 
imageub_flash_addr=0x200000
imageub_flash_size=0xD90000

echo [TE_BOOT-01] Trenz Boot-file version 0.1 (development);
echo [TE_BOOT-10] Chosen Bootmode is ${modeboot} from boot_targets=${boot_targets};
echo [TE_BOOT-11] Found boot.scr in device: ${target}

for boot_target in ${boot_targets};
do

	# Boot target is sd card: image.ub on mmc0
	if test "${boot_target}" = "mmc0"; then
		echo [TE_BOOT-20] Try to use: image.ub from ${boot_target};
		mmc dev 0
		if test -e ${devtype} 0:${distro_bootpart} /image.ub; then
			fatload ${devtype} 0:${distro_bootpart} ${imageub_addr} image.ub;
			bootm ${imageub_addr};
		fi
	fi
	if test "${boot_target}" = "mmc1"; then
		echo [TE_BOOT-21] Try to use: image.ub from ${boot_target};
		mmc dev 1
		if test -e ${devtype} 1:${distro_bootpart} /image.ub; then
			fatload ${devtype} 1:${distro_bootpart} ${imageub_addr} image.ub;
			bootm ${imageub_addr};
		fi
	fi
	# Boot target is qspi: image.ub on qspi; image.ub is included in BOOT.bin
	if test "${boot_target}" = "qspi"; then
		echo [TE_BOOT-30] Try to use: image.ub from ${boot_target};
		sf probe 0 0 0;
		sf read ${imageub_addr} ${imageub_flash_addr} ${imageub_flash_size};
		bootm ${imageub_addr};
	fi
done

Note: The alias name ${devnum} used so far does not work in all variants tested as described in the following chapter "Tested boot combinations with example boot script file for TE0715", therefore the mmc boot_targets were split up

Please remember that the boot.script file needs to be converted back into the boot.scr file after the edits are complete

mkimage -c none -A arm -T script -d boot.script boot.scr

Tested Boot combinations with example boot script file for TE0715

Set Boot Mode is SD-Boot:

Set Boot Mode is QSPI-Boot:

BOOT.bin^1 (for SD Card or qspi flash): 

• fsbl.elf
• test_board.bit
• u-boot.elf

BOOT.bin^2 (for qspi flash):

• fsbl.elf
• test_board.bit
• u-boot.elf
• image.ub
• boot.scr

BOOT.bin^3 (for qspi flash):

• fsbl.elf
• test_board.bit
• u-boot.elf
• boot.scr

Booting from QSPI

Option 1 (Boot.bin on QSPI Flash and image.ub and boot.scr on SD):

1. Connect JTAG and power on carrier with module (boot mode set to SD boot and no SD card is inserted)
2. Open Vivado Project with "vivado_open_existing_project_guimode.cmd" or if not created, create with "vivado_create_project_guimode.cmd"
3. Type on Vivado TCL Console: TE::pr_program_flash -swapp u-boot
   Note: To program with SDK/Vivado GUI, use special FSBL (zynq_fsbl_flash) on setup
            optional "TE::pr_program_flash -swapp hello_te0715" possible
4. Copy boot.scr and image.ub on SD-Card
   • use files from (<project folder>/_binaries_<Article Name>)/boot_linux from generated binary folder,see: Get prebuilt boot binaries
   • or use prebuilt file location, see <design_name>/prebuilt/readme_file_location.txt
5. Set boot mode to QSPI-Boot mode and insert SD card.
   • Depends on Carrier, see carrier TRM.

Option 2 (Boot.bin with image.ub and boot.scr on QSPI Flash):

1. Connect JTAG and power on carrier with module (boot mode set to SD boot and no SD card is inserted)
2. Open Vivado Project with "vivado_open_existing_project_guimode.cmd" or if not created, create with "vivado_create_project_guimode.cmd"
3. Type on Vivado TCL Console: TE::pr_program_flash -swapp u-boot
   Note: To program with SDK/Vivado GUI, use special FSBL (zynq_fsbl_flash) on setup
            optional "TE::pr_program_flash -swapp hello_te0715" possible
4. Set boot mode to QSPI-Boot mode and start the board.
   • Depends on Carrier, see carrier TRM.

Note: When booting from a QSPI device, care must be taken to maintain a very specific scheme for where files are located both in the nonvolatile flash device as well as where they are loaded into DDR prior to hand-off to the robust operating system.

scriptaddr=0x3000000
script_offset_f=fc0000
script_size_f=0x40000
bootcmd_qspi=sf probe 0 0 0 && sf read ${scriptaddr} ${script_offset_f} ${script_size_f} && echo QSPI: Trying to boot script at ${scriptaddr} && source ${scriptaddr}; echo QSPI: SCRIPT FAILED: continuing...;

Booting from SD

1. Copy image.ub, boot.scr and Boot.bin on SD-Card.
   • use files from (<project folder>/_binaries_<Article Name>)/boot_linux from generated binary folder,see: Get prebuilt boot binaries
   • or use prebuilt file location, see <design_name>/prebuilt/readme_file_location.txt
2. Set Boot Mode to SD-Boot.
   • Depends on Carrier, see carrier TRM.
3. Insert SD-Card in SD-Slot.

bootcmd_mmc0=devnum=0; run mmc_boot
mmc_boot=if mmc dev ${devnum}; then devtype=mmc; run scan_dev_for_boot_part; fi

References

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/749142017/Using+Distro+Boot+With+Xilinx+U-Boot#UsingDistroBootWithXilinxU-Boot-BootTargets

https://wiki.ubuntu.com/ARM/EditBootscr