Linux root filesystem can be flashed on NAND memory in three different ways: running prfs.sh script provided by Engicam source codes, using ubiformat command of mtd-utils package with .ubi root filesystem, or from U-Boot exploiting TFTP with .ubifs. Each one of these procedures requires thus a different type of root filesystem, that the user can choose as the Yocto build option. In the chapter, a brief description of how to configure NAND image cross-compilation and how to install the image on memory are presented. At the end instructions about the use of the new NAND model MT29F4G08AFAEAH4-IT are reported.

Root filesystem configuration

The user can choose which type of root filesystem can be outputted from the compilation. This can be done by editing the machine configuration file, usually placed in conf/machine folder inside the image recipe meta-layer. For example, if the device is an iCoremx6 Dual Lite and the compiled image is engicam-test-hw from meta-engicam layer, the machine configuration file will be::

yocto-dir/sources/meta-engicam/conf/machine/icoremx6duallite.conf

To chose the type of change IMAGE_FSTYPES::

IMAGE_FSTYPES = "tar.bz2 ext4 sdcard ubifs ubi"

In the above example, the root filesystem will be generated as tar.bz2 archive, as part of the whole OS image, to flash onto SD card, as ext4 filesystem, as .ubi and .ubifs for NAND programming only. In our case the possible choices are tar.bz2, .ubi and .ubifs, depending on the procedure adopted to program the NAND memory.

If the user goal is to program NAND from U-Boot or .ubi a further configuration step is required. NAND device features must be passed to Bitbake through variables MKUBIFS_ARGS and UBINIZE_ARGS, defined in the same machine configuration file. To know the right values to give them, run on module console the command::

 ubiattach -m 3 /dev/ubi_ctrl

assuming that rootfs device is /dev/mtd3, as commonly set in Engicam modules. If rootfs is associated with another MTD device just write in the -m option the right index. The command gives as output the following ubi device specs::

ubi0: attaching mtd3
ubi0: scanning is finished
ubi0: attached mtd3 (name "rootfs", size 243 MiB)
ubi0: PEB size: 131072 bytes (128 KiB), LEB size: 126976 bytes
ubi0: min./max. I/O unit sizes: 2048/2048, sub-page size 2048
ubi0: VID header offset: 2048 (aligned 2048), data offset: 4096
ubi0: good PEBs: 1939, bad PEBs: 5, corrupted PEBs: 0
ubi0: user volume: 0, internal volumes: 1, max. volumes count: 128
ubi0: max/mean erase counter: 5/2, WL threshold: 4096, image sequence number: 492033789
ubi0: available PEBs: 1900, total reserved PEBs: 39, PEBs reserved for bad PEB handling: 35
ubi0: background thread "ubi_bgt0d" started, PID 357
UBI device number 0, total 1939 LEBs (246206464 bytes, 234.8 MiB), available 1900 LEBs (241254400 bytes, 230.1 MiB), LEB size 126976 bytes (124.0 KiB)

Relative MKUBIFS_ARGS and UBINIZE_ARGS are thus set by default as::

MKUBIFS_ARGS = "-m 2048 -e 126976 -c 1939"
UBINIZE_ARGS = "-m 2048 -p 128KiB -s 2048"  

where the options correspond to the following device properties::

-m → smallest flash I/O unit
-e → logical eraseblock size (LEB size)
-c → consecutive logical eraseblocks (LEBs)
-p → physical eraseblock size (PEB size)
-s → sub-page size

U-Boot configuration

Machine configuration files contain also UBOOT_CONFIG variables::

UBOOT_CONFIG[sd] = "icoremx6dl_sd_defconfig, sdcard"
UBOOT_CONFIG[nand] = "icoremx6dl_nand_defconfig, ubifs"
UBOOT_CONFIG[emmc] = "icoremx6dl_emmc_defconfig, sdcard"

that store the configuration file names for U-Boot image compilation, depending on which type of memory (either sd, nand, or emmc) it will be installed. Notice that the U-Boot type that will be compiled can be set either in conf/local.conf of Yocto build directory or editing the setup environment script before creating the build directory. Choosing the configuration for NAND as in the following example of local.conf file::

MACHINE ??= 'icoremx6duallite'
DISTRO ?= 'fslc-framebuffer'
PACKAGE_CLASSES ?= "package_rpm"
EXTRA_IMAGE_FEATURES ?= "debug-tweaks"
USER_CLASSES ?= "buildstats image-mklibs image-prelink"
PATCHRESOLVE = "noop"
BB_DISKMON_DIRS = "\
    STOPTASKS,${TMPDIR},1G,100K \
    STOPTASKS,${DL_DIR},1G,100K \
    STOPTASKS,${SSTATE_DIR},1G,100K \
    STOPTASKS,/tmp,100M,100K \
    ABORT,${TMPDIR},100M,1K \
    ABORT,${DL_DIR},100M,1K \
    ABORT,${SSTATE_DIR},100M,1K \
    ABORT,/tmp,10M,1K"
PACKAGECONFIG_append_pn-qemu-native = " sdl"
PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
CONF_VERSION = "1"

BB_NUMBER_THREADS = '12'
PARALLEL_MAKE = '-j 12'
PACKAGE_CLASSES = "package_ipk"

LICENSE_FLAGS_WHITELIST = "commercial license"

DL_DIR ?= "${BSPDIR}/downloads/"

UBOOT_CONFIG="nand"

PACKAGECONFIG_append_pn-qtbase = " tslib "
PACKAGECONFIG_append_pn-qtbase = " linuxfb "
PACKAGECONFIG_append_pn-qtbase = " fontconfig "

IMAGE_ROOTFS_SIZE = "2097152"
DISTRO_FEATURES_remove = " x11 wayland"
STARTUPDEMO = "resistive"
ACCEPT_FSL_EULA = "1"

an U-Boot image with preconfigured variables for NAND boot will be generated by Bitbake build.

Program NAND running prfs.sh

This is the program provided by Engicam to flash Linux root filesystem ( tar.bz2 type) on NAND memory. It is one of the scripts of engicam-mtd-script the recipe, always included in the default image of meta-engicam layer. The others perform analogous programming tasks for kernel ( prkernel.sh ), device-tree ( prdtb.sh ) and system boot ( prboot.sh ). In the following example, these scripts are used to flash on NAND the Bitbake image engicam-test-hw, compiled according to NAND specs configuration described in U-Boot configuration paragraph. The files available in the build directory are::

build-dir/tmp/deploy/images/<machine target>/engicam-test-hw-<machine target>.tar.bz2
build-dir/tmp/deploy/images/<machine target>/engicam-test-hw-<machine target>.sdcard
build-dir/tmp/deploy/images/<machine target>/u-boot.imx
build-dir/tmp/deploy/images/<machine target>/uImage-<machine target>.bin
build-dir/tmp/deploy/images/<machine target>/uImage-<file>.dtb

Copy and renamed them into an USB drive as follows::

engicam-test-hw-<machine target>.tar.bz2 → rootfs.tar.bz2
engicam-test-hw-<machine target>.sdcard → engicam-test-hw.sdcard
uImage-<machine target>.bin → uImage
uImage-<file>.dtb → uImage.dtb
u-boot.imx → u-boot.imx

Flash a sdcard with engicam-test-hw.sdcard and boot the device from it. Once the rootfs is loaded insert the USB drive and mount it::

mount /dev/sda1 /mnt
cd /mnt

then flash NAND memory with the Engicam mtd scripts, not necessarily in this order::

prfs.sh <ROOTFS FILE NAME>
prboot.sh <BOOT FILE NAME>
prdtb.sh <DEVICE TREE FILE NAME>
prkernel.sh <KERNEL FILE NAME>

where you do not need to specify any filename if they have already been changed as indicated above. In case these filenames have been left as build default, you need to provide them as options.

Program NAND with .ubi

We consider again the Bitbake image engicam-test-hw but we now describe how to flash NAND with .ubi root filesystem. To program kernel, device tree and U-Boot the procedure is the same of Program NAND running prfs.sh. Following instructions in Root filesystem configuration, Bitbake build creates .ubi files (in this case engicam-test-hw-<machine target>.ubi) that should be copied into a usb drive. Then flash an sd card  with engicam-test-hw.sdcard and boot the device from it. Once the rootfs is loaded insert the usb drive and mount it::

mount /dev/sda1 /mnt
cd /mnt

then use the tool ubiformat to flash rootfs::

flash_eraseall /dev/mtd3
ubiformat /dev/mtd3 -f engicam-test-hw-<machine target>.ubi 

Notice that the mtd device index is the one specific for root filesystem partition. The mtd partitions are configured in mtdparts variable of U-Boot.

Program NAND with .ubifs through TFTP

The last NAND program method requires TFTP, allowing the user to install the image on memory directly from U-Boot. For this purpose, it is necessary to configure and run a TFTP server hosting the scripts for programming, provided by Engicam layer at /yocto/sources/meta-engicam/tools/uboot_script/mx6-mx6ul/scr-file. In the same server folder the user needs to copy the following build files::

build-dir/tmp/deploy/images/<machine target>/engicam-test-hw-<machine target>.rootfs.ubifs
build-dir/tmp/deploy/images/<machine target>/uImage-<machine target>.bin
build-dir/tmp/deploy/images/<machine target>/uImage-<file>.dtb

that is root filesystem, kernel, and device tree respectively. For more information about how to compile an .ubifs root filesystem check :ref:reference-rootfs-nand. Rename the file as follow::

engicam-test-hw-<machine target>.rootfs.ubifs → rootfs.ubifs
uImage-<machine target>.bin → uImage
uImage-<file>.dtb → uImage.dtb

Power the device and set the server ip address in U_Boot variable::

setenv serverip=192.168.XX.XX   

Then download and execute scripts::

tftpboot ker.scr
source
tftpboot dtb.scr
source
tftpboot fs.scr
source

New NAND configuration

Due to obsolescence of NAND MT29F4G08ABAEAH4-IT previously mounted on i:CoreMX6 series, Engicam provides on its new module NAND MT29F4G08AFAEAH4-IT. In the following lines, the different programming features between the two are presented.

running prfs.sh

No differences between the programming procedures for the two NAND versions are present. The script is already designed to read NAND register containing memory specs and take them into account while flashing it.

with .ubi and .ubifs root filesystem

To get suitable .ubi and .ubifs for new NAND you need to update NAND parameters variables MKUBIFS_ARGS and UBINIZE_ARGS in the machine configuration file. This file is in conf/machine folder, placed inside the image recipe meta-layer ( ex. conf/machine/icoremx6duallite.conf for the build that will run on iCoremx6 Dual Lite module). To know the right values to associate to these variables run on module console the command::

 ubiattach -m 3 /dev/ubi_ctrl

assuming that rootfs device is /dev/mtd3, as commonly set in Engicam modules. If rootfs is associated with another MTD device just write in the -m option the right index::

ubi0: attaching mtd3
ubi0: scanning is finished
ubi0: attached mtd3 (name "rootfs", size 499 MiB)
ubi0: PEB size: 262144 bytes (256 KiB), LEB size: 253952 bytes
ubi0: min./max. I/O unit sizes: 4096/4096, sub-page size 4096
ubi0: VID header offset: 4096 (aligned 4096), data offset: 8192
ubi0: good PEBs: 1992, bad PEBs: 4, corrupted PEBs: 0
ubi0: user volume: 1, internal volumes: 1, max. volumes count: 128
ubi0: max/mean erase counter: 4/1, WL threshold: 4096, image sequence number: 0
ubi0: available PEBs: 0, total reserved PEBs: 1992, PEBs reserved for bad PEB handling: 15
ubi0: background thread "ubi_bgt0d" started, PID 356
UBI device number 0, total 1992 LEBs (505872384 bytes, 482.4 MiB), available 0 LEBs (0 bytes), LEB size 253952 bytes (248.0 KiB)

The relative MKUBIFS_ARGS and UBINIZE_ARGS have thus been set by default as::

MKUBIFS_ARGS = "-m 4096 -e 253952 -c 1992"
UBINIZE_ARGS = "-m 4096 -p 256KiB -s 4096"