docs(linux): Kernel: Add UBIFS documentation

Add instructions to generate UBI image for OSPI/QSPI NOR/NAND
flashes.

Signed-off-by: Santhosh Kumar K <[email protected]>

Author: Santhosh Kumar K

source/linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI.rst

@@ -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
 

source/linux/Foundational_Components/Kernel/Kernel_Drivers/Storage/NAND.rst

@@ -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
@@ -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.
@@ -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/
-