Table of Contents
U-Boot is an open source Universal Boot Loader that is frequently used in the Linux community. Xilinx provides a Git tree located at https://github.com/Xilinx/u-boot-xlnx which includes U-Boot to run on Xilinx boards. The Xilinx U-Boot project is based on the source code from http://git.denx.de.
U-Boot CommandsThe list of U-Boot commands can be accessed while in the U-Boot prompt. Type "help" or "?" for a complete listing of available commands. Below an example is given:
? - alias for 'help'
base - print or set address offset
bdinfo - print Board Info structure
boot - boot default, i.e., run 'bootcmd'
bootd - boot default, i.e., run 'bootcmd'
bootm - boot application image from memory
bootp - boot image via network using BOOTP/TFTP protocol
cmp - memory compare
coninfo - print console devices and information
cp - memory copy
crc32 - checksum calculation
date - get/set/reset date && time
echo - echo args to console
editenv - edit environment variable
erase - erase FLASH memory
ext2load- load binary file from a Ext2 filesystem
ext2ls - list files in a directory (default /)
fatinfo - print information about filesystem
fatload - load binary file from a dos filesystem
fatls - list files in a directory (default /)
fdt - flattened device tree utility commands
flinfo - print FLASH memory information
go - start application at address 'addr'
help - print command description/usage
iminfo - print header information for application image
imls - list all images found in flash
imxtract- extract a part of a multi-image
itest - return true/false on integer compare
loadb - load binary file over serial line (kermit mode)
loads - load S-Record file over serial line
loady - load binary file over serial line (ymodem mode)
loop - infinite loop on address range
md - memory display
mm - memory modify (auto-incrementing address)
mmc - MMC sub system
mmcinfo - display MMC info
mtest - simple RAM read/write test
mw - memory write (fill)
nfs - boot image via network using NFS protocol
nm - memory modify (constant address)
ping - send ICMP ECHO_REQUEST to network host
printenv- print environment variables
protect - enable or disable FLASH write protection
rarpboot- boot image via network using RARP/TFTP protocol
reset - Perform RESET of the CPU
run - run commands in an environment variable
setenv - set environment variables
sf - SPI flash sub-system
sleep - delay execution for some time
source - run script from memory
sspi - SPI utility commands
tftpboot- boot image via network using TFTP protocol
version - print monitor version
Programming QSPI FlashU-Boot provides the SF command to program serial flash devices. On all Xilinx platforms from u-boot, you can use SF command to program a QSPI device. Here is an example of loading an image file to QSPI device.
sf probe [[bus:]cs] [hz] [mode] - init flash device on given SPI bus and chip select
sf read addr offset len - read 'len' bytes starting at 'offset' to memory at 'addr'
sf write addr offset len - write 'len' bytes from memory at 'addr' to flash at 'offset'
sf erase offset [+]len - erase 'len' bytes from 'offset'; '+len' round up 'len' to block size
sf update addr offset len - erase and write 'len'bytes from memory at 'addr' to flash at 'offset
uboot> sf probe 0 0 0
SF: Detected N25Q128 with page size 256, total 16 MiB
16384 KiB N25Q128 at 0:0 is now current device
// Detect QSPI Flash parameters
// To make QSPI clock run faster, higher speed can be set to second parameter,
// e.g. setting QSPI clock to 20MHz
// sf probe 0 20000000 0
uboot> sf erase 0 0x200000
// Erase 2MB from QSPI offset 0x0
// Note: If erase size is less than QSPI Flash page size, u-boot reports erase error
uboot> sf read 0x08000000 0 100
// Read QSPI Flash from 0x0 to DDR 0x08000000 with 100 bytes
// you can use any location in DDR as destination. make sure it doesnt overwrite u-boot
// code/data area. u-boot is at 0x04000000.
uboot> md 08000000
08000000: ffffffff ffffffff ffffffff ffffffff ................
// Display content in memory 0x08000000.
// U-boot by default uses hex
// load the boot image to DDR
// load method can be KERMIT through UART, XMD dow -data through JTAG, TFTP through Ethernet
// or read from SD Card directly
zynq-boot> loadb 0x08000000
// load the boot image through KERMIT protocol after this step
// it is assumed that you should have a boot image generated using the bootgen utility
## Ready for binary (kermit) download to 0x08000000 at 115200 bps...
## Total Size = 0x0003e444 = 255044 Bytes
## Start Addr = 0x08000000
uboot> md 08000000 100
uboot> sf write 0x08000000 0 0x3E444
// Write from DDR address 0x08000000 to QSPI offset 0 with 0x3E444 bytes of data
// U-Boot read command can be used to see what is programmed in to QSPI memory.
// Following is the syntax of the "sf read" command.
zynq-boot> sf read <destination address in RAM> <source address in QSPI> <length of data to read>
NOTE: The "destination address" should not be ZERO.
uboot> sf read 0x800 0x0 0x2000
Programming NAND FlashU-Boot provides the nand command to program nand devices. Here is an example of loading an image file to nand device. The command sequence for nand is same as QSPI except the commands.Below nand command sequence for writing an image to nand device. The read command at the end just to ensure the data was written properly and you can use cmp command for comparing written data with original data which was lready present in DDR..
nand erase <start addr> <size>
// Download the image to a location DDR(DDR addr) using tftp and then perform write to nand from that DDR address as shown below.
nand write <DDR addr> <start addr> <size>
// The nand programming was done wuith the above command but to ensure that it has written successfully just read the written data using the below read command.
// Provide DDR addr different from the above and differ from the above DDR addr at least by the <size> so that we can compare both using cmp command and ensure it was written successfully.
nand read <DDR addr> <start addr>
Programming NOR Flash
U-Boot uses the regular memory command to program NOR devices. Here is command sequence of loading an image file to NOR device.
cp.b <DDR addr> <nor addr> <size>.
Authentication and Decryption in Zynq U-Boot
The authentication and decryption feature present in Zynq U-Boot can be found at page Authentication and Decryption in Zynq u-boot
Authentication and Decryption in ZynqMP U-Boot
The authentication and decryption feature present in ZynqMP U-Boot can found at Authentication and Decryption in Zynq US+ u-boot
Boot application images
U-Boot provides bootm command to boot application images (i.e. Linux) which expects those images be wrapper with a U-Boot specific header using mkimage. This command can be used either to boot legacy U-Boot images or new multi component images (FIT) as documented in U-Boot images wiki page. The standard Linux build process builds the wrapper uImage and Petalinux projects generates by default the multi component FIT image as well.
The following U-Boot commands illustrate loading a Linux image from a SD card using either individual images and a FIT image using the bootm command.
u-boot> fatload mmc 0 0x3000000 uImage
u-boot> fatload mmc 0 0x2A00000 devicetree.dtb
u-boot> fatload mmc 0 0x2000000 uramdisk.image.gz
u-boot> bootm 0x3000000 0x2000000 0x2A00000
u-boot> fatload mmc 0 0x1000000 image.ub
u-boot> bootm 0x1000000
With the bootm command, U-Boot is relocating the images before it boots Linux such that the addresses above may not be what the kernel sees. U-Boot also alters the device tree to tell the kernel where the ramdisk image is located in memory (initrd-start and initrd-end). The
bootm command sets the r2 register to the address of the device tree in memory which is not done by the go command.
The differences and use cases of using the
booti commands and the bootm command have evolved over time. As of U-Boot 2020.01, the primary difference is in handling of uncompressed Linux
Image files (common for 64-bit Arm platforms) versus compressed Linux
zImage files (common on 32-bit Arm platforms) as denoted in the U-Boot help. As a general rule of thumb, only differentiate in usage depending on Linux image type rather than solely based on architecture.
booti - boot Linux kernel 'Image' format from memory
bootm - boot application image from memory
The full help for
individually fully details the differences in usage.
booti [addr [initrd[:size]] [fdt]]
- boot Linux 'Image' stored at 'addr'
The argument 'initrd' is optional and specifies the address
of an initrd in memory. The optional parameter ':size' allows
specifying the size of a RAW initrd.
Since booting a Linux kernel requires a flat device-tree, a
third argument providing the address of the device-tree blob
is required. To boot a kernel with a device-tree blob but
without an initrd image, use a '-' for the initrd argument.
bootm [addr [arg ...]]
- boot application image stored in memory
passing arguments 'arg ...'; when booting a Linux kernel,
'arg' can be the address of an initrd image
When booting a Linux kernel which requires a flat device-tree
a third argument is required which is the address of the
device-tree blob. To boot that kernel without an initrd image,
use a '-' for the second argument. If you do not pass a third
a bd_info struct will be passed instead
For the new multi component uImage format (FIT) addresses
must be extended to include component or configuration unit name:
addr:<subimg_uname> - direct component image specification
addr#<conf_uname> - configuration specification
Use iminfo command to get the list of existing component
images and configurations.
Sub-commands to do part of the bootm sequence. The sub-commands must be
issued in the order below (it's ok to not issue all sub-commands):
start [addr [arg ...]]
loados - load OS image
ramdisk - relocate initrd, set env initrd_start/initrd_end
fdt - relocate flat device tree
cmdline - OS specific command line processing/setup
bdt - OS specific bd_t processing
prep - OS specific prep before relocation or go
go - start OS
Supported Drivers list for Zynq and Zynq Ultrascale
There are a number of drivers in the u-boot tree and they may work, but the following list of drivers are currently what's tested and users are encouraged to use these rather than others.
|Zynq||Zynq Ultrascale||Link||In Mainline||Location||Comment|
|Nand PS driver||Nand PS driver||nand driver||yes|
|QSPI driver||QSPI driver||qspi driver|
is not in mainline
|SD/MMC/eMMC driver||SD/MMC/eMMC driver||mmc driver||yes|
|PS GEM||PS GEM||ethernet driver||yes|
|USB2.0 host||USB2.0 host||usb driver||yes|
|USB2.0 device||USB2.0 device||usb driver|
|NOR flash||SATA||To be done|
Supported SoftIP drivers
Supported File systems
Below are the file systems supported in u-boot against flash devices for platform and Zynq UltraScale+. "Raw" in below table means that it supports raw read/write to respective flash devices without any need of file systems.
|Flash ||Zynq|| ZynqUS+|
|SD/eMMC||Raw, FAT, EXT2, EXT4||Raw, FAT, EXT2, EXT4|
|USB||FAT, EXT2, EXT4||FAT, EXT2, EXT4|
|SATA||----NA----||FAT, EXT2, EXT4|
|QSPI||Raw, UBIFS||Raw, UBIFS|
|Nand||Raw, UBIFS, JFFS2||Raw, UBIFS, JFFS2|
Please note that SD does not work in SD3.0 UHS modes by default. The dt parameter no-1-8-v has to be removed from corresponding sdhci node to work in UHS mode. Having no-1-8-v in sdhci node makes it to operate till SD High speed only, on Xilinx ZynqMP/Versal boards UHS mode will not work.
U-boot Release Notes