NVIDIA Tegra Tegra Linux Driver Package
Developers' Guide

June 11, 2012
R15 Release


U-Boot Guide
This document describes the U‑Boot implementation for NVIDIA® Tegra® Linux Driver Package. It covers the following topics:
Requirements
This topic provides software requirements and prerequisites, including Linux kernel options that are required for Tegra Linux Driver Package (L4T).
U‑Boot.
Functionality was validated using an Ubuntu 10.04 host system; however, later versions or alternative Linux distributions may work with host-specific modifications.
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:
http://developer.nvidia.com/linux-tegra
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 with the following command:
$ sudo apt-get install flex bison
You must either ensure that dtc is available to be passed in as a variable to the U‑Boot make system or make it available in the host machine’s local command path. 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 the Using Device Tree Compiler topic in this section.
The U‑Boot image tool must be installed on the host machine. This tool is what generates the vmlinux.uimg from the kernel zImage. If mkimage is not installed, it can be obtained by building the top-level U‑Boot make target. For more information on building U‑Boot, see Downloading and Building U‑Boot in this section. The mkimage tool can then be found in the U‑Boot source directory at:
./tools/mkimage
U‑Boot source.
For more information, see the Downloading and Building U-Boot topic in this section.
For information, see the following sections in the Getting Started chapter:
Also, see the Adding a Compiled Kernel to the Root File System topic in this section.
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: 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
Note: At time of publication, the tested commit ID for dtc is:
a6e6c60e3a97a6b3a033cd052bb3740fd53cbf4c
4.
$ 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.
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 release directory and skip Step 2 below.
When running source_sync.sh -u, if no parameters are provided, the script prompts for the <TAG_NAME>, which is provided in the release notes. Also, you can run the script by passing the <TAG_NAME> in as follows:
$ source_sync.sh –u <TAG_NAME>
This will sync the source to <source_sync.sh_location>/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.
$ export ARCH=arm
$ export CROSS_COMPILE=<toolchain>/…/bin/arm-none-linux-gnueabi-
$ export CONFIG_L4T=1
$ export USE_PRIVATE_LIBGCC=yes
$ export DTC=<dtc_binary_location>
4.
$ cd <uboot_src_dir>/u-boot
$ make distclean
$ make cardhu_config
$ make
5.
$ cp u-boot.bin <L4T_path>/Linux_for_Tegra/bootloader/<platform>
Note: Before copying U-Boot, it is recommended that you back up the u‑boot.bin file in this directory.
6.
If using network booting, perform the following steps.
Note: You can use any tftp daemon, but you must use the /tftpboot directory of the host machine specifically to perform the tftp boot.
$ sudo apt-get install tftpd
/etc/inetd.conf
Ensure it has following line:
tftp dgram udp wait nobody /usr/sbin/tcpd/usr/sbin/in.tftpd /tftpboot
$ cd /etc/init.d; ./openbsd-inetd restart
$ cp <L4T_path>/Linux_for_Tegra/bootloader/<platform> /tftpboot
Adding a Compiled Kernel to the Root File System
This topic describes the steps to create and install into the sample file system the kernel image that U‑Boot needs.
Prerequisites
To configure a file system for U-Boot
Use the zimage_to_uimg.sh script to create the vmlinux.uimg from your kernel zImage by executing the following commands:
$ cd <l4t path>/Linux_for_Tegra
$ ./zimage_to_uimg.sh –zImage <path>/zImage
With default values, zimage_to_uimg.sh writes vmlinux.uimg to the kernel directory of the extracted L4T release. Run zimage_to_uimg.sh –h for description of other parameters.
The zimage_to_uimg.sh script runs mkimage with the appropriate parameters to create the vmlinux.uimg file in the kernel directory. The apply_binaries script copies the vmlinux.uimg in the kernel directory into the rootfs directory in the /boot folder. You can then install the rootfs directory onto your device. For information on installing the rootfs directory onto your device, see Setting Up the Root File System in the Getting Started chapter.
If you have already installed your rootfs onto a device, you can manually copy the vmlinux.uimg file created by the zImage_to_uimg.sh script to the previously installed root file system.
To configure a network file system for U-Boot
For a network RootFS, use the --dest option to specify the path to the host machine’s nfs root directory with the “LDK_ROOTFS_DIR” variable. It will look as follows:
$ ./zImage_to_uimg.sh --zImage <path to zImage>/zImage --dest ${LDK_ROOTFS_DIR}/boot
Use the rootfs with the updated vmlinux.uimg file and configure NFS boot as described in the Configuring NFS Root on the Linux Host topic in the Getting Started chapter.
To configure a file system installed in the internal eMMC
1.
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: Optionally, rename existing release kernel to avoid overwriting it with the copy.
2.
Run the flash.sh script to install the rootfs directory onto internal eMMC.
Flashing U-Boot
This section presents the theory of usage for flashing U‑Boot followed by the commands used to flash. It contains the following topic:
eMMC Partition as Script Partition
Because you use the standard NvFlash Utility and the fastboot.bin flash application, U-Boot shares the same internal eMMC partition layout as fastboot does. The only difference is that L4T U-Boot does not use the kernel partition in the usual fashion: U‑Boot uses the kernel partition as its boot-script partition. Additionally, U‑Boot expects the kernel file named vmlinux.uimg in the following directory:
<rootfs>/boot
Fastboot Creation of GPT
Fastboot creates the GPT partition, which contains the secondary GUID Partition Table (GPT) that must be located in the last 512‑byte (B) sector of the boot device.
Note: The boot device is not necessarily the same as the rootfs device.
The logical block addressing (LBA) of the last-512‑B sector varies from device to device. Both U-Boot and the kernel know how to query the hardware to obtain the LBA of the last 512‑B sector.
Example eMMC Layout with Script Partition
This topic provides an example eMMC layout showing the script partition and configuration (CFG) file contents.
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=4194304
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
 
[partition]
name=PT
id=3
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=4
type=bootloader
allocation_policy=sequential
filesystem_type=basic
size=2097152
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
filename=fastboot.bin
 
[partition]
name=SOS
id=5
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=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=GP1
id=7
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=8
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=CAC
id=9
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=MSC
id=10
type=data
allocation_policy=sequential
filesystem_type=basic
size=2097152
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
 
[partition]
name=USP
id=11
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=12
type=data
allocation_policy=sequential
filesystem_type=basic
size=0xFFFFFFFFFFFFFFFF
file_system_attribute=0
partition_attribute=0
allocation_attribute=0x808
percent_reserved=0
 
[partition]
name=GPT
id=13
type=GPT
allocation_policy=sequential
filesystem_type=basic
size=0xFFFFFFFFFFFFFFFF
file_system_attribute=0
partition_attribute=0
allocation_attribute=8
percent_reserved=0
Flash Commands
This topic provides the commands to use to flash U‑Boot so that you can boot the device either from internal eMMC, from an SD Card, or from an IP network.
To flash U‑Boot to boot from internal eMMC
$ sudo ./flash.sh –L bootloader/<platform>/u-boot.bin <platform> mmcblk0p1
Where <platform> is the device, such as cardhu for Tegra 3 or ventana for Tegra 2.
To flash U‑Boot to boot from an SD Card
$ sudo ./flash.sh –L bootloader/<platform>/u-boot.bin <platform> mmcblk1p1
Where <platform> is the device, such as cardhu for Tegra 3 or ventana for Tegra 2.
To flash U‑Boot to boot from an IP network
$ sudo ./flash.sh –L bootloader/<platform>/u-boot.bin –N <IPA>:/<platform> [-n <target IPA>:<host IPA>:<gateway IPA>:<netmask>] <platform> eth0
Where <platform> is the device, such as cardhu for Tegra 3 or ventana for Tegra 2.
RootFS Tested By Device
This topic provides the results of testing the root file system location by device. The “Y” citations shown in the following table indicate that proper U-Boot initialization and hand-off to the kernel occurred, but this does not guarantee a fully-functional system.
Example Hush Boot Scripts
This section provides example boot scripts for eMMC, SD Card, USB, and Network booting.
To minimize the foot print of the binary, U-Boot is designed to be configured by compile‑time switches; however, in the Tegra Linux Driver (L4T) environment, it is desirable to have flash‑time switches available to accommodate various L4T use cases. Therefore, to support flash‑time switching, L4T implements a script partition concept, and the script partition can be edited and flashed to alter the U-Boot environment variables and boot parameters.
There are two example Hush Shell script files supplied in Tegra Driver for Linux release: <platform>_emmc.hush and <platform>_net.hush. Hush is a command line shell similar to Bourne Shell. L4T uses Hush as a Borne Shell-like U‑Boot command-line interpreter.
eMMC Hush Script
The eMMC Hush script handles booting with boot order from all local storage devices, such as internal eMMC, SD Card, and USB devices. This script checks the USB device first, the SD Card next, and then the internal eMMC memory. During these checks, if U‑Boot finds a valid vmlinux.uimg kernel image file, it boots off of the device where it found the kernel image.
The Hush script can be edited to set desired U‑Boot boot strapping characteristics. You can find the eMMC Hush script at the following location:
bootloader/<platform>/<platform>_emmc.hush
where <platform> is the device, such as cardhu for Tegra 3 or ventana for Tegra 2.
Example Script Contents
The following shows the contents of the eMMC Hush script.
#
# U-boot environment for local storage boot.
#
usbname=sda
pn=1
#
# Static env:
#
board=cardhu
mmcname=mmcblk
loadaddr=0x80408000
baudrate=115200
bootdelay=3
bootfile=vmlinux.uimg
console=ttyS0,115200n8
stderr=serial,lcd
stdin=serial,tegra-kbc
stdout=serial,lcd
user=user
videospec=tegrafb
serial#=1
#
# Board Specific variable env:
#
# tegra_fbmem: handled by u-boot runtime.
lp0_vec=0x00002000@0x9C406000
#
# Multi purpose env containers:
#
platform_extras=vmalloc=128M mem=1024M@2048M
extra_bootargs=usbcore.old_scheme_first=1 core_edp_mv=1300 panel=lvds tegraid=30.1.2.0.0 debug_uartport=lsport smp
#
# Local Storage Boot Scripts:
#
regen_all=setenv common_bootargs console=${console} console=tty1 lp0_vec=${lp0_vec} video=${videospec} ${platform_extras} ${dev_extras} noinitrd; setenv bootargs ${common_bootargs} ${extra_bootargs} ${bootdev_bootargs}
mmc_setup=setenv bootdev_bootargs root=/dev/${mmcname}${mmcdev}p${pn} rw rootwait gpt; run regen_all
mmc_boot=run mmc_setup; mmc rescan ${mmcdev}; ext2load mmc ${mmcdev}:${pn} ${loadaddr} /boot/${bootfile}; bootm ${loadaddr}
mmc0_boot=setenv mmcdev 0; run mmc_boot
mmc1_boot=setenv mmcdev 1; run mmc_boot
usb_setup=setenv bootdev_bootargs root=/dev/${usbname}${pn} rw rootwait; run regen_all
usb_boot=usb start; run usb_setup; ext2load usb 0:${pn} ${loadaddr} /boot/${bootfile}; bootm ${loadaddr}
bootcmd=run usb_boot; run mmc1_boot; run mmc0_boot
Net Hush Script
The Net Hush script handles booting from the Network File System (NFS). You can find the Net Hush script at the following location:
bootloader/<platform>/<platform>_net.hush
where <platform> is the device, such as cardhu for Tegra 3 or ventana for Tegra 2.
Example Script Contents
The following shows the contents of the Net Hush script.
#
# U-boot environment for network boot.
#
#
# Static env:
#
board=cardhu
mmcname=mmcblk
loadaddr=0x80408000
baudrate=115200
bootdelay=3
bootfile=vmlinux.uimg
console=ttyS0,115200n8
stderr=serial,lcd
stdin=serial,tegra-kbc
stdout=serial,lcd
user=user
videospec=tegrafb
serial#=1
#
# All CAP nfs info tokens need to be replaced with proper values as follow:
# IPADDR ----- 172.17.187.71
# SERVERIP --- 172.17.186.62
# GATEWAYIP -- 172.17.186.62
# NETMASK ---- 255.255.252.0
# NFSARGS ---- ip=:::::eth0:on or ip=cip:sip:gip:mask::eth0:off
# NFSROOT ---- 172.17.187.62:/cardhu_nfsroot
#
ipaddr=IPADDR
serverip=SERVERIP
gatewayip=GATEWAYIP
netmask=NETMASK
tftppath=TFTPPATH
nfsbootargs=root=/dev/nfs NFSARGS nfsroot=NFSROOT
#
# Board Specific variable env:
#
# tegra_fbmem: handled by u-boot runtime.
lp0_vec=0x00002000@0x9C406000
#
# Multi purpose env containers:
#
platform_extras=vmalloc=128M mem=1024M@2048M
extra_bootargs=usbcore.old_scheme_first=1 core_edp_mv=1300 panel=lvds tegraid=30.1.2.0.0 debug_uartport=lsport smp
#
# Local Storage Boot Scripts:
#
regen_all=setenv common_bootargs console=${console} console=tty1 lp0_vec=${lp0_vec} video=${videospec} ${platform_extras} ${dev_extras} noinitrd; setenv bootargs ${common_bootargs} ${extra_bootargs} ${bootdev_bootargs}
 
regen_net_bootargs=setenv bootdev_bootargs rw ${nfsbootargs} ; run regen_all
 
nfs_setup=setenv autoload n; run regen_net_bootargs
nfs_boot=run nfs_setup; dhcp; tftpboot ${loadaddr} ${tftppath}; bootm ${loadaddr}
 
bootcmd=usb start; run nfs_boot
Debugging U-Boot Environment
This section provides some debugging tips for your UBoot environment. The examples shown, however, 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, one common problem that can occur is when you create your own kernel and U‑Boot has trouble finding it. To verify that U‑Boot can read the device and also see 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 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, you can 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 3
Tegra3 # help
The below shows example Help information printed when executing help on a Tegra 3 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'
bootm - boot application image from memory
bootp - boot image via network using BOOTP/TFTP protocol
cls - clear screen
cmp - memory compare
coninfo - print console devices and information
cp - memory copy
crc32 - checksum calculation
dcache - enable or disable data cache
dhcp - boot image via network using DHCP/TFTP protocol
echo - echo args to console
editenv - edit environment variable
env - environment handling commands
exit - exit script
ext2load- load binary file from a Ext2 filesystem
ext2ls - 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 - GPIO access
help - print command description/usage
i2c - I2C sub-system
icache - enable or disable instruction cache
iminfo - print header information for application image
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)
nm - memory modify (constant address)
ping - send ICMP ECHO_REQUEST to network host
printenv- print environment variables
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
test - minimal test like /bin/sh
tftpboot- boot image via network using TFTP protocol
time - run a command and report its run time
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, you can list the directory structure of sda1 in U‑Boot by typing: usb 0:1 (for USB device 0 partition 1).
To list the directory structure
Tegra3 # ext2ls usb 0:1
Note: This works on EXT3 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:
Tegra3 # ext2ls usb 0:1 $DIRECTORY
where $DIRECTORY is an expected path on the device.
For example, to list contents of the /boot directory where the vmlinux.uimg file should be, execute:
Tegra3 # ext2ls usb 0:1 /boot
Printing the U-Boot Environment
You can print the entire U‑Boot environment.
To print the U-Boot environment
Execute the following command:
Tegra3 # printenv
Printing/Setting Environment Variables
You can print and set variables in the environment.
To print a variable in the environment
Tegra3 # printenv $ENV_VARIABLE
where $ENV_VARIABLE refers to an environment variable in U‑Boot.
For example, to print the boot device partition number, execute:
Tegra3 # printenv pn
Output can be as follows:
pn=1
To set a variable in the environment
Tegra3 # 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:
Tegra3 # setenv pn 1