TS-7970 U-boot Sections
This platform uses U-Boot as the bootloader to launch the full operating system. The i.MX6 processor loads U-Boot from the on-board 8 MiB SPI flash. U-Boot provides support for loading data from various mediums; this allows booting a kernel from SD, eMMC, SATA, 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 should be similar to the output below:
U-Boot 2014.10-gee73348 (Oct 07 2015 - 11:12:20) I2C: ready DRAM: 1 GiB MMC: FSL_SDHC: 0, FSL_SDHC: 1 SF: Detected N25Q64 with page size 256 Bytes, erase size 4 KiB, total 8 MiB In: serial Out: serial Err: serial Net: using phy at 7 FEC [PRIME]
By default the device will boot to SD or eMMC depending on the status of the "SD Boot" jumper on startup.
To break into the U-Boot console, press and hold the SW1 button while the unit is being powered up. This mode will also check for a USB mass storage device to use for production purposes.
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. The variable contents are clobbered when set, so be sure to specify the full desired cmdline string.
env set cmdline_append console=ttymxc0,115200 init=/sbin/init quiet
env save
The kernel command line can also be modified from from the on-board Linux. Debian (and other distributions) provide a U-Boot utilities package that contains the tools necessary to create a U-Boot script:
apt-get update && apt-get install u-boot-tools -y
echo "env set cmdline_append console=ttymxc0,115200 init=/sbin/init quiet" > /boot/boot.scr
mkimage -A arm -T script -C none -n 'tsimx6 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.
U-Boot Recovery
U-Boot handles CPU and RAM setup/configuration that needs to be run every boot. Due to these configurations separate binaries are maintained for each CPU grade, RAM part, and RAM size; the correct binary must be used for any given device configuration. The specific device variant can be obtained in U-Boot via the command 'env print imx_type'.
On startup, the TS-7970 checks the SPI flash for a valid boot header in SPI flash. If it is unable to locate a valid boot header, the CPU falls back to the "serial downloader" which allows the CPU to execute code sent via USB. If the unit has a valid but damaged or incorrect U-Boot binary programmed in to SPI flash, an RMA return will be required in order to properly recover it. Please contact us for assistance with this.
1) Download the U-Boot binary for the correct imx_type variant from the list here: https://files.embeddedTS.com/ts-arm-sbc/ts-7970-linux/u-boot/. See the U-Boot Changelog for information on the changes between released versions.
2) Download and build/install the "imx_usb" loader
3) Disconnect power from the device.
4) Remove the "CON EN" jumper.
5) Apply power to the device.
6) Plug a USB type B cable into the P2 connector on the device and connect it to a host PC.
7) Check 'dmesg' or 'lsusb' on the host PC for a new USB connection. This should show a HID device listing NXP or Freescale as the manufacturer. For example:
hid-generic 0003:15A2:0054.0006: hiddev0,hidraw3: USB HID v1.10 Device [Freescale SemiConductor Inc SE Blank ARIK] on usb-0000:00:14.0-6.4.2/input0
If it does not show the above output, an RMA return will be required in order to properly recover the unit. Please contact us for assistance with this.
8) Hold down SW1.
9) Run 'imx_usb path/to/u-boot.imx' on the host PC while holding down SW1. Continue holding SW1 for a few seconds after the command is run. This is to force the unit to stop in U-Boot after 'imx_usb' has uploaded the U-Boot binary and the unit has begun booting.
10) Disconnect the USB cable on P2.
11) Set the "CON EN" jumper.
12) Re-insert the USB cable into P2.
At this point, the USB serial device should show up on the host, opening it will reveal that the unit is stopped at the U-Boot prompt. Follow the steps in Update U-Boot to reinstall U-Boot on the SPI flash.
Booting From NFS
U-Boot's NFS support can be used to load a kernel, device tree binary, and root filesystem over the network. The default scripts include an example NFS boot script.
# Set this to your NFS root path. The server root should be accessible at this path.
env set nfsroot 192.168.0.36:/mnt/storage/imx6/
env save
To boot to an NFS root:
# Boot to NFS once
run nfsboot;
# To make the NFS boot the persistent default
env set bootcmd run nfsboot;
env save
Booting From USB
With the push button held down before power on and a few seconds after, U-Boot will attempt to read a U-Boot script named /tsinit.ub from a USB drive. If present on the USB drive, U-Boot will automatically load this script in to memory and execute it. For our bootable USB disk images, no further action is needed.
To make a bootable drive from scratch, create a single ext3 partition on a USB drive and copy over your preferred rootfs just like you would with an SD card. This is described in the Debian and Yocto sections.
The one addition is to create the /tsinit.ub file in the root of the USB drive in order to allow U-Boot to boot from the drive's contents.
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 'mx6 usb' -d tsinit.scr tsinit.ub
# DO NOT MANUALLY EDIT THE .UB FILE
# If loading files from a partition other than the first partition on disk, change
# the second number to the partition number
env set bootpart 0:1
if test ${model} = '4900';
then load usb 0:1 ${loadaddr} /boot/ts4900-fpga.bin;
ice40 ${loadaddr} ${filesize};
bbdetect;
# Check rev, attempt to load the best dtb file for compatibility. If Rev E files
# are not found, attempt to boot prior dtb. If not Rev E, just boot prior dtb.
if test ${rev} > 'D'; then
if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-reve-${baseboardid}.dtb
then echo Baseboard $baseboardid detected;
elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-reve.dtb
then echo Booting default Rev E device tree;
elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb
then echo Baseboard $baseboardid detected;
elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb
then echo Booting default device tree;
fi
else
if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900-${baseboardid}.dtb
then echo Baseboard $baseboardid detected;
elif load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts4900.dtb
then echo Booting default device tree;
fi
fi
load usb ${bootpart} ${loadaddr} ${uimage};
setenv bootargs root=/dev/sda1 rootwait rw ${cmdline_append};
bootm ${loadaddr} - ${fdtaddr};
elif test ${model} = '7970'; then
# Check for Rev F or newer. If so, load that dtb. If Rev F dtb does not exist
# fall back to a prior dtb. If earlier Rev PCB, use prior dtb.
if test ${rev} > 'E'; then
if load usb ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970-revf.dtb; then
echo Loaded TS-7970 Rev F device tree;
elif load usb ${bootdev} ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970.dtb; then
echo Loaded TS-7970 device tree;
fi
else
if load usb ${bootdev} ${bootpart} ${fdtaddr} /boot/imx6${cpu}-ts7970.dtb; then
echo Loaded TS-7970 device tree;
fi
fi
load usb 0:1 ${loadaddr} ${uimage};
setenv bootargs root=/dev/sda1 rootwait rw ${cmdline_append};
bootm ${loadaddr} - ${fdtaddr};
fi
Then in the same directory generate the tsinit.ub file:
mkimage -A arm -T script -C none -n 'mx6 usb' -d tsinit.scr tsinit.ub
You may need to install u-boot-tools or the equivalent package for your distribution.
Update U-Boot
| WARNING: | Installing a custom U-Boot is not recommended and may cause the device to fail to boot. |
U-Boot requires a different build for Quad/Dual and Solo/Duallite. When booted to the U-Boot shell, run 'env print imx_type' and it will return the correct U-Boot build that should be used. Copy the built u-boot.imx file or the pre-built binary from our FTP site to the SD card as "/u-boot.imx", and run the following U-Boot commands:
mmc dev 0
load mmc 0:1 ${loadaddr} /u-boot.imx
sf probe
sf erase 0 0x80000
sf write ${loadaddr} 0x400 $filesize
U-Boot Development
We do provide our U-Boot sources but we do not recommend rebuilding a custom U-Boot if it can be avoided. Custom built U-Boot binaries will not have the latest up to date settings. Specifically, the largest concern is with RAM timing settings. Memory technology is expanding rapidly and we may need to use different parts through the shipping lifetime of the device itself. If RAM timings change, then we update our factory shipped U-Boot to have the proper settings. A custom U-Boot would need to be re-built if any of these settings change.
Our U-Boot includes a variable "imx_type". If loading a custom U-Boot binary, make sure to check the value of this before writing. If we are forced to update the RAM configuration we will change this variable. We will also send out a product change to anyone who is subscribed to our PCS system.
If you still need to proceed with building a custom U-Boot, use the imx_v2015.04_3.14.52_1.1.0_ga branch from the github here: https://github.com/embeddedTS/u-boot-imx
Boot up a TS-7970 into u-boot and run "echo ${imx_type}". This will show you the u-boot config to use for the correct RAM timing. We use the same GCC 6.2 used from Yocto Morty to compile the u-boot binary. This toolchain can be found here.
export ARCH=arm
export CROSS_COMPILE=/opt/poky/2.2.1/sysroots/x86_64-pokysdk-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-
git clone https://github.com/embeddedTS/u-boot-imx.git -b imx_v2015.04_3.14.52_1.1.0_ga
cd u-boot-imx
# For example, one of the quad core variants. Replace this with your imx_type
make ts7970-s-1g-800mhz-i_defconfig
make -j4
This will output a u-boot.imx file that can be written to the SPI flash following the instructions in the update U-Boot section.
Access U-Boot Environment from Linux
A utility called 'fw_printenv' is available which can set/read environment variables from Linux. This must be built and provided with a config file before it will work.
On the board first boot to U-Boot by holding SW1 during power on and startup. At the prompt run:
U-Boot > env print imx_type imx_type=<Output is dependent on specific configuration>
Save the output of the command then boot to Linux to build the 'fw_printenv' tool.
cd /usr/src/
git clone --depth 1 https://github.com/embeddedTS/u-boot-imx.git -b imx_v2015.04_3.14.52_1.1.0_ga
cd u-boot-imx
For example, if U-Boot returned "imx_type=ts7970-s-1g-800mhz-i", then the example defconfig is ts7970-s-1g-800mhz-i_defconfig. Be sure to use the correct imx_type defconfig!
# These next 2 commands should only be used if gcc --version is greater than 9
cp include/linux/compiler-gcc6.h include/linux/compiler-gcc9.h
sed --in-place 's/march=armv5)/march=armv5te)/g' arch/arm/Makefile
make ts7970-s-1g-800mhz-i_defconfig
make -j4 env
cp tools/env/fw_printenv /usr/bin/
# The same utility sets environment variables when
# called as fw_setenv
ln -s /usr/bin/fw_printenv /usr/bin/fw_setenv
The utility will also need a config file to know where to load the environment. Create the file, "/etc/fw_env.config", with the following contents:
# SPI flash on the TS-7970/TS-7990
# MTD device name Device offset Env. size Flash sector size Number of sectors
/dev/mtdblock0 0x100000 0x2000 0x1000 2
/dev/mtdblock0 0x180000 0x2000 0x1000 2
From here, "fw_printenv" can be run to read the environment variables. If first line of output is:
Warning: Bad CRC, using default environment
Then the environment saved is blank, and the utility output is loading the environment compiled into the U-Boot binary. This is normal and how units are shipped from the factory.
You can modify variables with this command as well:
# Set cmdline_append to include "quiet"
fw_setenv cmdline_append console=ttymxc0,115200 ro init=/sbin/init quiet