TS-7670 eMMC Backup

The eMMC device is set up like a standard SD card when presented to the system, however it does have a few differences. eMMC offers "enhanced mode" which makes the usually MLC device behave like an SLC device. This setting does decrease the effective device size, however the benefit of reliability greatly makes up for it. Another option that eMMC offers is "write reliability." This setting changes the internal behavior of the eMMC, meaning that if a power-off occurs during a write, the guaranteed loss is limited to the currently written 512 byte sector. Aside from those two settings, the device will appear as a standard SD card, with the same partition setup as our standard SD card size, save for the maximum size of the linux partition, the second partition. The first partition contains the raw bootstream (kernel and initramfs in one binary blob); the second partition houses the Debian linux filesystem.

Kernel

Due to the way the NXP bootlets work, the easiest way to get a kernel on the eMMC device is to use a direct `dd` image of a bootable SD card. In order to create a `dd` image, use the following command on a bootable SD card:

dd if=/dev/sdX1 of=kernelpart.dd

Replace /dev/sdX1 with the first partition of a bootable SD card. The file "kernelpart.dd" can then be copied to the first partition of a USB drive and used in conjunction with kernel_from_usb below. This step is not necessary if using kernel_from_sd.

If a bootable SD card is in slot 0, the following command can be used when booted from either said SD card, or eMMC:

kernel_from_sd

In using a USB device to update the kernel of the eMMC, the process is slightly different. The following script expects the file /mnt/usbdev/kernelpart.dd The kernelpart.dd file is created by using the `dd` command as stated above.

kernel_from_usb

Both scripts above will take a few moments and will return with an exit of 0, and print "prog_ok=1" upon success. This command will also destroy and re-create the partition table. As long as the factory partition scheme is used, this command is safe to run without having to update the eMMC filesystem as well.

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

Filesystem

The process to update the filesystem on eMMC simply uses a tarball of the desired linux filesystem. Technologic Systems strongly recommends to do all development on an SD card and later create a tarball from that Debian filesystem. This allows for easy creation of a tarball from the existing master SD card to be used in production processes.

The tarball can be created from an existing filesystem. A command like the following should be all that is needed.

tar cvf rootfs.tar -C /mnt/source_fs_root/ .

This command will create rootfs.tar in the current directory from the filesystem tree root located at /mnt/source_fs_root/ Many implementations of `tar` will not have issues with creating the output file in the same directory as input. However it is recommended to keep the output file in a different directory than the source, just in case.

This tarball can be used in conjunction with scripts in our initramfs to flash the eMMC device.

Copy rootfs.tar to the root Debian folder (partition 2) of a bootable SD card. Be sure there is enough space available. Our standard image has enough free space to allow this. Boot from the SD card to the initramfs, and use the following command:

filesystem_from_sd

Alternatively, the rootfs.tar can be copied to the root directory of the first partition of a USB drive:

filesystem_from_usb

In this case, the script expects the file /mnt/usbdev/rootfs.tar to exist.

Output from the commands will look like the following:

prog_ok=1

WARNING:

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

Using *_from_usb when booted from eMMC

Since part of this process will modify an active partition table in the eMMC, this script is required for updating either the kernel or the filesystem when booted from eMMC.

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 kernelpart.dd and rootfs.tar 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 the bootdev. These sections will unmount the root filesystem and then mount the USB drive as the new root filesystem. This allows the contents of the eMMC device to be completely re-written with tools available in Debian without having the eMMC device mounted.

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.