1.17. UBI/UBIFS support

barebox has both UBI and UBIFS support. For handling UBI barebox has commands similar to the Linux commands ubiformat - format an ubi volume, ubiattach - attach mtd device to UBI, ubidetach - detach an UBI device, ubimkvol - create an UBI volume and ubirmvol - delete an UBI volume.

The first step for preparing a pristine Flash for UBI is to ubiformat - format an ubi volume the device:

ubiformat /dev/nand0.root

If you intend to use a device with UBI you should always use ubiformat instead of plain erase - erase flash memory. ubiformat will make sure the erasecounters are preserved and also UBI Fastmap won’t work when a flash is erased with erase

NOTE: when using the UBI Fastmap feature make sure that the UBI is attached and detached once after using ubiformat. This makes sure the Fastmap is written.

After a device has been formatted it can be attached with ubiattach - attach mtd device to UBI.

ubiattach /dev/nand0.root

This will create the controlling node /dev/nand0.root.ubi and also register all volumes present on the device as /dev/nand0.root.ubi.<volname>. When freshly formatted there won’t be any volumes present. A volume can be created with:

ubimkvol /dev/nand0.root.ubi root 0

The first parameter is the controlling node. The second parameter is the name of the volume. In this case the volume can be found under /dev/dev/nand0.root.ubi.root. The third parameter contains the size. A size of zero means that all available space shall be used.

The next step is to write a UBIFS image to the volume. The image must be created on a host using the mkfs.ubifs command. mkfs.ubifs requires several arguments for describing the flash layout. Values for these arguments can be retrieved from a devinfo ubi under barebox:

barebox@Phytec pcm970:/ devinfo nand0.root.ubi
  peb_size: 16384
  leb_size: 15360
  vid_header_offset: 512
  min_io_size: 512
  sub_page_size: 512
  good_peb_count: 3796
  bad_peb_count: 4
  max_erase_counter: 0
  mean_erase_counter: 0
  available_pebs: 3713
  reserved_pebs: 83

To build a UBIFS image for this device the following command is suitable:

mkfs.ubifs --min-io-size=512 --leb-size=15360 --max-leb-cnt=4096 -r rootdir \

The --max-leb-cnt parameter specifies the maximum number of logical erase blocks the UBIFS image can ever have. For this particular device a number of 3713 would be enough. If the image shall be used for multiple boards the maximim peb count of all boards must be used.

The UBIFS image can be transferred to the board for example with TFTP:

cp /mnt/tftp/root.ubifs /dev/nand0.root.ubi.root

Finally it can be mounted using the mount - mount a filesystem or list mounted filesystems command:

mount /dev/nand0.root.ubi.root

The default mount path when the mount point is skipped is /mnt/<devname>, so in this example it will be /mnt/nand0.root.ubi.root. The second time the UBIFS is mounted the above can be simplified to:

ubiattach /dev/nand0.root
mount /dev/nand0.root.ubi.root

Mounting the UBIFS can also be made transparent with the automount command. The command automount -d /mnt/nand0.root.ubi.root 'mount nand0.root.ubi.root' will automatically attach the UBI device and mount the UBIFS image to /mnt/nand0.root.ubi.root whenever /mnt/nand0.root.ubi.root is first accessed. The automount command can be added to /env/init/automount to execute it during startup.

1.17.1. UBI Fastmap

When attaching UBI to a flash device the UBI code has to scan all eraseblocks on the flash. Since this can take some time the Fastmap feature has been introduced. It has been merged in Linux 3.7. barebox has support for the Fastmap feature, but to use it some care must be taken. The Fastmap feature reduces scanning time by adding informations to one of the first blocks of a flash. For technical details see http://www.linux-mtd.infradead.org/doc/ubi.html#L_fastmap. Since the Fastmap can only live near the beginning of a flash the Fastmap code relies on finding a free eraseblock there. The above example command make that sure, but Fastmap is incompatible with creating a UBI image on a host and directly flashing the UBI image to the raw NAND/NOR device. In this case the Fastmap code will not find a free eraseblock and the following message will occur during ubidetach:

UBI error: ubi_update_fastmap: could not find any anchor PEB
UBI warning: ubi_update_fastmap: Unable to write new fastmap, err=-28

The Fastmap is first written after a ubidetach, so it’s important to attach/detach a UBI volume after using ubiformat.