16. 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 following examples assume we work on the first UBI device. Replace ubi0 with the appropriate number when you have multiple UBI devices.

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/ubi0 and also register all volumes present on the device as /dev/ubi0.<volname>. When freshly formatted there won’t be any volumes present. A volume can be created with:

ubimkvol /dev/ubi0 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/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 ubi0
Parameters:
  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 \
      /tftpboot/root.ubifs

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/ubi0.root

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

mkdir -p /mnt/ubi
mount -t ubifs /dev/ubi0.root /mnt/ubi

The second time the UBIFS is mounted the above can be simplified to:

ubiattach /dev/nand0.root
mount -t ubifs /dev/ubi0.root /mnt/ubi

Mounting the UBIFS can also be made transparent with the automount command. With this helper script in /env/bin/automount-ubi::

#!/bin/sh

if [ ! -e /dev/ubi0 ]; then
      ubiattach /dev/nand0 || exit 1
fi

mount -t ubifs /dev/ubi0.root $automount_path

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

16.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.