Skip to content

Commit

Permalink
docs(linux): Kernel: Add UBIFS documentation
Browse files Browse the repository at this point in the history 
Add instructions to generate UBI image for OSPI/QSPI NOR/NAND
flashes.

Signed-off-by: Santhosh Kumar K <s-k6@ti.com>
  • Loading branch information
Santhosh Kumar K committed Dec 10, 2024
1 parent 2fb012f commit 32aa48c
Show file tree
Hide file tree
Showing 2 changed files with 250 additions and 48 deletions.
241 changes: 239 additions & 2 deletions source/linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -420,11 +420,248 @@ or via command line arguments):
$ dd if=/dev/mtd6 of=tmp_read.txt bs=num count=1 # read to num bytes to flash
$ diff tmp_read.txt tmp_write.txt # should be NULL
.. note::

Make sure UBIFS filesystem is enabled in the kernel (refer to `this
section <#enabling-qspi-driver-configurations>`__ for more information).

.. linux_ubifs_start
.. rubric:: Unsorted Block Image File System (UBIFS)
:name: linux-ubifs

UBIFS is a flash file system for unmanaged flash memory devices. UBIFS works on
top of an UBI layer, which is itself on top of MTD (Memory Technology Device)
layer. UBI + UBIFS takes care of wear leveling, bad-block management, etc.

.. rubric:: Using UBIFS on flash
:name: using-ubifs-on-flash

Make sure UBIFS filesystem is enabled in the kernel (refer to `this
section <#enabling-qspi-driver-configurations>`__ for more information).
.. rubric:: Required Software for UBI image creation
:name: linux-required-software-ubifs

Building a UBI File System requires two applications, :command:`ubinize` and
:command:`mkfs.ubifs`. Both are both provided by ``mtd-utils`` package.

.. code-block:: console
$ sudo apt-get install mtd-utils
.. rubric:: Building a UBI File System image
:name: linux-building-ubi-file-system

Step 1: Create a directory containing the files and directories for the file
system. It is important that the directory size is smaller than the ``rootfs``
partition in the flash.

Step 2: Create a file named :file:`ubinize.cfg` and add the contents below.

.. code-block:: text
[ubifs]
mode=ubi
image=rootfs.ubifs
vol_id=0
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
.. linux_ubifs_end
.. linux_args_detail_start
.. rubric:: mkfs.ubifs
:name: linux-mkfs-ubifs

:command:`mkfs.ubifs` is used to create UBI File System image, which is
specifically generated for a flash memory device, like Serial NOR, NAND and
Parallel NAND.

Syntax

.. code-block:: console
mkfs.ubifs -r <root_dir> -o <output_image> [options]
Some key options to use:

1. ``-m <min_io_size>``: specifies the minimum I/O size (in bytes) of the flash
device.

2. ``-e <leb_size>``: specifies the logical eraseblock (LEB) size, which is the
usable portion of an eraseblock in UBI (physical eraseblock - UBI overhead)

3. ``-c <max_leb>``: specifies the maximum number of logical eraseblocks (LEBs) the
filesystem can use.

4. ``-x <compression>``: specifies the compression method to use. Default is
``zlib``

5. ``-F``: used to force the filesystem to "fixup" all the free space which it
is going to use. Note, this flag makes the first mount very slow, because
the "free space fixup" procedure takes time.

For more details:

.. code-block:: console
mkfs.ubifs --help
.. rubric:: ubinize
:name: linux-ubinize

:command:`ubinize` is used to create UBI image for one or more UBIFS images.

.. code-block:: console
ubinize [options] -o <output_image> <configuration_file>
Some key options to use:

1. ``-m <min_io_size>``: specifies the minimum I/O size (in bytes) of the flash
device.

2. ``-p <peb_size>``: specifies the physical eraseblock size, which is the
total size of an eraseblock in the flash device.

3. ``-s <sub_page_size>``: specifies the sub-page size. Usually equivalent to
the minimum I/O size.

4. ``-O <vid_hdr_offset>``: specifies the offset of the VID (Volume Identifier)
header within the physical eraseblock.

For more details:

.. code-block:: console
ubinize --help
.. linux_args_detail_end
.. ifconfig:: CONFIG_part_variant in ('AM64X')

Step 3: Generate .ubifs image

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 16 -e 262016 -c 219
Step 4: Generate .ubi image

.. code-block:: console
$ ubinize -o rootfs.ubi -m 16 -p 262144 -s 16 -O 64 ubinize.cfg
.. ifconfig:: CONFIG_part_variant in ('AM62X')

Step 3: Generate .ubifs image

For OSPI NOR:

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 16 -e 262016 -c 219
For OSPI NAND:

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 2048 -e 126976 -c 743
Step 4: Generate .ubi image

For OSPI NOR:

.. code-block:: console
$ ubinize -o rootfs.ubi -m 16 -p 262144 -s 16 -O 64 ubinize.cfg
For OSPI NAND:

.. code-block:: console
$ ubinize -o rootfs.ubi -m 2048 -p 131072 -s 2048 -O 2048 ubinize.cfg
.. ifconfig:: CONFIG_part_variant in ('AM62AX')

Step 3: Generate .ubifs image

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 2048 -e 126976 -c 743
Step 4: Generate .ubi image

.. code-block:: console
$ ubinize -o rootfs.ubi -m 2048 -p 131072 -s 2048 -O 2048 ubinize.cfg
.. ifconfig:: CONFIG_part_variant in ('AM62PX', 'J7200')

Step 3: Generate .ubifs image

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 16 -e 262016 -c 219
Step 4: Generate .ubi image

.. code-block:: console
$ ubinize -o rootfs.ubi -m 16 -p 262144 -s 16 -O 64 ubinize.cfg
.. ifconfig:: CONFIG_part_variant in ('J721E')

Step 3: Generate .ubifs image

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs <MKUBIFS ARGS>
Step 4: Generate .ubi image

.. code-block:: console
$ ubinize -o rootfs.ubi <UBINIZE ARGS> ubinize.cfg
.. ifconfig:: CONFIG_part_variant in ('J721S2', 'J784S4', 'J742S2', 'J722S')

Step 3: Generate .ubifs image

For OSPI NOR:

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 16 -e 262016 -c 219
For OSPI NAND:

.. code-block:: console
$ mkfs.ubifs -r /path/to/directory -o rootfs.ubifs -m 4096 -e 253952 -c 369
Step 4: Generate .ubi image

For OSPI NOR:

.. code-block:: console
$ ubinize -o rootfs.ubi -m 16 -p 262144 -s 16 -O 64 ubinize.cfg
For OSPI NAND:

.. code-block:: console
$ ubinize -o rootfs.ubi -m 16 -p 262144 -s 4096 -O 4096 ubinize.cfg
Step 5: Flash rootfs.ubi to ``ospi.rootfs`` or ``ospi_nand.rootfs`` partition
in the flash

.. code-block:: console
# EVM Linux
$ ubiformat -f rootfs.ubi /dev/mtdX
.. code-block:: console
Expand Down
57 changes: 11 additions & 46 deletions source/linux/Foundational_Components/Kernel/Kernel_Drivers/Storage/NAND.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,49 +164,11 @@ Information regarding NAND booting and booting the kernel and file
system from NAND can be found in the U-boot User Guide NAND
section.

.. include:: ../QSPI.rst
:start-after: .. linux_ubifs_start
:end-before: .. linux_ubifs_end

.. rubric:: **NAND Based File system**
:name: nand-based-file-system

The bootloader and u-boot partitions don't use any filesystem. The
images are flased directly to NAND flash.

The Filesystem though uses UBIFS filesystem. NAND flash is prone to
bit-flips. UBI + UBIFS takes care of the bit-flips issue and as well as
many other things like wear leveling, bad-block management, etc.

.. rubric:: Required Software for UBI image creation
:name: required-software-ubifs

Building a UBI file system requires two applications, ubinize and
mkfs.ubifs. Both are both provided by mtd-utils package.
(sudo apt-get install mtd-utils).

.. rubric:: Building a UBI File system image
:name: building-ubi-file-system

When building a UBI file system you need to have a directory that
contains the exact files and directories layout that you plan to use for
your file system. This is similar to the files and directories layout
you will use to copy a file system onto a SD card for booting purposes.
It is important that your file system size is smaller than the file
system partition in the NAND.

Next you need a file named ubinize.cfg. Below contains the exact
contents of ubinize.cfg you should use. However, replace **<name>**
with a name of your choosing. e.g. rootfs

ubinize.cfg contents:

::

[ubifs]
mode=ubi
image=<name>.ubifs
vol_id=0
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
Step 3:

To build a UBI files system requires the below two commands. The
symbol **<directory path>** should be replaced with the path to
Expand All @@ -217,12 +179,16 @@ many other things like wear leveling, bad-block management, etc.
**<UBINIZE ARGS>** are board specific. Replace these values with the
values seen in the below table based on the TI EVM you are using.

.. include:: ../QSPI.rst
:start-after: .. linux_args_detail_start
:end-before: .. linux_args_detail_end

Commands to execute:

::
.. code-block:: console
~# mkfs.ubifs -r <directory path> -o <name>.ubifs <MKUBIFS ARGS>
~# ubinize -o <name>.ubi <UBINIZE ARGS> ubinize.cfg
~# mkfs.ubifs -r <directory path> -o <name>.ubifs <MKUBIFS ARGS>
~# ubinize -o <name>.ubi <UBINIZE ARGS> ubinize.cfg
Once these commands are executed <name>.ubi can then be flashed into
the NAND's file-system partition.
Expand Down Expand Up @@ -526,4 +492,3 @@ http://www.linux-mtd.infradead.org/doc/ubi.html
http://www.linux-mtd.infradead.org/doc/ubifs.html
https://wiki.linaro.org/Flash%20memory
https://lwn.net/Articles/428584/

0 comments on commit 32aa48c

Please sign in to comment.