UBI/UBIFS Filesystem

Overview

On DHCOM Systems with Linux the UBIFS Filesystem is used for the NAND-Flash root-filesystem. The Unsorted Block Image File System (UBIFS) is a filesystem for use with raw flash memory media. UBIFS works on top of an Unsorted Block Images (UBI) device, which is itself on top of an MTD device.

For further details please have a look at

• UBI documentation
• UBIFS documentation
• MTD documentation

Create Images

To create UBI-Images or UBIFS-Images you need to install the "mtd-utils" on your Linux host pc. We recommend to download the latest version of the mtd-utils form the mtd-utils git-repository because it is reported that some versions from the distribution repositorys are buggy and/or out of date.

Create UBIFS Images

To create a UBIFS Image you need some hardware-depended information.

• <min io size> Equals the page-size of the used NAND-Flash
• <LEB size> Logical Erase Block size
• <Erase Blocks count> maximum logical erase block count

If got this information, you can create a UBIFS-Image from a directory-tree with the following command:

# sodu mkfs.ubifs -F -r </path/to/your/rootfs/tree> -m <min io size> -e <LEB size> -c <Erase Blocks count> -o </path/to/output/Image.ubifs>

Examples

for am3517 with 256MB NAND-Flash

# sudo mkfs.ubifs –F -r /work/rootfs -m 2048 -e 126976 -c 1700 -o am35x.ubifs

for i.MX25 with 256MB NAND-Flash

# sudo mkfs.ubifs –F -r /work/rootfs -m 2048 -e 129024 -c 1700 -o imx25.ubifs

Remark To use the option -F you habe to run a kernel version 3.0 or higher. You need to have the "mtd-utils" version 1.5.x or higher, too.

Use the ubinfo command on your device to check the LEB size and count. Example: # ubinfo /dev/ubi0

Create UBI Images

To create a UBI image you have to have already a UBIFS image. Use the following command:

# ubinize -vv -o <output image> -m <min io size> -p <PEB size>KiB -s <subpage-size> -O <VID-hdr-offset> <configuration file>

• <min io size> Equals the page-size of the used NAND-Flash
• <PEB size> Physical Erase Block size (in KiB) - Equals the block size of the NAND-Flash
• <Erase Blocks count> Count of the available Erase Blocks
• <subpage-size> Subpage size in bytes. Default value is the minimum input/output size (page-size)
• <VID-hdr-offset> offset if the VID header from start of the PEB (default is the next min I/O unit or sub-page after the EC header)
• <configuration file> Path to a configuration file.

Example of a configuration file content (config.ini):

 [rootfs_volume]
 mode=ubi
 image=imx25.ubifs
 vol_id=0
 vol_type=dynamic
 vol_name=nand_rootfs
 vol_flags=autoresize

Examples

for am3517

# sudo ubinize -vv -o am3517_rtfs.ubi -m 2048 -p 128KiB config.ini

for i.MX25

# sudo ubinize -vv -o imx25_rtfs.ubi -m 2048 -p 128KiB -s 512 -O 512 config.ini

User-space tools

The UBI/UBIFS user-space tools are included within the mtd-utils.

some commands are:

• ubinfo - provides information about UBI devices and volumes found in the system;
• ubiattach - attaches MTD devices (which describe raw flash) to UBI and creates corresponding UBI devices;
• ubidetach - detaches MTD devices from UBI devices (the opposite to what ubiattach does);
• ubimkvol - creates UBI volumes on UBI devices;
• ubirmvol - removes UBI volumes from UBI devices;
• ubiupdatevol - updates UBI volumes;
• ubiformat - formats empty flash, erases flash and preserves erase counters, flashes UBI images to MTD devices;
• mtdinfo - reports information about MTD devices found in the system.

Use the "-h" option to get more information about the commands.

Flashing UBI/UBIFS Images

The following commands can be used to flash UBI/UBIFS Images on a running linux device (you can not flash your active root filesystem). When you want to run a linux root-filesystem update please use the subfunction Root Filesystem Update of the DHCOM Update Mechnism. In special cases you can use the following commands:

Flash a UBIFS Image

ubiformat /dev/mtdX
ubiattach -m X -d Y /dev/ubi_ctrl
ubimkvol /dev/ubiY -N volume_name -s -m
ubiupdatevol /dev/ubiY_0 /path/to/Image.ubifs 

Flash a UBI Image

 ubiformat /dev/mtdX –f Image.ubi