TS-7553v2 U-Boot Sections
This platform includes U-Boot as the bootloader to load and boot the full operating system. The i.MX6UL processor loads U-Boot from the eMMC flash at power-on. U-Boot allows booting images from the microSD, eMMC, NFS, or USB. U-Boot is a general purpose bootloader that is capable of booting into common Linux distributions, Android, QNX, or others.
On a normal boot, output from U-Boot will be similar to the following:
U-Boot 2016.03-00305-g75344a5 (Dec 15 2017 - 13:53:14 -0800) CPU: Freescale i.MX6UL rev1.1 at 396 MHz Reset cause: WDOG Board: Technologic Systems TS-7553-V2 I2C: ready DRAM: 512 MiB MMC: FSL_SDHC: 0, FSL_SDHC: 1 Net: FEC0 [PRIME] Booting from the SD card ... ** File not found /boot/boot.ub ** 34511 bytes read in 162 ms (208 KiB/s) 5460520 bytes read in 391 ms (13.3 MiB/s) NO CHRG jumper is set, not waiting Kernel image @ 0x80800000 [ 0x000000 - 0x535228 ] ## Flattened Device Tree blob at 83000000 Booting using the fdt blob at 0x83000000 Using Device Tree in place at 83000000, end 8300b6ce Starting kernel ...
By default the board will boot to SD or eMMC depending on the status of the "SD Boot" jumper on startup.
Entering U-Boot shell
The U-Boot shell is a powerful tool. It allows modification of the environment, as well as the ability to run commands directly. By default, there are two ways to enter the shell: Set the U-Boot jumper, or press and hold the Push Switch before applying power and hold it for 5 seconds. When entering the U-Boot shell, it will attempt to run a script on a USB mass storage device before finally dropping to the shell.
The reset switch is provided as a convenience, so U-Boot can be entered without having to open any kind of enclosure. It can also be disabled for security purposes. Even if the switch is disabled, the U-Boot shell can still be accessed by using the U-Boot jumper.
To disable the press-and-hold method of entering the U-Boot shell, use the following U-Boot commands:
env set rstuboot 0
env save
By setting the env var, rstuboot, to a 1, the push-and-hold method can be re-enabled.
U-Boot Environment
The eMMC flash contains both the U-Boot executable binary and U-Boot environment. Our default build has 2 MiB of environment space which can be used for variables and boot scripts. The following commands are examples of how to manipulate the U-Boot 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 environment changes to the SPI flash
# Otherwise changes are lost
env save
# Restore environment to default
env default -a
# Remove a variable
env delete emmcboot
U-Boot Commands
# The most important command is
help
# This can also be used to see more information on a specific command
help i2c
# This is a command added to U-Boot by TS to read the baseboard ID on our
# System on Module devices
bbdetect
echo ${baseboard} ${baseboardid}
# The echo will return something similar to:
# TS-8390 2
# Boots into the binary at $loadaddr. The loaded file needs to have
# the U-Boot header from mkimage. A uImage already contains this.
bootm
# Boots into the binary at $loadaddr, skips the initrd, specifies
# the FDT addrress so Linux knows where to find the device tree
bootm ${loadaddr} - ${fdtaddr}
# 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
# 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:1 ${loadaddr} /boot/uImage
# Load Kernel from eMMC
load mmc 1:1 ${loadaddr} /boot/uImage
# Load kernel from USB
usb start
load usb 0:1 ${loadaddr} /boot/uImage
# Load kernel from SATA
sata init
load sata 0:1 ${loadaddr} /boot/uImage
# View the FDT from U-Boot
load mmc 0:1 ${fdtaddr} /boot/imx6q-ts4900.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:
ls mmc 0:1 /
# Access memory like devmem in Linux, read/write arbitrary memory
# using mw and md
# write
mw 0x10000000 0xc0ffee00 1
# read
md 0x10000000 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/ubootscript
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/uImage;
then echo Loaded Kernel
else
echo Could not find kernel
fi
# Commands can be timed with "time"
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. If new arguments are added, the existing value should also be included with the new arguments.
env set cmdline_append rw rootwait console=ttymxc0,115200 quiet
env save
The kernel command line can also be modified from from the onboard Linux. From the linux shell prompt run the following commands to install the necessary tools and create the script:
apt-get update && apt-get install u-boot-tools -y
echo "env set cmdline_append rw rootwait console=ttymxc0,115200 quiet" > /boot/boot.scr
mkimage -A arm -T script -C none -n 'tsimx6ul boot script' -d /boot/boot.scr /boot/boot.ub
The boot.scr includes the plain text commands to be run in U-Boot on startup. The mkimage tool adds a checksum and header to this file which can be loaded by U-Boot. The .ub file should not be edited directly.
Booting From NFS
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.
# Set this to your NFS server IP and NFS directory path
env set nfsroot 192.168.0.1:/path/to/nfs/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
| Note: | If 'bootcmd' is used to test for whether the system should stop at the U-Boot shell or continue, the above will make it difficult to get back to the U-Boot shell as it will always attempt to boot regardless of jumper status. |
Booting From USB
By default, U-Boot will attempt to read a U-Boot script from a USB drive when the U-Boot jumper is set (or the reset button is enabled and depressed). It copies /tsinit.ub into memory and jumps in to the script. To make a bootable drive, create a single ext4 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 device itself. 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 'ts7553v2 usb' -d tsinit.scr tsinit.ub
# DO NOT MANUALLY EDIT THE .UB FILE
load usb 0:1 ${fdtaddr} /boot/imx6ul-ts7553v2${variant}.dtb;
load usb 0:1 ${loadaddr} /boot/zImage;
setenv bootargs root=/dev/sda1 ${cmdline_append};
bootz ${loadaddr} - ${fdtaddr};
Then in the same directory generate the tsinit.ub file:
mkimage -A arm -T script -C none -n 'ts7553v2 usb' -d tsinit.scr tsinit.ub
Update U-Boot
| WARNING: | Installing a custom U-Boot is not recommended and may cause the device to fail to boot. |
The latest U-Boot binary can be downloaded from the TS-7553-V2 FTP site. Copy this file to /boot/u-boot.imx on the 1st partition of the SD card. The U-Boot binary can be updated by inserting that SD card in to the TS-7553-V2, setting the U-Boot and SD card jumpers, and powering up the unit. At the U-Boot prompt, the following command can be used:
run update-uboot
The above script will use the /boot/u-boot.imx file from the SD card or eMMC, depending on the state of the SD Boot jumper.
U-Boot Development
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 you still want to proceed with building a custom U-Boot, use the "tsimx_v2016.03_4.1.15_2.0.0_ga" branch from the github here: https://github.com/embeddedTS/u-boot-imx
When compiling, we recommend using ONLY this cross-compiler, the use of any other compiler may cause issues. Specifically, we have experienced RAM problems when using a more recent cross compiler to build this version of U-Boot. The use of any other compiler may leave the system in an unbootable state!
export ARCH=arm
export CROSS_COMPILE=/path/to/folder/bin/arm-tsimx6ul-linux-gnueabihf-
make ts7553v2_defconfig
make u-boot.imx
This will output a u-boot.imx that can be written to the device using the steps in Update U-Boot.
POST
The TS-7553-V2 includes a simple POST test. This is normally used in production to verify basic functionality rapidly before doing more thorough testing. By default, this is not enabled on every boot, but it can be added via U-Boot scripting if there is a need for additional confidence in the application. The POST test quickly verifies basic functionality of: USB, RTC, Ethernet PHY, FRAM (if present), WiFi/BT module (if present), eMMC (see warning below), RAM, and the supervisory microcontroller.
The post test can be run with the following command in U-Boot:
post
| WARNING: | The 'post' command has an optional "-d" argument; when this argument is passed it does a write and readback test of the eMMC and FRAM which is DESTRUCTIVE to the data on the disk! Note that it will not modify the boot sector contents of the eMMC. The eMMC chip is still tested for basic functionality without the argument passed, but no data is read or written from the disk itself. |