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-mibo...@gmail.com/
>
> Signed-off-by: Tony Dinh <mibo...@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
