UBI/UBIFS support
=================

barebox has both UBI and UBIFS support. For handling UBI barebox has commands similar to
the Linux commands :ref:`command_ubiformat`, :ref:`command_ubiattach`, :ref:`command_ubidetach`,
:ref:`command_ubimkvol` and :ref:`command_ubirmvol`.

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 :ref:`command_ubiformat` the
device:

.. code-block:: sh

  ubiformat /dev/nand0.root

If you intend to use a device with UBI you should always use ``ubiformat`` instead of plain
:ref:`command_erase`. ``ubiformat`` will make sure the erasecounters are preserved and also
:ref:`ubi_fastmap` won't work when a flash is erased with ``erase``

**NOTE:** when using the :ref:`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 :ref:`command_ubiattach`.

.. code-block:: sh

  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:

.. code-block:: sh

  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:

.. code-block:: sh

  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:

.. code-block:: sh

  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:

.. code-block:: sh

  cp /mnt/tftp/root.ubifs /dev/ubi0.root

Finally it can be mounted using the :ref:`command_mount` command:

.. code-block:: sh

  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:

.. code-block:: sh

  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:``:

.. code-block:: sh

  #!/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.

.. _ubi_fastmap:

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``:

.. code-block:: sh

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