UBIFS FAQ and HOWTO

Table of contents

1. May UBIFS be used on MLC NAND flash?
2. How to mount UBIFS?
3. How to create an UBIFS image?
4. How to find out LEB size?
5. May an empty UBI volume be mounted?
6. What is the purpose of -c (--max-leb-cnt) mkfs.ubifs option?
7. How to compile mkfs.ubifs?
8. Can UBIFS mount loop-back devices?
9. How to change a file atomically?
10. Does UBIFS support atime?
11. Does UBIFS support NFS?
12. Does UBIFS become slower when it is full?
13. Why df reports too few free space?
14. How to disable compression?
15. How to use UBIFS with nandsim?
16. Is UBIFS tolerant to power-cuts?

May UBIFS be used on MLC NAND flash?

Yes, it should run fine. Let's consider the specific aspects of MLC NAND flashes:

• MLC NAND flashes are more "faulty" than SLC, so they use stronger ECC codes which occupy whole OOB area; this is not a problem for UBI/UBIFS, because neither UBIFS nor UBI use OOB area;
• when the data is written to an eraseblock, it has to be written sequentially, from the beginning of the eraseblock to the end of it; this is also not a problem because it is exactly what UBI and UBIFS do (see also this section);
• MLC flashes have rather short eraseblock life-cycle of just few thousand of erase cycles; and this is not be a problem, because UBI uses deterministic wear-leveling algorithm (seethis section).

How to mount UBIFS?

UBIFS mounts UBI volumes, not UBI devices, not MTD devices. There are no block device nodes corresponding to UBI volumes and UBIFS uses device-less mount, just like procfs or sysfs. The volume to mount is specified using ubiX_Y or ubiX:NAME syntax, where

• X - UBI device number;
• Y - UBI volume number;
• NAME - UBI volume name.

For example,

$ mount -t ubifs ubi0_0 /mnt/ubifs

mounts volume 0 on UBI device 0 to /mnt/ubifs, and

$ mount -t ubifs ubi0:rootfs /mnt/ubifs

mounts "rootfs" volume of UBI device 0 to /mnt/ubifs ("rootfs" is volume name). This method of specifying UBI volume is more preferable because it does not depend on volume number.

Note, if X is not specified, UBIFS uses 0, i.e., "ubi0:rootfs" and "ubi:rootfs" are equivalent.

Some environments like busybox are confused by the ":" delimiter (e.g., ubi:rootfs) and "!" may be used instead (e.g., ubi!rootfs).

The following is an example of the kernel boot arguments to attach mtd0 to UBI and mount volume "rootfs":

ubi.mtd=0 root=ubi0:rootfs rootfstype=ubifs

Please, see this section for information about how to create UBI devices and this section for information about how to create UBI volumes.

How to create an UBIFS image?

Creating UBIFS images might be a little trickier than creating JFFS2 images. First of all, you have to understand that UBIFS works on top of UBI which works on top or MTD which basically represents your raw flash. This means, that if you need to create an image which would be flashed to the raw flash, you should first create an UBIFS image, than UBI image. In other words, the process has 2 steps.

However, as described here, UBI has a volume update facility and there is an ubiupdatevol utility which for this. So you may update UBI volumes straight form your running system as well. In this case, you only need UBIFS image, and you do not have to make the UBI image, i.e., the process has only 1 step in this case.

So, there are 2 utilities:

• mkfs.ubifs which creates UBIFS images;
• ubinize which creates UBI images.

And depending on the needs you use either mkfs.ubifs or mkfs.ubifs plus ubinize. Choose the former if you are going to upload the update UBIFS image on your target and then update the UBI volume using ubiupdatevol. Choose the latter if you are going to flash the image to raw flash, e.g., at the factory.

The UBI and UBIFS images depend on parameters of the flash they are going to be used on. Namely, you have to know the following characteristics of the flash before creating images:

• flash size;
• physical eraseblock size;
• minimum flash input/output unit size;
• for NAND flashes, sub-page size;
• logical eraseblock size.

This and this sections explain the above parameters and give some hints about how to find them out.

And optionally, you should decide which compression algorithm you would want to use for this file-system. UBIFS supports zlib and LZO (default) at the moment. Generally, zlib compresses better, but it is slower on both compression and decompression. So this is a trade-off between space savings and speed. The best idea is to try both and choose the one which is more appropriate for you. But if flash space is not a big issue, it is recommended to use LZO. Alternatively, the compression may be switched off. See "-x" option of the mkfs.ubifs utility.

There are other advanced file-system and UBI characteristics which may be altered with the tools. Use them only if you understand what they do.

The below example demonstrates how to create an UBI/UBIFS image for a 256MiB SLC OneNAND flash chip with 128KiB physical eraseblocks, 2048 bytes NAND pages, and which supports 4 sub-pages (this means that it allows to do 4x512 bytes writes to the same NAND page, which is quite typical for SLC flashes). The resulting image will have one UBI volume storing UBIFS file-system.

$ mkfs.ubifs -r root-fs -m 2048 -e 129024 -c 2047 -o ubifs.img $ ubinize -o ubi.img -m 2048 -p 128KiB -s 512 ubinize.cfg

where ubinize.cfg contains:

$ cat ubinize.cfg [ubifs] mode=ubi image=ubifs.img vol_id=0 vol_size=200MiB vol_type=dynamic vol_name=rootfs vol_flags=autoresize

Some comments about what the options mean:

• -r root-fs: tells mkfs.ubifs to create an UBIFS image which would have identical contents as the local root-fs directory has;
• -m 2048: tells mkfs.ubifs that the minimum input/output unit size of the flash this UBIFS image is created for is 2048 bytes;
• -e 129024: logical eraseblock size of the UBI volume this image is created for;
• -c 2047: specifies maximum file-system size in logical eraseblocks; this means that it will be possible to use the resulting file-system on volumes up to this size (less or equivalent); so in this particular case, the resulting FS may be put on volumes up to about 251MiB (129024 multiplied by 2047);
• -p 128KiB: tells ubinize that physical eraseblock size of the flash chip the UBI image is created for is 128KiB (128 * 1024 bytes);
• -s 512: tells ubinize that the flash supports sub-pages and sub-page size is 512 bytes; ubinize will take this into account and put the VID header to the same NAND page as the EC header.

The ubinize utility requires volumes description file. Please, refer this section for more ubinize usage information.

In the example, the ubinize.cfg file tells ubinize to create an UBI image which has a singe 200MiB dynamic volume with ID 0, and name "rootfs". The configuration file also sets the "autoresize" volume flag, which means that the volume will be automatically enlarged by UBIFS to have the maximum possible size when it runs for the first time. See here for more information about what the auto-resize feature is.

Please, run ubinize -h and mkfs.ubifs -h for more information and for more possibilities to tweak the generated images.

Here is one more example for a 32MiB NOR flash with 128KiB physical eraseblock size.

$ mkfs.ubifs -r root-fs -m 1 -e 130944 -c 255 -o ubifs.img $ ubinize -o ubi.img -m 1 -p 128KiB ubinize.cfg

where ubinize.cfg contains:

$ cat ubinize.cfg [ubifs] mode=ubi image=ubifs.img vol_id=0 vol_size=30MiB vol_type=dynamic vol_name=rootfs vol_alignment=1 vol_flags=autoresize

And one more example for a 512MiB MLC NAND flash with 128KiB physical eraseblock size, 2048 bytes NAND page size and no sub-page write support.

$ mkfs.ubifs -r root-fs -m 2048 -e 126976 -c 4095 -o ubifs.img $ ubinize -o ubi.img -m 2048 -p 128KiB ubinize.cfg

where ubinize.cfg contains:

$ cat ubinize.cfg [ubifs] mode=ubi image=ubifs.img vol_id=0 vol_size=450MiB vol_type=dynamic vol_name=rootfs vol_alignment=1 vol_flags=autoresize

How to find out LEB size?

When creating UBIFS images it is necessary to know logical eraseblock size which depends on the following flash chip parameters:

• physical eraseblock size;
• minimum input/output unit size;
• sub-page size;

Please, refer this section for more information about how to find those 3 parameters. Here are the most typical configurations:

• NOR flash with 1 byte min. I/O unit size: LEB size is PEB size minus 128;
• NAND flash with 512 byte NAND page and 265 byte sub-page: LEB size is PEB size minus 512;
• NAND flash with 2048 byte NAND page and 512 byte sub-page: LEB size is PEB size minus 2048;
• NAND flash with 2048 byte NAND page and no sub-page: LEB size is PEB size minus 4096.

Please, also refer this section for additional information.

The easiest way to find out the LEB size is to attach the MTD device to UBI, as it is suggested at the end of this section.

Is it OK to mount empty UBI volumes?

Yes, it is OK to mount empty UBI volumes, i.e. the volumes which contain only 0xFF bytes. In this case UBIFS formats the media automatically with default parameters (journal size, compression, etc). But generally, this feature should have limited use, and a proper UBIFS image should preferably be flashed created (see this section).

Note, UBI has similar property and it automatically formats the flash media if it is empty (see here). So if there is an mtd0 MTD device, the following will work:

# Wipe the MTD device out. Note, we could use flash_eraseall, but we do not # want to loose erase counters ubiformat /dev/mtd0 # Load UBI module modprobe ubi # Attach mtd0 to UBI - UBI will detect that the MTD device is # empty and automatically format it. This command will also create # UBI device 0 and udev should create /dev/ubi0 node ubiattach /dev/ubi_ctrl -m 0 # Create an UBI volume - the created volume will be empty ubimkvol /dev/ubi0 -N test_volume -s 10MiB # Mount UBIFS - it will automatically format the empty volume mount -t ubifs ubi0:test_volume /mnt/ubifs

It is also possible to wipe out an existing UBIFS volume represented by /dev/ubi0_0 using the following command:

ubiupdatevol /dev/ubi0_0 -t

What is the purpose of -c (--max-leb-cnt) mkfs.ubifs option?

It is a form of specifying file-system size. But instead of specifying the exact file-system size, this option defines the maximum file-system size (more strictly, maximum UBI volume size). For example, if you use --max-leb-cnt=200 mkfs.ubifs option, than it will be possible to put the resulting image to smaller UBI volume and mount it. But if the image is put to a larger UBI volume, the file-system will anyway take only first 200 LEBs, and the rest of the volume will be wasted.

Note, the --max-leb-cnt option does not affect the size of the resulting image file, which depends only on the amount of data in the file-system. mkfs.ubifs just writes the --max-leb-cntvalue to the file-system superblocks.

This feature is quite handy on NAND flashes, because they have random amount of initial bad eraseblocks (marked as bad in production). This means, that different devices may have slightly different volume sizes (especially if the UBI auto-resize feature is used). So you may specify the maximum possible volume size and this will guarantee that the image will work on all devices, irrespectively on the amount of initial bad eraseblocks.

Fundamentally, mkfs.ubifs has to know file-system size because UBIFS maintains and stores per-LEB information (like amount of dirty and free space in each LEB) in so-called LPT area on the media. So obviously, the size of this area depends on the total amount of LEBs, i.e. on the volume size. Note, various characteristics of the LPT B-tree depend on the LPT area size, e.g., we use less bits in LPT tree keys of smaller LPT area. So do not use unnecessarily large --max-leb-cnt value to achieve better performance.

Can UBIFS mount loop-back devices?

Unfortunately not, because loop-back devices are block devices (backed by regular files), while UBIFS works on top of UBI devices (see here).

However, there is a very hacky way to make UBIFS work with a file-backed image using NAND simulator (see here). Originally nandsim has been created to emulate NAND flashes in RAM, but there is a patch which teaches nandsim to use a file instead of memory. Try something like

# Create a 1GiB emulated MTD device backed by regular file "my_image" $ modprobe nandsim cache_file=my_image first_id_byte=0xec second_id_byte=0xd3 third_id_byte=0x51 fourth_id_byte=0x95

See here for more instructions about using UBIFS with nandsim.

But be warned that this patch has not been well tested, it is not in mainline yet, and it has been created for development and debugging purposes, but not for production use.

How to compile mkfs.ubifs?

The mkfs.ubifs utility requires zlib, lzo and uuid libraries. The former two are used for compressing the data, and the latter one is used for generating universally unique ID number for the file-system. In Fedora install zlib-devel, lzo-devel, and e2fsprogs-devel (libuuid is provided there, strangely) packages, in Debian install zlib1g-dev, liblzo2-dev and uuid-devpackages.

How to change a file atomically?

Changing a file atomically means changing the contents in a way that unclean reboots could not lead to any corruption or inconsistency in the file. The only reliable way to do this in UBIFS (and in most of other file-systems, e.g. JFFS2 or ext3) is the following:

• make a copy of the file;
• change the copy;
• synchronize the copy (see here);
• re-name the copy to the file (using the rename() libc function or mv utility).

Note, if power-cut happens during re-naming, the original file will be intact. This is POSIX requirement and UBIFS satisfies it.

Does UBIFS support atime?

No, it does not support atime. The authors think it is not very useful in embedded world and did not implement this. Indeed most of the users do not provably want the file-system doing inode updates every time it is read.

Does UBIFS support NFS?

Not so far, but it is planned to be implemented.