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

[Tony Dinh]

Hi Anshul,

On Fri, Sep 12, 2025 at 6:23 AM Anshul Dalal <anshuld at ti.com> wrote:
>
> 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

Thanks! I'll send V2 patch.

All the best,
Tony