TS-7670 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

When the kernel is built and installed to the SD card from a host PC, it copies the current bootstream to the SD card as well. It copies it to /lib/modules/imx28_ivt_linux.sb, the bootstream is a Freescale boot mechanism that contains the bootloader and kernel all in one binary. When booted from an SD card, the bootstream at /lib/modules/imx28_ivt_linux.sb can be flashed to mtd0 with

kernel_from_sd

This will take a few moments and then will return with no messages if everything was successful.

The following command can be used to update the kernel on NAND from the imx28_ivt_linux.sb file from USB:

kernel_from_usb

The file is expected to be located at /mnt/usbdev/imx28_ive_linux.sb, the command is intended for use with our USB update mechanism. The file can be copied from the Debian partition of a bootable SD card, /lib/modules/imx28_ivt_linux.sb; or directly from a kernel build, /<kernel_tree>/imx-bootlets-src-10.12.01/imx28_ivt_linux.sb.

See the section on our USB update mechanism for more information about utilizing this process.

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 to do all development on an SD card and later create a UBIFS image from that Debian filesystem. Copying the large amount of small files Debian has to or from the NAND is very time consuming.

Making the UBIFS image from a host PC. Note that 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.

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 NAND partitions mounted), further preparation is required in order to successfully boot from NAND, and use the USB update functionality to update the NAND flash. A USB device is required to have the the Debian distribution on the first partition, as well as a specific set of steps contained in the tsinit file to ensure the NAND is safely unmounted, and all of the UBI tools are available.

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, create the file "tsinit" in the root directory of the first partition of the USB drive, make it world executable with `chmod a+x` and make sure it has the contents of the following script:

#!/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 to NAND"
  tshwctl --greenledoff
  while true; do tshwctl --redledon; sleep .5; tshwctl --redledoff; sleep .5 ; done &
  return 1
fi
echo "Flashing NAND"
eval `filesystem_from_usb`
if [ "$prog_ok" != "1" ] ; then
  echo "Failed flashing filesystem to NAND"
  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.