TS-7680 U-boot Sections

U-Boot is used on this device as the bootloader to launch the full operating system. When the i.MX28 processor starts, it loads U-Boot from the on-board SPI flash. This allows creation of a custom boot image on either the SD, eMMC, NFS, or USB. U-Boot is a general purpose bootloader that is capable of booting into common Linux distributions, Android, Windows, or custom software OSes.

On a normal boot the output will be similar to this:

HTLLCLLC

U-Boot 2014.10-g4d36657 (Dec 07 2016 - 12:19:27)

CPU:   Freescale i.MX28 rev1.2 at 454 MHz
BOOT:  SSP SPI #2, master, 3V3 NOR
I2C:   ready
SPI:   ready
DRAM:  256 MiB
MMC:   MXS MMC: 0, MXS MMC: 1
SF: Detected IS25LQ016B with page size 256 Bytes, erase size 4 KiB, total 2 MiB

In:    serial
Out:   serial
Err:   serial
Net:   FEC0 [PRIME]
NO CHRG jumper is set, not waiting for SuperCaps to charge
Booting from the SD Card ...
** File not found /boot/boot.ub **
3336928 bytes read in 1245 ms (2.6 MiB/s)
20378 bytes read in 265 ms (74.2 KiB/s)
## Booting kernel from Legacy Image at 42000000 ...
   Image Name:   Linux-3.14.28-g1a4251b
   Image Type:   ARM Linux Kernel Image (uncompressed)
   Data Size:    3336864 Bytes = 3.2 MiB
   Load Address: 40008000
   Entry Point:  40008000
   Verifying Checksum ... OK
## Flattened Device Tree blob at 41000000
   Booting using the fdt blob at 0x41000000
   Loading Kernel Image ... OK
   Loading Device Tree to 4fb4b000, end 4fb52f99 ... OK

Starting kernel ...

U-Boot Environment

On the SPI flash U-boot has both the U-boot application and the U-boot environment. Our default build has 8KB of environment which can be used for variables and scripts to control booting your operating system. These commands are relevant to manipulating the environment:

# 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 red on; echo Hello world; led green 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 emmcboot

For a production environment the best option for setting depends on the number of units. For a smaller number of units it may be simplest to update any required commands manually. For example, a custom cmdline option like "debug":

env set cmdline_append rw rootwait console=ttyAMA0,115200 loglevel=3 debug
env save

U-Boot Commands

These commands are agnostic to the operating system that is running, but may be useful for testing or scripting:

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

# Boots into the binary at $loadaddr.  This file needs to have
# the uboot header from mkimage.  A uImage already contains this.
bootm
# Boots into the binary at $loadaddr, skips the initrd, specifies
# the fdtaddr so Linux knows where to find the board support
bootm ${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 mainly used for scripting:
false # do nothing, unsuccessfully
true # do nothing, successfully

# Control LEDs
led red on
led green on
led all off
led red toggle

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

# View the fdt from u-boot with fdt
load mmc 0:2 ${fdtaddr} /boot/imx28-ts7680.dtb
fdt addr ${fdtaddr}
fdt print

# Blindly jump into any memory location
# This is similar to bootm, but it does not use the 
# u-boot header
load mmc 0:2 ${loadaddr} /boot/custombinary
go ${loadaddr}

# Browse fat,ext2,ext3,or ext4 filesystems:
ls mmc 0:2 /

# Similar to devmem in Linux, read/write arbitrary memory
# using mw and md
# write
mw 0x10000000 0xc0ffee00 1
# read
md 0x10000000 1

# Test memory.  Typically just used in production
mtest

# Read newly inserted SD card
mmc rescan
# Read SD card size
mmc dev 0
mmcinfo

# The NFS command is similar to '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

# It is possible to load HUSH scripts that have been created with mkimage
load mmc 0:2 ${loadaddr} /boot/ubootscript
source ${loadaddr}

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

# Commands can be timed with "time" similar to Linux
time sf probe

# Print U-boot version/build information
version

Modify Linux Kernel cmdline

The Linux kernel cmdline can be customized by modifying the cmdline_append variable. Keeping the default options here is recommended, but additional arguments can be appended to this variable.

env set cmdline_append rw rootwait console=ttyAMA0,115200 loglevel=3
env save

You can also change the kernel command line from the onboard Linux. From the board's shell prompt run:

apt-get update && apt-get install u-boot-tools -y
echo "env set cmdline_append rw rootwait console=ttyAMA0,115200 quiet" > /boot/boot.scr
mkimage -A arm -T script -C none -n 'tsimx28 boot script' -d /boot/boot.scr /boot/boot.ub

The boot.scr includes the plaintext commands to be run in u-boot on startup, and mkimage adds a checksum and header to this file which can be loaded by u-boot. The ub file should not be manually modified.

Linux NFS Boot

U-boot includes support for NFS which can be used to load your kernel, device tree binary, and root filesystem. Our default environment contains the nfsboot command which can be updated to boot NFS on your network:

# Set this to your NFS server ip
env set nfsip 192.168.0.11;

# Set this to your NFS root path.  The server root should be accessible at this path.
env set nfsroot /nfsroot/rootfs/
env save

To boot your NFS root:

# Boot to NFS once
run nfsboot;

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

Linux USB Boot

By default, U-Boot will attempt to read a U-Boot script from a USB drive when the U-Boot jumper is set. It copies /tsinit.ub into memory and jumps in to the script. To make a bootable drive, create a single ext3 partition on a USB drive and unpack the rootfs tarball located here

The one addition is to create the tsinit.ub file in the root of the USB drive. In order to do this, a U-Boot script must be created and then converted to the .ub format. This process requires a set of U-Boot specific tools. These are available on most every linux distribution, the instructions below are for Debian, either run on a host PC or on the target. See the package installation documentation for other respective distributions.

Install U-Boot tools in Debian

apt-get update && apt-get install u-boot-tools -y

Create the file tsinit.scr in the root of the USB drive with the linux filesystem:

# Prepare with:
# mkimage -A arm -T script -C none -n 'imx28 usb' -d tsinit.scr tsinit.ub

# DO NOT MANUALLY EDIT THE .UB FILE

if load usb 0:1 ${loadaddr} /boot/ts${model}-fpga.vme;
        then fpga load 0 ${loadaddr} ${filesize};
fi;

load usb 0:1 ${fdtaddr} /boot/imx28-ts${model}.dtb;

load usb 0:1 ${loadaddr} /boot/uImage;

setenv bootargs root=/dev/sda1 ${cmdline_append};
bootm ${loadaddr} - ${fdtaddr};

Then in the same directory generate the tsinit.ub file:

mkimage -A arm -T script -C none -n 'imx28 usb' -d tsinit.scr tsinit.ub

You may need to install u-boot-tools or the equivalent package for your distribution.

U-Boot Recovery

The development tool, TS-9468, can be used to recover the SBC. Set the flip switch in the "Up" position so it lights up red when powered on to boot from the SPI flash on the TS-9468; the TS-9468 may not ship with a switch, without the switch populated the TS-9468 will automatically boot to the SPI flash on the TS-9468. Use the instructions in Update U-Boot to download and copy in the latest U-Boot binary to SD and boot the unit. And instead of the command listed, use the following:

env set spi onboard
run update-uboot

The script output will include a message saying that it is writing to the onboard SPI flash. The environment variable "spi" can be set to "offboard" in order to force writing to the TS-9468 in order to update the binary on there. Note that if the variable is not set, the script will write to the SPI flash of the SBC or TS-9468 based on the switch position (if there is one).