TS-7680 NAND Backup

The NAND is divided in to three devices, mtd0, mtd1, and mtd2. mtd0 contains the raw bootstream (kernel and initramfs in one binary), mtd1 contains what would normally be the /ts folder on the SD card, and mtd2 contains the linux root filesystem (mtd1 and mtd2 use UBI and UBIFS and can be subdivided down further with mechanisms in UBIFS, see UBI and UBIFS for more information). Since UBI/UBIFS does have a fairly linear mount time for device size, mtd1 is made fairly small, 8MB. This allows for increased startup speed when booting from NAND so that configuration, FPGA softload, or other scripts may be run as soon as possible after power is applied.

Kernel

The kernel build scripts will build and copy a uImage file to the SD card. This file is used by U-Boot for SD card and NAND booting. For the NAND however, and extra step is required to copy the uImage file in to a NAND partition that U-Boot can quickly load from. This can be accomplished with a single U-Boot command.

First, boot to the U-Boot shell by holding the push switch while applying power. The device does not need to be booted from SD, however the following command expects a properly formatted SD card, with the kernel to be installed, present in the system at bootup.

At the U-Boot prompt, enter the command:

run update_nand_kernel

The output will show the NAND kernel partition being erased, and then having the new kernel written to it. A valid U-Boot binary must also be installed in the NAND in order to boot from. This process is completed at the factory, however it is possible to restore or update the U-Boot binary. Please see the U-Boot section for more information.

Filesystem

Making a UBIFS Debian image from existing filesystem is the best way to make a custom image for production devices. Technologic Systems strongly recommends doing all development on an SD card; later, create a UBIFS image from that Debian filesystem. Copying the large amount of small files on the Debian filesystem directly to or from the NAND device is very time consuming.

In order to create a UBIFS image from a host PC mtd-utils will need to be installed, please see your distribution's documentation for instructions on installation

#/mnt/source_fs_root is the mounted Debian filesystem on an SD; /mnt/usb is a USB drive to store the image for later use
mkfs.ubifs -m4096 -e516096 -c3861 -r /mnt/source_fs_root/ nandimg.ubifs

Note that the UBI rootfs partition on NAND is 1900MiB, Make sure that the UBIFS image is smaller than this. UBI does implement compression on-disk, so the total size of a folder tree may not reflect the actual filesystem size when made in to a UBIFS image. For example, our default SD Debian root filesystem is around 1.2GB, however when made in to a UBIFS image with the above command, it is compressed to roughly 550MB and remains this size on disk.

The latest UBIFS image can be found on our FTP site.

This NAND UBIFS image can be used in conjunction with tools in our initramfs to flash the NAND device.

Copy nandimg.ubifs to the root Debian folder (partition 2) of a pre-imaged bootable SD card. The SD card can either be a freshly imaged SD card, or be one that was used for current development, provided that there is enough space to fit the UBIFS image. Boot from the SD card to the initramfs, when presented a command prompt, run the following command:

filesystem_from_sd

Output from the command will look like the following:

prog_ok=1

The following command can be used to flash the UBIFS image to NAND:

filesystem_from_usb

The UBIFS image file is expected to be located at /mnt/usbdev/nandimg.ubifs, the command is intended for use with our USB update mechanism.

WARNING:

The `filesystem_from_*` commands will completely format any existing data that is on the NAND linux root partition

Using filesystem_from_usb when booted from NAND

While there is no issue in executing filesystem_from_usb when booted from SD (provided there are no flash partitions mounted), further preparation is required in order to successfully boot from eMMC/NAND, and use the USB update functionality to update the flash. A USB device is required to have the the Debian distribution on the first partition and a specific set of steps in the "tsinit" script - this ensures that all flash partitions are safely unmounted and the necessary tools are available. See the initramfs USB scripting section for more information on setting up the "tsinit" script.

Using a linux host PC, format a USB drive with the first partition (min. 2GB) formatted ext2/3. Download the distribution tarball and extract it to first partition of the USB drive.

Next, set up the "tsinit" file with the following script outline:

#!/bin/sh

#We only need unmount /mnt/root and use USB if booted from NAND/eMMC
if [ "$bootmode" == "0x1" ]; then
  killall mdnsd >/dev/null #Required to cleanly umount /etc
  sleep 1
  if [ -e /dev/mtd0 ]; then
    umount /mnt/root/ts
  fi
  umount /etc
  umount /mnt/root

  mount -obind /mnt/usbdev /mnt/root
  mount -obind /mnt/root/etc /etc/
fi

echo ""
source /ts.subr
tshwctl --greenledon --redledon
echo "Flashing kernel"
kernel_from_usb >/dev/null 2>&1
if [ "$?" != "0" ]; then
  echo "Failed flashing kernel"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
echo "Flashing filesystem"
eval `filesystem_from_usb`
if [ "$prog_ok" != "1" ] ; then
  echo "Failed flashing filesystem"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi

#We only need unmount /mnt/root and use USB if booted from NAND
if [ "$bootmode" == "0x1" ]; then
  umount /etc
  umount /mnt/root
fi

echo "Done"
while true; do tshwctl --greenledon; sleep .5; tshwctl --greenledoff; sleep .5 ; done &

Be sure to copy nandimg.ubifs and imx28_ivt_linux.sb to the root directory of the first partition of the USB drive as well!

Note, if you wish to integrate this in to your own custom USB update script, the critical sections for setting up this process are surrounded by the if blocks that check for NAND being the bootdev.

The above script will keep both LEDs on and solid while the process is happening, and will blink the green or red LED upon success or fail of the imaging process. Upon completion a power cycle or reboot is required if booted from NAND to run the update.

There are a number of different configurations and setups available when using UBI and UBIFS, see UBI and UBIFS for more information about the capabilities of the subsystem.