Date: Thu, 28 Mar 2024 22:00:58 +0000 (UTC) Message-ID: <2026803988.1.1711663258199@74cc05f75d4d> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_0_1770287980.1711663258182" ------=_Part_0_1770287980.1711663258182 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This pages provides information related to using the industry standard "di= stro boot" boot flow for U-boot as it's been implemented by Xilinx. = p>
While x86-based platforms have a de facto standardization of how boot op= erates from BIOS/UEFI during initial power-on until hand-off to a robust op= erating system like Linux or Microsoft Windows, this is largely incidental = and has much to do with the limited number of x86-based vendors in the mark= et. By contrast, the number of Arm-based SoC platforms numbers in the dozen= s and virtually every SoC has some form of unique boot process.
Supporting all these unique Arm platforms can be tedious at best and at = worst quickly devolves to inconsistencies in the expectations and experienc= es on each. These inconsistencies quickly escalate into increased developme= nt time and maintenance costs for the software teams involved.
Distro boot is an embedded-focused boot methodology with the primary aim= to make booting Arm-based platforms more standardized and predictable; sim= ilar to the experience on x86-based desktop and server platforms. The prima= ry way that distro boot accomplishes this goal is by decoupling the boot-ti= me discovery of boot media from the remainder of the bootloader and firmwar= e stack.
For example, on a Xilinx Zynq UltraScale+ platform, the initial power-on= is run via the SoC's in-built BootROM. The BootROM then discovers the prim= ary boot medium via a sample of the SoC's MODE pins and uses this to hand-o= ff to the Xilinx First Stage Boot Loader or FSBL.
During the runtime of the FSBL, other components such as the Xilinx-spec= ific PMU firmware and Arm Trusted Firmware are loaded before handing off to= U-Boot as the second stage bootloader. From an end-user perspective, these= operations are analogous to the BIOS/UEFI experience on an x86-based platf= orm.
That is, the first point in execution where context-aware decisions need= to be made during the boot process is during the hand-off from U-Boot to t= he robust operating system environment. Distro boot provides a framework in= which these choices can be made in a predictable and platform-independent = manner.
The distro boot functionality is primarily implemented as an extension o= f the existing U-Boot bootcmd functionality in U-Boot. In a standard U-Boot= boot process, the bootcmd variable contains the sequence of commands to be= executed automatically after the boot countdown finishes (eg, if no key is= pressed). The bootcmd variable contains a sequence of commands that are ex= ecuted sequentially in order to load and hand-off to the next stage of boot= .
For example, a simple TFTP-based boot is illustrated below.
bootcmd= =3Decho Booting from network ...; usb start; setenv ethact asx0; if dhcp &a= mp;& tftp $loadaddr $bootfile && tftp $f
Distro boot extends this functionality by redirecting the call to bootcm= d to a call to the distro_bootcmd variable.
bootcmd= =3Drun distro_bootcmd
How the distro_bootcmd variable is defined and used differs by vendor bu= t it typically contains a sequence of commands that scans a pre-defined lis= t of potential boot targets in search of boot collateral as shown below.
boot_tar= gets=3Dmmc0 jtag mmc0 mmc1 qspi0 nand0 usb0 usb1 scsi0 pxe dhcp distro_bootcmd=3Dscsi_need_init=3D; for target in ${boot_targets}; do run b= ootcmd_${target}; done
The command loops through the contents of the boot_targets list and scans t=
he media in order looking for additional boot collateral. 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 infrastr=
ucture can either use the boot_targets list to explicitly find specific boo=
t collateral (eg, hard-coded loading once a valid boot target is located) o=
r it can be used to locate some kind of decoupled configuration information=
.
Specifically, the distro boot infrastructure will first scan for a file = named extlinux.conf at the pre-defined locations (ex: /extlinux/extlinux.co= nf or /boot/extlinux/extlinux.conf) in the default U-Boot environment. The = basic syntax of the extlinux.conf file is as show below.
LABEL Li= nux KERNEL Image FDT system.dtb INITRD rootfs.cpio.gz.u-boot
Once U-Boot has found this file it will parse the fields as defined and = hand-off to the components specified in the file. The syntax of this file r= eferences paths in the boot media. For example, a value of KERNEL I= mage will look for the file Image in the same directory of the boo= t media as the extlinux.conf. Conversely, a value of /boot/linux-im= age-5.2 will look for a file name linux-image-5.2= in the directory /boot of the filesystem.
Starting in 2020.1, this the default method used by Petalinux.
In the 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 or= der) and run any commands located in the script file. An example of = the script file syntax is seen below. If your environment requires a = different sequence of commands or behavior, you can edit the boot.scr file = to suit your needs.
for = ;boot_target in ${boot_targets}; do if test "${boot_t= arget}" =3D "jtag" ; then . . . <COMMANDS> . . . fi if test "${boot_t= arget}" =3D "mmc0" || test "${boot_target}" =3D&nb= sp;"mmc1" ; then . . . <COMMANDS> . . . fi if test "${boot_t= arget}" =3D "xspi0"; then . . . <COMMANDS> . . . fi done
It's important to note that this syntax is standard U-Boot HUSH scriptin= g syntax. The only change being made here is that this script is loaded int= o the environment during the boot process rather than being compiled in to = the binaries.
Prior to use in a distro boot environment, the boot script must be compi= led using mkimage as noted in the examples below.
The recommended method for packaging the boot.scr image is to use the U-= Boot FIT format with a script similar to:
/dts-v1/= ; / { description =3D "Boot script"; images { default =3D "script"; script { description =3D "Boot scrip= t"; data =3D /incbin/("./boot.s= cr"); type =3D "script"; compression =3D "none"; hash { algo =3D "sha= 1"; }; }; }; };
Packaging a FIT image is similar to the legacy method in that it uses mk= image but the syntax is much simpler:
mkimage = -f boot.fit boot.scr.uimg
If your design does not require the additional features provided in the = FIT description method seen above, the image can be packaged simply with th= e mkimage command directly:
mkimage = -C none -A arm -T script -d boot.scr boot.scr.uimg
If you need to edit an existing packaged boot.scr file (or boot.scr.uimg= ), you can extract the plain ASCII text format using the following command = line:
tail -c+= 73 < boot.scr.uimg > out
Remember that the boot.scr file will need be re-packaged with mkimage af= ter the edits are complete.
Starting with the 2020.1 release, Xilinx has switched to using the distr= o boot infrastructure by default for all SoC platform. The default me= chanism in the Xilinx-provided software stack utilizes the boot.scr framewo= rk. Support is still present for using extlinux.conf files and they w= ill be used if present. The platform files which define the boot_targ= ets list and the Xilinx-specific default U-Boot environment are:
SoC Platform |
Path in U-Boot Source Tree |
---|---|
Zynq-7000 |
include/configs/zynq-common.h |
Zynq UltraScale+ MPSoC |
include/configs/xilinx_zynqmp.h |
Versal |
include/configs/xilinx_versal.h |
On Xilinx platforms, the boot_targets list always prepends the current p= rimary boot mode as configured on the MODE pins. Thus, it is expected to se= e a given target more than once in the boot_targets variable. For example, = on a Zynq UltraScale+ MPSoC device booting from SD card, the boot_targets l= ist appears as:
boot_tar= gets=3Dmmc0 jtag mmc0 mmc1 qspi0 nand0 usb0 usb1 scsi0 pxe dhcp
In addition, the Xilinx distro boot infrastructure is implemented such that=
if a boot script file is found, these commands are utilized to load the bo=
ot components from specific locations on the boot medium to specific locati=
ons in memory. Further, the default Xilinx workflow is to name the compiled=
version of the boot script boot.scr rather than boot.scr.uimg (though both=
will still work).
For example, when booting from MMC devices (SD card or eMMC), the following script is run from the boot.scr = file by default in the Xilinx-provided U-Boot environment. This can b= e modified based on your needs.
if test = "${boot_target}" =3D "mmc0" || test "${boot_target}" =3D "mmc1" ; then if test -e ${devtype} ${devnum}:${distro_bootpart} /image.ub; then fatload ${devtype} ${devnum}:${distro_bootpart} 0x10000000 image.ub; bootm 0x10000000; exit; fi if test -e ${devtype} ${devnum}:${distro_bootpart} /Image; then fatload ${devtype} ${devnum}:${distro_bootpart} 0x00200000 Image;; fi if test -e ${devtype} ${devnum}:${distro_bootpart} /system.dtb; then fatload ${devtype} ${devnum}:${distro_bootpart} 0x00100000 system.dtb= ; fi if test -e ${devtype} ${devnum}:${distro_bootpart} /rootfs.cpio.gz.u-boo= t; then fatload ${devtype} ${devnum}:${distro_bootpart} 0x04000000 rootfs.cpi= o.gz.u-boot; booti 0x00200000 0x04000000 0x00100000 exit; fi booti 0x00200000 - 0x00100000 exit; fi
For additional details on the usage of the bootm
and =
booti
commands, see the U-Boot p=
age.
Of note in this scheme is that the files must be found in the root of th= e filesystem and follow the naming scheme:
Component |
File Name |
Load Address |
U-Boot combined image file (image.ub) |
image.ub |
0x10000000 |
Linux kernel image file (if image.ub is not found) |
Image |
0x00200000 |
Linux device tree file (if image.ub is not found) |
system.dtb |
0x00100000 |
Linux root filesystem image (if image.ub is not found) |
rootfs.cpio.gz.u-boot |
0x04000000 |
When the boot mode detected is QSPI, the following script is run from th= e boot.scr file by default in the Xi= linx-provided U-Boot environment. This can be modified based on your = needs.
if test = "${boot_target}" =3D "xspi0" || test "${boot_target}" =3D "qspi" || test "$= {boot_target}" =3D "qspi0"; then sf probe 0 0 0; if test "image.ub" =3D "image.ub"; then sf read 0x10000000 0xF00000 0x6400000; bootm 0x10000000; exit; fi if test "image.ub" =3D "Image"; then sf read 0x00200000 0xF00000 0x1D00000; sf read 0x04000000 0x4000000 0x4000000 booti 0x00200000 0x04000000 0x00100000 exit; fi exit; fi
When booting from a QSPI device, care must be taken to maintain a very spec=
ific scheme for where files are located both in the nonvolatile flash devic=
e as well as where they are loaded into DDR prior to hand-off to the robust=
operating system.
Component |
Flash Address |
Load Address |
U-Boot combined image file (image.ub) |
0xF00000 |
0x10000000 |
Linux kernel image file (if image.ub is not found) |
0xF00000 |
0x00200000 |
Linux device tree file (if image.ub is not found) |
Pre-loaded by BOOT.BIN |
0x00100000 |
Linux root filesystem image (if image.ub is not found) |
0x4000000 |
0x04000000 |
Note: The table above presents default values = as found in the pre-built collateral. The PetaLinux tools will automa= tically adjust the flash and load addresses as appropriate to fit the relat= ive sizes of each payload partition.
It is important to note that when booting from MMC devices, U-Boot will = load all of the individual components from the boot media as files. When bo= oting from flash devices, all of the components are loaded by U-Boot ex= cept for system.dtb. For flash devices, the system.dtb file is assumed= to be pre-loaded to the correct address by FSBL from the BOOT.BIN file.
In JTAG boot mode, U-Boot will look for boot.scr.uimg in DDR a= t address 0x20000000. This is set by environment variable SCRIPTADDR.= In the eMMC/SD bootmodeit U-Boot will look for a file named boo= t.scr.uimg in the primary FAT file system partition. When bootin= g from QSPI or NAND devices, U-Boot will expect boot.scr.uimg to = be flashed at address 0x3E80000. This value is configurable in the CONFIG_B= OOT_SCRIPT_OFFSET variable.
In summary, the order of precedence for searching for boot components is= as follows
extlinux.conf file (located in /extlinux/ or /boot/extlinux/)
boot.scr file + image.ub file
boot.scr file + individual files (Image, system.dtb, etc.)
https://gitlab.denx.de/u-bo=
ot/u-boot/blob/master/doc/README.distro
https://www.denx.de/wiki/view/DULG/UBootEnvVariables
https://wiki.syslinux.org/wiki/index.php?title=3DConf=
ig
http://www.freedesktop.o=
rg/wiki/Specifications/BootLoaderSpec/