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 

Check the health of a NAND-flash with features of the UBI device

If an UBI Device is used on top of NAND-flash, you can use ubinfo /dev/ubiY to check the health of the NAND-flash.

Here an example:

root@dhcom1bimx6ull:~# ubinfo /dev/ubi0
ubi0
Volumes count:                           2
Logical eraseblock size:                 126976 bytes, 124.0 KiB
Total amount of logical eraseblocks:     1019 (129388544 bytes, 123.3 MiB)
Amount of available logical eraseblocks: 0 (0 bytes)
Maximum count of volumes                 128
Count of bad physical eraseblocks:       5
Count of reserved physical eraseblocks:  15
Current maximum erase counter value:     40
Minimum input/output unit size:          2048 bytes
Character device major/minor:            242:0
Present volumes:                         0, 1

Important are the following fields:

• "Count of bad physical eraseblocks": This value indicates how many eraseblocks are bad. Note that there may be some eraseblocks that are bad when the NAND-flash memory was manufactured.
• "Count of reserved physical eraseblocks": This number indicates how many eraseblocks are available as a reserve if other eraseblock gets bad. If this reserve is depleted then it is a sign that the NAND-flash is at the end of its life.
• "Current maximum erase counter value": This value indicates how often the eraseblock with the highest number of erases was erased. Note that UBI devices use wear leveling to distribute the erases of heavely used eraseblocks to different eraseblocks. The number of erases an eraseblock can usually last until it gets bad depends on the NAND flash itself. Important: The erase counter is saved inside the data structure of the UBI device, so if you erase the NAND flash without using ubiformat the current erase counter will get lost and reset to 1!

You can also check the health of the NAND flash at the bootloader (for example when the linux isn't booting anymore). The following commands are needed for doing this:

• mtdparts to get the name of the UBI device (in this example: "main-nand").
• ubi part main-nand to set the current partition to the UBI device (in this case it is set to main-nand).
• ubi info to print the information about the UBI device.