How to write an UBIFS rootfs image to NAND

The images on this site are normally run from a bootable SD card.  For OMAP boards with NAND, it is also possible to boot from a NAND image.  To boot from NAND you will need to write four different binary images to NAND:

• X-loader
• U-boot
• Linux kernel
• Root file system

This article covers the fourth step of that process, the root file system.  Click on each of the other links above for instructions on how to write the other images to NAND.

UBIFS

It is highly recommended that you use the Unsorted Block Image File System (UBFS) for your NAND root file system.
UBIFS is a successor to JFFS2.  It offers improved performance and stability and scales better to systems with large NAND storage.  You can learn more about it at the project home page.
Unfortunately these advantages come at a small cost -- creating an UBIFS image is a bit more complicated than other file systems.
This article will discuss two methods to prepare a NAND ubifs image from a rootfs tarball.  Both of these methods use the Linux command line to write the rootfs.  While it is also possible to write an UBIFS file system from u-boot, the Linux command line methods are preferred.
These instructions assume you are running a bootable SD image from this site.  You will also need a tarball of the rootfs you want to write to NAND.  For this example we will download a console image tarball from this site and use that for our ubifs image (command broken into 2 lines for web page aesthetics!):

# wget \
> http://feeds.sakoman.com/feeds/gnome-r13/images/omap3-multi/current/sakoman-console-image.tar.bz2

Method 1: ubimkvol

The first method creates a blank ubifs volume in NAND, then mounts it, and extracts the desired rootfs to the mounted volume.
First let's erase the NAND roofs partition:

# flash_erase /dev/mtd4 0 0

If your NAND has any bad blocks (a small number are normal and not a cause for concern) you may see messages indicating that some blocks could not be erased. You can safely ignore these messages.
Next we create an empty UBIFS file system:

# ubiattach /dev/ubi_ctrl -m 4
# ubimkvol /dev/ubi0 -N rootfs -m

Again, if your NAND has a few bad blocks you will see messages indicating that these blocks are being marked as "bad". If you look closely you will see that these are the same blocks that were listed in the nand_erase step above. You can safely ignore these messages too.
Now we will mount the newly created UBIFS files system and extract our rootfs tarball onto it:

mkdir /mnt/nand
mount -t ubifs ubi0:rootfs /mnt/nand
sudo tar xvf sakoman-console-image.tar.bz2 -C /mnt/nand

Method 2: ubiformat

The second method uses mkfs to create an ubifs binary image that is then written to NAND using ubiformat.
We'll start by untarring our rootfs tarball:

mkdir rootfs
sudo tar xvf sakoman-console-image.tar.bz2 -C rootfs

Then, using the text editor of your choice, create a file called ubinize.cfg with the following contents:

[ubifs]
mode=ubi
image=rootfs.ubifs
vol_id=0
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize

Next create an ubifs binary image with mkfs.ubifs and "wrap" it into a UBI image with ubinize:

sudo mkfs.ubifs -v -r rootfs -o rootfs.ubifs -m 2048 -e 129024 -c 1996
sudo ubinize -v -o rootfs.ubi -m 2048 -p 128KiB -s 512 ubinize.cfg

And finally write the ubinized image to NAND using ubiformat:

sudo ubiformat -y /dev/mtd4 -f rootfs.ubi

You might want to use this second method if you are developing a production tool to flash NAND since the initial steps can be done once in advance and only the ubiformat command would be needed per unit. This is much faster than Method 1.
Note:  The GNOME r13 and later releases on this site are pre-configured to support UBIFS.   Earlier releases do not support UBIFS.

U-boot Environment setup

The u-boot images on this site are pre-configured to use UBIFS when booting from NAND.  In particular, the following 2 u-boot environment variables are initialized as follows:

# printenv nandrootfstype
nandrootfstype=ubifs
# printenv nandroot
nandroot=ubi0:rootfs ubi.mtd=4