doc: usage: Add File System section and Ext4 documentation

Create doc/usage/filesystems/ section.
Convert doc/README.ext4 to rST format and move it to the new section.
Update documentation to add configuration instruction for Ext4 Write
when using large partitions.

Note that this patch depends on this previous patch:
https://patchwork.ozlabs.org/project/uboot/patch/20250910215702.15576-1-mibodhi@gmail.com/

Signed-off-by: Tony Dinh <mibodhi@gmail.com>
Reviewed-by: Anshul Dalal <anshuld@ti.com>

diff --git a/doc/README.ext4 b/doc/usage/filesystems/ext4.rst
similarity index 51%
rename from doc/README.ext4
rename to doc/usage/filesystems/ext4.rst
index ca9f19953d215dfb35b822c123987606999e76b4..c6cdaf57facaa424f6589e004b5a223d9837a356 100644 (file)
--- a/doc/README.ext4
+++ b/doc/usage/filesystems/ext4.rst
@@ -1,9 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Ext4 File System
+================
+
+Overview
+--------
+
 U-Boot supports access of both ext2 and ext4 filesystems, either in read-only
 mode or in read-write mode.
 
+Configuration
+-------------
+
 First, to enable support for both ext4 (and, automatically, ext2 as well),
 but without selecting the corresponding commands, enable one of the following:
 
+::
+
   CONFIG_FS_EXT4       (for read-only)
   CONFIG_EXT4_WRITE    (for read-write)
 
@@ -20,22 +33,28 @@ or ext4-related commands:
 
 use one or both of:
 
-  CONFIG_CMD_EXT2
-  CONFIG_CMD_EXT4
+::
+
+       CONFIG_CMD_EXT2
+       CONFIG_CMD_EXT4
 
 Selecting either of the above automatically selects CONFIG_FS_EXT4 if it
 wasn't enabled already.
 
-In addition, to get the write access command "ext4write", enable:
+In addition, to get the write access command ``ext4write``, enable:
 
-  CONFIG_CMD_EXT4_WRITE
+::
+
+       CONFIG_CMD_EXT4_WRITE
 
 which automatically selects CONFIG_EXT4_WRITE if it wasn't defined
 already.
 
 Also relevant are the generic filesystem commands, selected by:
 
-  CONFIG_CMD_FS_GENERIC
+::
+
+       CONFIG_CMD_FS_GENERIC
 
 This does not automatically enable EXT4 support for you, you still need
 to do that yourself.
@@ -44,6 +63,8 @@ Lastly, the current u-boot implementation for Ext4 write requires a lot
 of memory to run successfully. The following enable support for
 large Ext4 partitions:
 
+::
+
        CONFIG_EXT4_MAX_JOURNAL_ENTRIES
        CONFIG_SYS_MALLOC_LEN
 
@@ -51,11 +72,16 @@ The number of journal entries and dynamic memory allocation are proportional
 to the partition capacity. For example, an ext4 4TB HDD partition could
 require approximately 500 entries and more than 128 MB heap space.
 
+Examples
+--------
+
 Some sample commands to test ext4 support:
 
-1. Check that the commands can be seen in the output of U-Boot help:
+1. Check that the ext4 commands can be seen in the output of U-Boot help:
+
+::
 
-       UBOOT #help
+       => help
        ...
        ext4load- load binary file from a Ext4 file system
        ext4ls  - list files in a directory (default /)
@@ -63,32 +89,49 @@ Some sample commands to test ext4 support:
        ext4write- create a file in ext4 formatted partition
        ...
 
-2. To list the files in an ext4-formatted partition, run:
+2. The ``ext4ls`` command can be used to list the files in an ext4-formatted partition:
+
+::
 
        ext4ls <interface> <dev[:part]> [directory]
 
-       For example:
-       UBOOT #ext4ls mmc 0:5 /usr/lib
+For example, to list files in ext4-formatted partition directory /usr/lib:
+
+::
+
+       => ext4ls mmc 0:5 /usr/lib
+
+3. The ``ext4load`` command can be used to read and load a file from an
+ext4-formatted partition to RAM:
+
+::
+
+       ext4load <interface> [<dev[:part]> [addr [filename [bytes [pos]]]]]
+
+For example, to load file /uImage from an ext4-formatted partition:
+
+::
+
+       => ext4load mmc 2:2 0x30007fc0 uImage
+
+4. The ``ext4write`` command can be used to write to an ext4 partition:
+
+::
 
-3. To read and load a file from an ext4-formatted partition to RAM, run:
+       ext4write <interface> <dev[:part]> <addr> <absolute filename path> [sizebytes] [file offset]
 
-       ext4load <interface> <dev[:part]> [addr] [filename] [bytes]
+For example, to write a file loaded at 0x8200000 of size 256 bytes to an
+ext4-formatted partition with the filename ``/boot/sample_file.hex``:
 
-       For example:
-       UBOOT #ext4load mmc 2:2 0x30007fc0 uImage
+::
 
-4. To write a file to an ext4-formatted partition.
+       => ext4write mmc 2:2 0x82000000 /boot/sample_file.hex 0x100
+       256 bytes written in 138 ms (1000 Bytes/s)
 
-       a) First load a file to RAM at a particular address for example 0x30007fc0.
-       Now execute ext4write command:
-       ext4write <interface> <dev[:part]> [filename] [Address] [sizebytes]
 
-       For example:
-       UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 6183120
-       (here 6183120 is the size of the file to be written)
-       Note: Absolute path is required for the file to be written
+References
+----------
 
-References :
-       -- ext4 implementation in Linux Kernel
-       -- Uboot existing ext2 load and ls implementation
-       -- Journaling block device JBD2 implementation in linux Kernel
+       * ext4 implementation in Linux Kernel
+       * Uboot existing ext2 load and ls implementation
+       * Journaling block device JBD2 implementation in linux Kernel

diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 3a48521d5d5618da9f019556f50151c9a838dd5b..4b0533c8e6970d0883562c5db277d480aa0927d4 100644 (file)
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -147,3 +147,11 @@ Booting OS
 
    os/plan9
    os/vxworks
+
+File Systems
+------------
+
+.. toctree::
+   :maxdepth: 1
+
+   filesystems/ext4