V2020.01 U-boot Sections

U-Boot

U-Boot is a bootloader and comes preinstalled on this board. U-Boot resides in the eMMC hardware boot partition /dev/mmcblk0boot0. U-Boot sets up the hardware and then loads the OS from the available storage devices. It can boot images from microSD, eMMC, NFS, or USB. Users without a need to customize U-Boot behavior can proceed to the #Debian sections for information on application development.

Entering U-Boot shell

The U-Boot shell provides the ability to run commands directly on the console, and includes commands for modification and saving of the environment (discussed further below).

By default, there is only one way to enter the shell: Pressing the esc key twice within a 1-second window immediately at power-on/reset will bring you to the U-Boot shell prompt. This behavior can be modified by setting the U-Boot environment variable bootdelay. If modified (and saved), it will force the timeout for pressing the esc key to be however many seconds the variable is set to. If it is set to 0, then the esc prompt is skipped, and if set to -1, the sequence will always stop in U-Boot.

Note:

Use caution when setting bootdelay! A value of 0 means it is no longer possible to enter the U-Boot shell. We do not recommend using bootdelay in this manner, as we do not support it. Be sure to read the U-Boot Documentation for further details U-Boot Documentation.

When stopped in U-Boot, booting can be resumed by simply typing boot or run bootcmd.

U-Boot Distro Boot

U-Boot is compiled with support for its distro bootcmd scheme to determine how to boot an operating system.

As shipped, and in the absence of removable boot media, the board will boot to our Debian image that is preprogrammed into eMMC.

As configured in the default environment, distro boot looks at:

Order	U-Boot device name	Description
1	usb0	First detected USB mass storage device
2	mmc1	MicroSD card
3	mmc0	Onboard eMMC storage
4	dhcp	DHCP Option
5	pxe	PXE File

The default boot order is one that requires no modification to succeed from any supported media. However, boot times can be improved and devices made less susceptible to unintended behavior by stopping at U-Boot and running:

# Boot straight to eMMC:
env set boot_targets 'mmc0';
env save

# Boot to usb, then mmc only
env set boot_targets 'usb0 mmc0';
env save

# Set back to default boot order
env set boot_targets 'usb0 mmc1 mmc0 dhcp pxe'
env save

U-Boot will search MBR-formatted boot media on the 1st partition, or if the media is partitioned with GPT instead, it will search the "bootable" partition. When a boot partition is found, it will then search for these files:

Order	Search for	Paths	Description
1	extlinux	/extlinux/extlinux.conf, /boot/extlinux/extlinux.conf	Menu conf file of kernels
2	U-Boot script	/boot.scr.uimg, /boot.scr, /boot/boot.scr.uimg, /boot/boot.scr	U-Boot script with instructions to load the OS
3	EFI Binary	efi/boot/bootarm.efi	EFI binary (such as grub)

Our Debian images boot via a U-Boot script in /boot/boot.scr.uimg.

U-Boot Environment

The V2020.01 U-boot Sections stores its U-Boot environment in the /dev/mmcblk0boot0 partition of its on-board eMMC flash.

# Print all environment variables
env print -a

# Sets the variable bootdelay to 5 seconds
env set bootdelay 5

# Variables can also contain commands
env set hellocmd 'led 0 off; echo Hello world; led 1 on;'

# Execute commands saved in a variable
env run hellocmd

# Commit env changes to the spi flash
# Otherwise changes are lost
env save

# Restore env to default
env default -a

# Remove a variable
env delete hellocmd

U-Boot Commands

# The most important command is 
help
# This can also be used to see more information on a specific command
help i2c

# Boot a Linux zImage loaded at $loadaddr
bootz
# Boot in to a Linux zImage at $loadaddr, skip initrd, specifies
# the FDT address to Linux knows where to find the device tree
bootz ${loadaddr} - ${fdtaddr}

# Get a DHCP address
dhcp
# This sets ${ipaddr}, ${dnsip}, ${gatewayip}, ${netmask}
# and ${ip_dyn} which can be used to check if the dhcp was successful

# These commands are used for scripting:
false # do nothing, unsuccessfully
true # do nothing, successfully

# This command can set fuses in the processor
# Setting fuses can brick the unit, will void the warranty,
# and should not be done in most cases
fuse

# GPIO can be manipulated from U-Boot.  Keep in mind that the IOMUX 
# in U-Boot is only setup enough to boot the device, so not all pins will
# be set to GPIO mode out of the box.  Boot to the full operating system
# for more GPIO support.
# GPIO are specified in bank and IO in this manual.  U-Boot uses a flat numberspace,
# so for bank 2 DIO 25, this would be number (32*1)+25=89
# The formula thus being (32*(bank-1)+dio)=flattened_dio
# Note that on some products, bank 1 is the first bank
# Set 2_25 low
gpio clear 83
# Set 2_25 high
gpio set 83
# Read 2_25
gpio input 83

# This command is used to copy a file from most devices
# Load kernel from SD
load mmc 0:1 ${loadaddr} /boot/zImage
# Load Kernel from eMMC
load mmc 1:1 ${loadaddr} /boot/zImage
# Load kernel from USB
usb start
load usb 0:1 ${loadaddr} /boot/zImage

# View an FDT on a boot image using U-Boot
load mmc 1:1 ${fdtaddr} /boot/imx6ul-ts${model}.dtb
fdt addr ${fdtaddr}
fdt print

# It is possible to blindly jump to any memory location
# This is similar to bootm, but it does not require
# the use of the U-Boot header
load mmc 0:1 ${loadaddr} /boot/custombinary
go ${loadaddr}

# Browse fat, ext2, ext3, or ext4 filesystems on an SD card:
ls mmc 0:1 /

# Test memory.
mtest

# Check for new SD card
mmc rescan
# Read SD card size
mmc dev 0
mmcinfo
# Read eMMC Size
mmc dev 1
mmcinfo

# The NFS command is like 'load', but used over the network
dhcp
env set serverip 192.168.0.11
nfs ${loadaddr} 192.168.0.11:/path/to/somefile

# Test ICMP
dhcp
ping 192.168.0.11

# Reboot
reset

# SPI access is through the SF command
# Be careful with sf commands since
# this is where U-Boot and the FPGA bitstream exist
# Improper use can render the board unbootable
sf probe

# Delay in seconds
sleep 10

# Load HUSH scripts that have been created with mkimage
load mmc 0:1 ${loadaddr} /boot/boot.scr
source ${loadaddr}

# Most commands have return values that can be used to test
# success, and HUSH scripting supports comparisons like
# test in Bash, but much more minimal
if load mmc 1:1 ${fdtaddr} /boot/zImage;
	then echo Loaded Kernel
else
	echo Could not find kernel
fi

# Print U-Boot version/build information
version

Booting From NFS

Note:

The following instructions assume the NFS server is running Debian.

U-Boot's NFS support can be used to load a kernel, device tree binary, and root filesystem. The default scripts include an example NFS boot script. Because of the way U-Boot tries to infer server data, the script we use will bypass this, making it more straightforward to use an NFS root that will not be heavily dependent on a particular network configuration.

First, on the NFS server side, be sure to verify and if needed modify /etc/default/nfs-kernel-server such that the server is running NFS -V 2. The nfs-kernel-server file should resemble the following:

# Number of servers to start up
RPCNFSDCOUNT="8 --no-nfs-version 4 -V 2"

# Runtime priority of server (see nice(1))
RPCNFSDPRIORITY=0

# Options for rpc.mountd.
# If you have a port-based firewall, you might want to set up
# a fixed port here using the --port option. For more information, 
# see rpc.mountd(8) or http://wiki.debian.org/SecuringNFS
# To disable NFSv4 on the server, specify '--no-nfs-version 4' here
RPCMOUNTDOPTS="--manage-gids --no-nfs-version 4"

# Do you want to start the svcgssd daemon? It is only required for Kerberos
# exports. Valid alternatives are "yes" and "no"; the default is "no".
NEED_SVCGSSD=""

# Options for rpc.svcgssd.
RPCSVCGSSDOPTS=""

Once verified that the file /etc/default/nfs-kernel-server looks like the above, then from the U-Boot shell run the following commands:

# Set this to your NFS root path
env set nfsroot <IP ADDRESS>:/path/to/nfs/rootfs/
env save

To boot to NFS root once the server details are set:

# Boot to NFS once
run nfsboot;

# To make the NFS boot the persistent default
env set bootcmd run nfsboot;
env save

Note:

You must have NFS version 2 on your server, as it is disabled by default on new distributions. Be sure to read the U-Boot Documentation for further details U-Boot Documentation

.

U-Boot Development

Note:

This section is incomplete at this time and is subject to change without warning while the V2020.01 U-boot Sections is in its Engineering Sampling phase.

We do provide our U-Boot sources, but we do not recommend rebuilding a custom U-Boot binary, as it can leave the system in an unbootable state.

If proceeding with building a custom U-Boot, use the "v2020.01-ts" branch from our github repo: https://github.com/embeddedTS/u-boot-imx this can be executed with the following command:

git clone https://github.com/embeddedTS/u-boot-imx.git -b v2020.01-ts u-boot-ts7250v3

When compiling, we recommend using ONLY this cross-compiler, the use of any other compiler may cause issues or may leave the system in an unbootable state! Specifically, we have experienced RAM problems when using a more recent cross compiler to build this version of U-Boot. The tarball can be extracted with the following:

mkdir /opt/toolchains/ts7250v3/
tar -xf tsimx6ul-glibc-gnueabihf-4.9.4.tar.xz -C /opt/toolchains/ts7250v3/

Once the tarball has been properly extracted set up the following variables and run the build script:

export ARCH=arm
export CROSS_COMPILE=/path/to/folder/bin/arm-linux-gnueabihf-

After the environment variables have been set up as shown above the build is now ready to be executed:

cd /path/to/u-boot-imx
./build-imx6ul.sh ts7250v3