[PATCH] doc: usage: Add File System section and Ext4 documentation

[Anshul Dalal]

Hi Tony,

On Fri Sep 12, 2025 at 10:19 AM IST, Tony Dinh wrote:
> 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 at gmail.com>
> ---
>
>  .../filesystems/ext4.rst}                     | 55 +++++++++++++++----
>  doc/usage/index.rst                           |  8 +++
>  2 files changed, 53 insertions(+), 10 deletions(-)
>  rename doc/{README.ext4 => usage/filesystems/ext4.rst} (79%)
>
> diff --git a/doc/README.ext4 b/doc/usage/filesystems/ext4.rst
> similarity index 79%
> rename from doc/README.ext4
> rename to doc/usage/filesystems/ext4.rst
> index ca9f19953d2..18e45045344 100644
> --- 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:
>  
> -  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,10 +72,15 @@ 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:
>  
> +::
> +
>  	UBOOT #help
>  	...
>  	ext4load- load binary file from a Ext4 file system
> @@ -65,6 +91,8 @@ Some sample commands to test ext4 support:
>  
>  2. To list the files in an ext4-formatted partition, run:
>  
> +::
> +
>  	ext4ls <interface> <dev[:part]> [directory]
>  
>  	For example:
> @@ -72,6 +100,8 @@ Some sample commands to test ext4 support:
>  
>  3. To read and load a file from an ext4-formatted partition to RAM, run:
>  
> +::
> +
>  	ext4load <interface> <dev[:part]> [addr] [filename] [bytes]
>  

The command usage has updated to:

ext4load <interface> [<dev[:part]> [addr [filename [bytes [pos]]]]]

>  	For example:
> @@ -79,16 +109,21 @@ Some sample commands to test ext4 support:
>  
>  4. To write a file to an ext4-formatted partition.
>  
> +::
> +
>  	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]
>  

This is an outdated format for ext4write, currently it's addr, filename
and then size.

>  	For example:
> -	UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 6183120
> -	(here 6183120 is the size of the file to be written)
> +	UBOOT #ext4write mmc 2:2 /boot/uImage 0x30007fc0 0x5E58D0
> +	(here 0x5E58D0 is the size of the file to be written,
> +	which was output by the ext4load command)
>  	Note: Absolute path is required for the file to be written

IMO, all the code blocks with U-Boot's console output in the 'Examples'
should only have text that user should expect during a regular usage,
all comments should be outside the code block as plain text. Like
follows:

The ``ext4write`` command can be used to write to an ext4
partition as follows:

::

	ext4write <interface> <dev[:part]> <addr> <absolute filename path> [sizebytes] [file offset]

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

::

  => ext4write mmc 2:2 0x82000000 /boot/sample_file.hex 0x100
  256 bytes written in 138 ms (1000 Bytes/s)

Regards,
Anshul