U-Boot Guide
This document describes the U‑Boot implementation for NVIDIA® Tegra® Linux Driver Package.
Requirements
This topic provides software requirements and prerequisites, including Linux tools that are required for Tegra Linux Driver Package (L4T).
• Linux-based Host System.
Functionality of the u-boot build and flashing utilities was validated using an Ubuntu 12.04 host system; however, later versions or alternative Linux distributions may work with host-specific modifications.
• Tegra Linux Driver Package (L4T).
Download the latest L4T package from the Tegra Developer Zone and follow the installation instructions in the user documentation. You can find L4T on the Tegra Developer Zone:
• Flex and Bison.
The U‑Boot makefiles require flex and bison to parse various configuration files. If flex and bison are not already installed on your host machine, you can install them on an Ubuntu host machine with the following command:
$ sudo apt-get install flex bison
• Device Tree Compiler (dtc).
Ensure that the full path to the dtc binary is available to the U‑Boot make system by either passing the path as a variable or by making the dtc directory available in the local command path of the host machine. Most of the dtc packages available from standard Linux distribution package management systems (like
apt) are not yet updated with a version of dtc with the features required by the U‑Boot makefile. Therefore, an example of building dtc from source is included in this section. For the procedure, see
Using Device Tree Compiler.
A pre-built DTC compiler is also included in the kernel directory of the release. This DTC compiler is built from the kernel sources in this release. These sources are located in the scripts/dtc directory and built by building the kernel dtbs target.
• U-Boot Kernel Image Tool (mkimage).
The U‑Boot image tool is what generates the vmlinux.uimg from the kernel zImage. The L4T release includes a prebuilt 64-bit mkimage in <your_L4T_root>/Linux for Tegra/bootloader. If mkimage is not installed, it can be obtained by building the top-level U‑Boot make target on either a 64-bit or 32-bit host build system. For more information on building U‑Boot, see Downloading and Building U-Boot . The mkimage tool is in the U‑Boot source directory at:
./tools/mkimage
• ARM tool chain for cross compilation.
For more information, see the Toolchain section in this guide.
• U‑Boot source.
• Kernel source.
For information, see the following sections in the
Getting Started chapter:
• Setting Up Your Environment
• Synchronizing the Kernel Sources
• Building the NVIDIA Kernel
Using Device Tree Compiler
This topic provides an example of building the Device Tree Compiler (dtc) from source to include the features required by the U‑Boot makefile.
To build dtc from source
1. If you do not want to pass in dtc as a parameter to the U‑Boot environment, ensure a local command path (such as ./usr/local/bin or another choice) is at the beginning of the shell command path.
$ export PATH=<local_command_path>:${PATH}
Note: If you execute:
$ make install
The dtc makefile installs the binary into the first entry of shell PATH variable, so it is important that the local command path is at the beginning of the shell PATH variable.
2. Create a directory to contain the dtc source code and change directories into it:
$ mkdir -p <dtc_src_dir>
$ cd <dtc_src_dir>
3. Download dtc source code by executing the following git clone command:
$ git clone http://git.jdl.com/software/dtc.git
4. Build and optionally install dtc by executing:
$ cd <dtc_src_dir>/dtc
$ make
Or, alternatively, if you want it installed on your local host file system execute:
$ make install
Note: if you specified just make be sure to pass in the following to the U-Boot make system:
DTC=${PATH_TO_DTC_TOOL_BINARY}
Where PATH_TO_DTC_TOOL_BINARY is the location of the dtc binary, such as:
<dtc_src_dir>/dtc/dtc
Downloading and Building U-Boot
This topic provides the steps to follow when downloading and building U-Boot to use as a boot loader for the Tegra device.
Prerequisites
• Before copying U-Boot, back up the original u‑boot.bin file in :
<your_L4T_root>/Linux_for_Tegra/bootloader/<target_board>/u-boot.bin
To download and build U-Boot
1. Download the L4T U-Boot source code by executing the following commands:
$ mkdir -p <uboot_src_dir>
$ cd <uboot_src_dir>
$ git clone -n git://nv-tegra.nvidia.com/3rdparty/u-boot.git
Alternatively, you can use the source_sync.sh script that is provided in the L4T release and skip Step 2 below.
When running source_sync.sh -u you are prompted to enter the <TAG_NAME>, which is provided in the release notes.
$ cd <your_L4T_root>/Linux_for_Tegra
$ ./source_sync.sh -u
This will sync the source to <source_sync.sh_location>/sources/u-boot_source. The <uboot_src_dir> directory becomes <your_L4T_root>/Linux_for_Tegra/sources/u-boot_source. Use that path below in Step 4.
2. Check out the git tag name:
$ cd u-boot
$ git checkout -b mybranchname <tag_name>
where <tag_name> is provided in the Release Notes.
3. Set the build environment:
$ export ARCH=arm
$ export CROSS_COMPILE=<your_toolchain_location>
$ export CONFIG_L4T=1
$ export USE_PRIVATE_LIBGCC=yes
$ export DTC=<dtc_binary_location>
4. Build U-Boot by executing:
$ cd <uboot_src_dir>/u-boot
$ make distclean
$ make <target_board>_config
$ make
Where <target_board> is the device, such as code-name ardbeg for Jetson TK1.
5. Copy U-Boot for flashing to the device:
$ cp u-boot-dtb-tegra.bin <your_L4T_root>/Linux_for_Tegra/bootloader/<target_board>/u-boot.bin
Adding a Compiled Kernel to the Root File System
This topic describes the steps to create and install the kernel image required by U-Boot into the sample file system.
Prerequisites
• You have compiled the kernel as described in Getting Started in this guide.
To configure a file system for U-Boot
1. Use the apply_binaries script to copy the zImage in the kernel directory into the rootfs directory in the /boot folder.
2. Install the rootfs directory onto your device.
For U-Boot to function properly, there must be a zImage kernel image in the /boot directory of the target filesystem.
For information on installing the rootfs directory onto your device, see Setting Up the Root File System in the Getting Started chapter.
3. If you have already installed your rootfs onto a device, manually copy the zImage file to the previously installed root file system.
To configure a file system installed in the internal eMMC
1. Optionally, backup the existing release kernel to avoid overwriting it with a new kernel copy.
2. Copy the compiled zImage kernel over the current L4T release kernel by executing the following command:
$ cp arch/arm/boot/zImage <L4T_path>/Linux_for_Tegra/kernel
Note: flash.sh automatically copies the zImage to the internal eMMC rootfs.
Flashing U-Boot
This section presents the theory of usage for flashing U‑Boot followed by the commands used to flash.
eMMC Partition as Script Partition
With the standard NvFlash Utility and the fastboot.bin flash application, U-Boot shares the same internal eMMC partition layout as fastboot. The only difference is that L4T U-Boot does not use the kernel partition.
Additionally, U‑Boot expects the following kernel files
• zImage
• device_tree_blob.dtb
• sysboot_config
These files must be located in the following directory:
<rootfs>/boot
Flash.sh Creation of GPT
The flash.sh script creates the primary and secondary GPT partitions. The Protective MBR contains device information for traditional boot loaders not to perform destructive activities. The primary GPT partition contains the GUID Partition Table and the secondary GPT partition contains the same information as the primary GPT and is used as the backup. The Protective MBR is located at LBA 0, the primary GPT is located at LBA 1, and the secondary GPT is located at the last LBA of the boot device.
Note: The boot device is not necessarily the same as the rootfs device.
The last Logical Block Address (LBA) varies from device to device. Both U-Boot and the kernel are able to obtain the last LBA.
Example eMMC Layout with Script Partition
This topic provides an example eMMC layout showing the script partition and configuration (CFG) file contents. For the actual configuration used in the release, see the gnu_linux_fastboot_emmc_full.cfg file.
U-Boot shares the same layout as fastboot; the layout is described in the following released configuration file:
gnu_linux_fastboot_emmc_full.cfg
The kernel partition (name=LNX) gets used as the script partition.
Example CFG Contents
[device]
type=sdmmc
instance=3
[partition]
name=BCT
id=2
type=boot_config_table
allocation_policy=sequential
filesystem_type=basic
size=2097152 #BCTSIZE
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=PPT
id=3
type=data
allocation_policy=sequential
filesystem_type=basic
size=8388608 #PPTSIZE
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
#filename=ppt.img
[partition]
name=PT
id=4
type=partition_table
allocation_policy=sequential
filesystem_type=basic
size=2097152
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=EBT
id=5
type=bootloader
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
filename=fastboot.bin
[partition]
name=LNX
id=6
type=data
allocation_policy=sequential
filesystem_type=basic
size=8388608
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
filename=boot.img
[partition]
name=SOS
id=7
type=data
allocation_policy=sequential
filesystem_type=basic
size=6291456
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
#filename=recovery.img
[partition]
name=GP1
id=8
type=GP1
allocation_policy=sequential
filesystem_type=basic
size=2097152
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=APP
id=9
type=data
allocation_policy=sequential
filesystem_type=basic
size=1073741824
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
filename=system.img
[partition]
name=DTB
id=10
type=data
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
#filename=tegra.dtb
[partition]
name=EFI
id=11
type=data
allocation_policy=sequential
filesystem_type=basic
size=67108864 #EFISIZE
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
#filename=efi.img
[partition]
name=USP
id=12
type=data
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=TP1
id=13
type=data
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=TP2
id=14
type=data
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=TP3
id=15
type=data
allocation_policy=sequential
filesystem_type=basic
size=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
[partition]
name=UDA
id=16
type=data
allocation_policy=sequential
filesystem_type=basic
size=2097152
file_system_attribute=0
partition_attribute=0
allocation_attribute=0x808
percent_reserved=0
[partition]
name=GPT
id=17
type=GPT
allocation_policy=sequential
filesystem_type=basic
size=0xFFFFFFFFFFFFFFFF
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
#filename=spt.img
Flash Commands
This topic provides the commands to use to flash U‑Boot to boot the device from internal eMMC, from an SD Card, from a USB pen drive, or from an IP network.
To flash U‑Boot to boot from internal eMMC
• Execute the following command:
$ sudo ./flash.sh -L bootloader/<target_board>/u-boot.bin <target_board> mmcblk0p1
Where <target_board> is the device, such as ardbeg for Jetson TK1.
To flash U‑Boot to boot from an SD Card
• Execute the following command:
$ sudo ./flash.sh -L bootloader/<target_board>/u-boot.bin <target_board> mmcblk1p1
Where <target_board> is the device, such as ardbeg for Jetson TK1.
To flash U‑Boot to boot from a USB Pen Drive
• Execute the following command:
$ sudo ./flash.sh -L bootloader/<target_board>/u-boot.bin <target_board> sda1
Where <target_board> is the device, such as ardbeg for Jetson TK1.
To flash U‑Boot to boot from an IP network
• Execute the following command:
$ sudo ./flash.sh -L bootloader/<target_board>/u-boot.bin -N <IPA>:/<target_board> [-n <target IPA>:<host IPA>:<gateway IPA>:<netmask>] <target_board> eth0
Where <target_board> is the device, such as ardbeg for Jetson TK1.
RootFS Tested By Device
This topic provides the results of testing the root file system location by device. The “Y” citations indicate that proper U-Boot initialization and hand-off to the kernel occurred. However, this does not guarantee a fully-functional system.
RootFS Location | Jetson TK1 |
mmcblk0p1 | Y |
mmcblk1p1 | Y |
sda1 | Y |
eth0 | Y |
Example Sysboot Config Files
This section outlines the U-boot scanning sequence and the associated configuration files.
U-Boot functionality includes a default booting scan sequence. It scans bootable devices such as: internal eMMC, external SD card, USB and NFS looking for an extlinux.conf configuration file. The file file must be located in the following directory of the bootable device:
<rootfs>/boot
If U-Boot finds the extlinux.conf file, it:
• Uses the sysboot command to read out boot configurations from extlinux.conf.
• Loads kernel zImage file and device tree file.
• Boots the kernel.
Since kernel extlinux.conf, zImage, and the device tree files are all in a user accessible location after booting:
<rootfs>/boot
Users can easily change these files to test their own kernel without flashing.
• extlinux.conf contains all the information about booting. It is in a standard and pure text format sysboot configuration file. It tells the U-Boot kernel the image filename, the device tree blob filename, and the kernel boot command line. There are four example extlinux.conf files provided in Tegra Driver for Linux release:
<target_board>_extlinux.conf.emmc
<target_board>_extlinux.conf.sdcard
<target_board>_extlinux.conf.usb <target_board>_extlinux.conf.nfs
During flashing, flash.sh copies one of them to:
<rootfs>/boot/extlinux.conf
These extlinux.conf files are very similar, except they have different kernel boot command lines. The extlinux.conf files are at:
bootloader/<target_board>/
Where <target_board> is ardbeg for Jetson TK1.
eMMC Sysboot extlinux.conf File
The following shows the contents of the extlinux.conf file.
TIMEOUT 30
DEFAULT primary
MENU TITLE Jetson-TK1 eMMC boot option
LABEL primary
MENU LABEL primary kernel
LINUX zImage
FDT tegra124-pm375.dtb
APPEND console=ttyS0,115200n8 console=tty1 no_console_suspend=1
lp0_vec=2064@0xf46ff000 video=tegrafb mem=1862M@2048M memtype=255
ddr_die=2048M@2048M section=256M pmuboard=0x0177:0x0000:0x02:0x43:0x00
vpr=151M@3945M tsec=32M@3913M otf_key=c75e5bb91eb3bd947560357b64422f85
usbcore.old_scheme_first=1 core_edp_mv=1150 core_edp_ma=4000
tegraid=40.1.1.0.0 debug_uartport=lsport,3 power_supply=Adapter
audio_codec=rt5640 modem_id=0 android.kerneltype=normal
usb_port_owner_info=0 fbcon=map:1 commchip_id=0 usb_port_owner_info=0
lane_owner_info=6 emc_max_dvfs=0 touch_id=0@0
tegra_fbmem=32899072@0xad012000
board_info=0x0177:0x0000:0x02:0x43:0x00 root=/dev/mmcblk0p1 rw
rootwait tegraboot=sdmmc gpt
Different boot methods have different APPEND strings in the extlinux.conf file. Check each file for details.
Note: NFS booting also uses eMMC as boot device. <rootfs>/boot is flashed into to eMMC but kernel mounts NFS device as rootfs.
Debugging U-Boot Environment
This section provides debugging tips for your U‑Boot environment. The examples do not represent a comprehensive listing for U‑Boot functionality. For a full listing of supported commands and their usage by U‑Boot, see the U‑Boot documentation and source.
For example, a common problem occurs when you create your own kernel and U‑Boot has trouble finding it. To verify that U‑Boot can read the device and sees the files in the file system, the commands listed in examples in this section may be beneficial. If a boot device is not found, or the device has trouble booting with a kernel other than the reference kernel provided in the L4T release, check the examples in this section for debug assistance.
Interrupting U-Boot
You can interrupt U-Boot during boot.
To interrupt U-Boot
• Press any key during boot.
Getting Help
On the U‑Boot terminal screen, type help at any time for the list of supported commands from the U‑Boot terminal.
To see the U-Boot Help screen on Tegra 4
• Enter:
Tegra124 (Jetson TK1) # help
The below shows example Help information printed when executing help on a Tegra 124 device.
? - 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'
bootelf - Boot from an ELF image in memory
bootm - boot application image from memory
bootp - boot image via network using BOOTP/TFTP protocol
bootvx - Boot vxWorks from an ELF image
bootz - boot Linux zImage image from memory
cmp - memory compare
coninfo - print console devices and information
cp - memory copy
crc32 - checksum calculation
dhcp - boot image via network using DHCP/TFTP protocol
echo - echo args to console
editenv - edit environment variable
enterrcm- reset Tegra and enter USB Recovery Mode
env - environment handling commands
exit - exit script
ext2load- load binary file from a Ext2 filesystem
ext2ls - list files in a directory (default /)
ext4load- load binary file from a Ext4 filesystem
ext4ls - list files in a directory (default /)
false - do nothing, unsuccessfully
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
go - start application at address 'addr'
gpio - query and control gpio pins
help - print command description/usage
i2c - I2C sub-system
imxtract- extract a part of a multi-image
itest - return true/false on integer compare
load - load binary file from a filesystem
loadb - load binary file over serial line (kermit mode)
loads - load S-Record file over serial line
loadx - load binary file over serial line (xmodem mode)
loady - load binary file over serial line (ymodem mode)
loop - infinite loop on address range
ls - list files in a directory (default /)
md - memory display
mii - MII utility commands
mm - memory modify (auto-incrementing address)
mmc - MMC sub system
mmcinfo - display MMC info
mw - memory write (fill)
nm - memory modify (constant address)
part - disk partition related commands
ping - send ICMP ECHO_REQUEST to network host
printenv- print environment variables
pxe - commands to get and boot from pxe files
reset - Perform RESET of the CPU
run - run commands in an environment variable
saveenv - save environment variables to persistent storage
setenv - set environment variables
sf - SPI flash sub-system
showvar - print local hushshell variables
sleep - delay execution for some time
source - run script from memory
sspi - SPI utility command
sysboot - command to get and boot from syslinux files
test - minimal test like /bin/sh
tftpboot- boot image via network using TFTP protocol
true - do nothing, successfully
usb - USB sub-system
usbboot - boot from USB device
version - print monitor, compiler and linker version
Listing a Directory Structure
You can list the directory structure of a particular device. For example, to list the directory structure of sda1 in U‑Boot by type: mmc 0:1 (for eMMC device 0 partition 1).
To list the directory structure
• Execute the following command:
Tegra124 (Jetson TK1) # ext2ls mmc 0:1
Note: This works on EXT3/EXT4 file systems, as well.
Example output follows:
<DIR> 4096 .
<DIR> 4096 ..
<DIR> 4096 bin
<DIR> 4096 boot
<DIR> 4096 dev
<DIR> 4096 etc
<DIR> 4096 home
<DIR> 4096 lib
<DIR> 4096 lost+found
<DIR> 4096 media
<DIR> 4096 mnt
<DIR> 4096 opt
<DIR> 4096 proc
<DIR> 4096 root
<DIR> 4096 sbin
<DIR> 4096 selinux
<DIR> 4096 srv
<DIR> 4096 sys
<DIR> 4096 tmp
<DIR> 4096 usr
<DIR> 4096 var
Listing the Contents of a Directory
You can list the contents of any directory.
To list contents of a directory
• Execute following command:
Tegra124 (Jetson TK1) # ext2ls mmc 0:1 $DIRECTORY
where $DIRECTORY is an expected path on the device.
For example, to list contents of the /boot directory where the zImage file should be, execute:
Tegra124 (Jetson TK1) # ext2ls mmc 0:1 /boot
<DIR> 1024 .
<DIR> 1024 ..
34642 tegra124-pm375.dtb
908 extlinux.conf
5910248 zImage
Printing the U-Boot Environment
You can print the entire U‑Boot environment.
To print the U-Boot environment
• Execute the following command:
Tegra124 (Jetson TK1) # printenv
Printing/Setting Environment Variables
You can print and set variables in the environment.
To print a variable in the environment
• Execute the following command:
Tegra124 (Jetson TK1) # printenv $ENV_VARIABLE
where $ENV_VARIABLE refers to an environment variable in U‑Boot.
For example, to print the boot device partition number, execute:
Tegra124 (Jetson TK1) # printenv pn
Output can be as follows:
pn=1
To set a variable in the environment
• Execute the following command:
Tegra124 (Jetson TK1) # setenv $ENV_VARIABLE $NEW_VALUE
where $ENV_VARIABLE refers to an environment variable in U‑Boot and $NEW_VALUE is the new value for that variable.
For example, to set the partition number variable, enter the following command:
Tegra124 (Jetson TK1) # setenv pn 1
To save the modified environment
• Execute the following command:
Tegra124 (Jetson TK1) # saveenv
The saved modified environment is preserved in case of resets and reboots.
