How to Clone Embedded Linux on eMMC Based Toradex Modules

Applicable for

BSP Layers / Reference Images for Yocto (Linux)

[hide]

Article updated at 29 Oct 2021

Compare with Revision

Introduction

Attention: We do recommend deploying production Embedded Linux systems by building customised Anstrom/OpenEmbedded/Yocto Project images as outlined in the following article on our developer website: Build a Reference Image with Yocto Project.

Deprecation Note

When developing modern software, one should use VCS such as Git, among other best practices. Toradex strongly recommends that you develop your system either:

Using Yocto, if you are based on our Toradex BSP Layers and Reference Images for Yocto Project.
Using Torizon tooling, if you are based on TorizonCore.

Therefore we do not support cloning the content from the module's internal flash memory, such as eMMC.

Click here to see the obsolete/deprecated instructions from older versions of our BSP

This article describes how to easily clone the Embedded Linux BSP installation of an eMMC based Toradex module onto similar modules.

For the backup operation U-Boot's built-in USB mass storage (UMS) feature is used.

For the restore operation there are 3 main possibilities:

A) Direct restoring using UMS again
B) Integration into the legacy update package
C) Integration into the Toradex Easy Installer package (preferred if available).

Note: This article does not describe cloning the boot loader. It is recommended to separately deploy resp. desired boot loader either using our legacy update procedure (e.g. run setupdate; run update_uboot) or the Toradex Easy Installer (e.g. using a custom JSON containing just the boot loader) prior to proceeding (Preferred if available). Also, remember to port any U-Boot environment changes if there should be any.

Please note that in below-given commands user may have to be replaced by your resp. user as logged into your Linux workstation.

Attention: this article has not been validated against BSPs 3 and 5. You may try to follow the steps from the previous BSP versions, but some commands were reported as not working.

BSP 2.8
BSP 2.7 and older

Sometimes you want to create a Toradex Easy Installer image from an existing installation. The easiest way of doing this on boards with eMMC storage is the following.

1. Rootfs

Insert an SD Card or USB Stick and mount it

mount /dev/<mmc/sd> /mnt

Mount the root partition to a clean mount point

mkdir /tmp/rootfs 
mount /dev/mmcblk0p2 /tmp/rootfs 
cd /tmp/rootfs 
tar -czf /mnt/my-rootfs.tar.gz .

Unmount the root partition and the SD or USB-Stick

cd
umount /tmp/rootfs
umount /mnt

Download the original Toardex Easy Installer image from our website: Linux Software

Now you can copy my-rootfs.tar.gz to the directory where you untared the original image. In the file image.json you have to replace "image name".rootfs.tar.xz with my-rootfs.tar.gz

2. Bootfs

Insert an SD Card or USB Stick and mount it

mount /dev/<mmc/sd> /mnt

Mount the root partition to a clean mount point

mkdir /tmp/bootfs
mount /dev/mmcblk0p1 /tmp/bootfs 
cd /tmp/bootfs 
tar -czf /mnt/my-bootfs.tar.gz .

Unmount the root partition and the SD or USB-Stick

cd
umount /tmp/bootfs
umount /mnt

Download the original Toardex Easy Installer image from our website: Linux Software

Now you can copy my-bootfs.tar.gz to the directory where you untared the original image. In the file image.json you have to replace "image name".bootfs.tar.xz with my-bootfs.tar.gz

3. Flash from TEZI

To flash the newly created image from TEZI you can follow the Toradex Easy Installer article.

1. Backup

1.1 Activate UMS Feature

Enter the U-Boot console and activate the UMS feature on resp. eMMC block device:

Apalis TK1 # ums 0 mmc 0
UMS: LUN 0, dev 0, hwpart 0, sector 0x0, count 0x1d5a000
/

1.2 Connect USB Device

Connect the target's USB device interface to your Linux workstation and check which block device or mounted file system it refers to:

[user@host ~]$ dmesg | tail -n 18
[ 2771.811733] usb 1-3.4.2.1: new high-speed USB device number 18 using xhci_hcd
[ 2771.890461] usb 1-3.4.2.1: New USB device found, idVendor=1b67, idProduct=4022
[ 2771.890464] usb 1-3.4.2.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 2771.890465] usb 1-3.4.2.1: Product: USB download gadget
[ 2771.890467] usb 1-3.4.2.1: Manufacturer: Toradex
[ 2771.893539] usb-storage 1-3.4.2.1:1.0: USB Mass Storage device detected
[ 2771.893657] scsi host4: usb-storage 1-3.4.2.1:1.0
[ 2772.938274] scsi 4:0:0:0: Direct-Access     Linux    UMS disk 0       ffff PQ: 0 ANSI: 2
[ 2772.938791] sd 4:0:0:0: Attached scsi generic sg1 type 0
[ 2772.938922] sd 4:0:0:0: [sdb] 30777344 512-byte logical blocks: (15.8 GB/14.7 GiB)
[ 2772.939156] sd 4:0:0:0: [sdb] Write Protect is off
[ 2772.939159] sd 4:0:0:0: [sdb] Mode Sense: 0f 00 00 00
[ 2772.939347] sd 4:0:0:0: [sdb] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA
[ 2772.944846]  sdb: sdb1 sdb2
[ 2772.946150] sd 4:0:0:0: [sdb] Attached SCSI removable disk
[ 2773.871090] FAT-fs (sdb1): Volume was not properly unmounted. Some data may be corrupt. Please run fsck.
[ 2773.878201] EXT4-fs (sdb2): mounting ext3 file system using the ext4 subsystem
[ 2773.945085] EXT4-fs (sdb2): mounted filesystem with ordered data mode. Opts: (null)
[user@host ~]$ lsblk | grep -E 'boot|rootfs'
├─sdb1                                          8:17   1    16M  0 part  /run/media/user/boot
└─sdb2                                          8:18   1  14.6G  0 part  /run/media/user/rootfs

1.3 Backup File Systems

Backup resp. file systems intended to clone:

[user@host ~]$ tar cJvf bootfs.tar.xz -C /run/media/user/boot .
./
./uImage
./tegra124-apalis-eval.dtb
./tegra124-apalis-v1.2-eval.dtb
[user@host ~]$ sudo tar cJf rootfs.tar.xz -C /run/media/user/rootfs .

This will take a while...

Note: Running tar as superuser is crucial to make sure all files can be accessed and user/group IDs are properly archived in the tar file. If the particular OS you are backing up is making use of any extended file attributes those would additionally need to be specified for preservation by tar (e.g. using --acls, --selinux and/or --xattrs).

1.4 Unmount File Systems

Unmount boot and rootfs on your Linux workstation and stop aka CTRL+C U-Boot's UMS:

[user@host ~]$ sudo umount /run/media/user/boot
[user@host ~]$ sudo umount /run/media/user/rootfs
Apalis TK1 # ums 0 mmc 0
UMS: LUN 0, dev 0, hwpart 0, sector 0x0, count 0x1d5a000
CTRL+C - Operation aborted

2. Restore

For restore there are 3 main possibilities: A) Direct restore using UMS again; B) Integrate into legacy update package; or C) Integrate into Toradex Easy Installer package (Preferred if available).

A) 2.1 Clear File Systems

Using a module with similar BSP already installed (e.g. not running Toradex Easy Installer refer to C) below otherwise) perform steps 1 and 2 from above, then first clear out resp. file systems:

[user@host ~]$ rm /run/media/user/boot/*
[user@host ~]$ sudo rm -rf /run/media/user/rootfs/*

A) 2.2 Restore File Systems

Now proceed to restoring from previous tar files:

[user@host ~]$ tar xJvf bootfs.tar.xz -C /run/media/user/boot
./
./uImage
./tegra124-apalis-eval.dtb
./tegra124-apalis-v1.2-eval.dtb
[user@host ~]$ sudo tar xJf rootfs.tar.xz -C /run/media/user/rootfs

A) 2.3 Unmount File Systems

Now don't forget to unmount resp. file systems and stop UMS as in step 4 above. After a target reset your cloned BSP should be booting.

B) 2.1 Integrate Artefacts

Integrate above backed-up artefacts into our regular legacy update package:

[user@host ~]$ tar xjf ~/Downloads/Apalis-TK1_LXDE-Image_2.7b4-20171007.tar.bz2
[user@host ~]$ cd Apalis-TK1_LXDE-Image_2.7.4/
[user@host Apalis-TK1_LXDE-Image_2.7.4] tar xJvf ~/bootfs.tar.xz
./uImage
./tegra124-apalis-eval.dtb
./tegra124-apalis-v1.2-eval.dtb
[user@host Apalis-TK1_LXDE-Image_2.7.4] sudo cp uImage apalis-tk1_bin/uImage
[user@host Apalis-TK1_LXDE-Image_2.7.4] sudo cp tegra124-apalis-eval.dtb apalis-tk1_bin/uImage-tegra124-apalis-eval.dtb
[user@host Apalis-TK1_LXDE-Image_2.7.4] sudo cp tegra124-apalis-v1.2-eval.dtb apalis-tk1_bin/uImage-tegra124-apalis-v1.2-eval.dtb
[user@host Apalis-TK1_LXDE-Image_2.7.4] rm uImage tegra124-apalis-eval.dtb tegra124-apalis-v1.2-eval.dtb
[user@host Apalis-TK1_LXDE-Image_2.7.4] cd rootfs
[user@host rootfs] sudo mv lib/modules ..
[user@host rootfs] sudo rm -rf *
[user@host rootfs] sudo tar xJf ~/rootfs.tar.xz
[user@host rootfs] sudo mv ../lib .

B) 2.2 Generate Update Media

Now one can proceed in generating the desired update media (e.g. SD card or USB memory stick resp. download folder of TFTP server) just as used to:

[user@host Apalis-TK1_LXDE-Image_2.7.4]$ ./update.sh -o /run/media/user/sdb1/

B) 2.3 Update

Now proceed with the update as before e.g. from within the U-Boot console:

Apalis TK1 # run setupdate; run update

B) 2.4 Reset And Boot

After the automatic target reset your cloned BSP should be booting.

C) 2.1 Integrate Artefacts

Integrate above backed-up artefacts into our regular Toradex Easy Installer package:

[user@host ~]$ tar xf ~/Downloads/Apalis-TK1_LXDE-Image-Tezi_2.7b5-20171201.tar
[user@host ~]$ cd Apalis-TK1_LXDE-Image-Tezi_2.7b5/
[user@host Apalis-TK1_LXDE-Image-Tezi_2.7b5]$ rm Apalis-TK1_LXDE-Image.bootfs.tar.xz
[user@host Apalis-TK1_LXDE-Image-Tezi_2.7b5]$ rm Apalis-TK1_LXDE-Image.rootfs.tar.xz
[user@host Apalis-TK1_LXDE-Image-Tezi_2.7b5]$ cp ~/bootfs.tar.xz Apalis-TK1_LXDE-Image.bootfs.tar.xz
[user@host Apalis-TK1_LXDE-Image-Tezi_2.7b5]$ cp ~/rootfs.tar.xz Apalis-TK1_LXDE-Image.rootfs.tar.xz

C) 2.2 Adjust Image.json

Now adjust the image.json to your liking (e.g. change at least the name and description for you to be able to distinguish it from our regular package). You should also update the nominal and un-compressed (partition) sizes accordingly. You may of course also change any of the other properties as documented in the Toradex Easy Installer article on our developer website.

C) 2.3 Use Toradex Easy Installer

You may now use above prepared Toradex Easy Installer package with the Toradex Easy Installer.

Need more help?

Ask the experts in our Community!