[PATCH] doc: Convert README.commands.spl to rST

[Tom Rini]

On Sat, Sep 13, 2025 at 06:49:46PM +0200, Heinrich Schuchardt wrote:
> Am 13. September 2025 17:18:07 MESZ schrieb Tom Rini <trini at konsulko.com>:
> >On Sat, Sep 13, 2025 at 02:32:26AM +0200, Heinrich Schuchardt wrote:
> >> On 9/13/25 01:02, Tom Rini wrote:
> >> > This converts the existing README.commands.spl file to rST as
> >> > doc/usage/cmd/spl.rst and adds it to the command index. Minimal
> >> > rewording is done to the previous contents, to make it fit better with
> >> > the overall style of documentation now.
> >> > 
> >> > Signed-off-by: Tom Rini <trini at konsulko.com>
> >> > ---
> >> > Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
> >> > ---
> >> >   doc/README.commands.spl | 31 --------------------------
> >> >   doc/usage/cmd/spl.rst   | 48 +++++++++++++++++++++++++++++++++++++++++
> >> >   doc/usage/index.rst     |  1 +
> >> >   3 files changed, 49 insertions(+), 31 deletions(-)
> >> >   delete mode 100644 doc/README.commands.spl
> >> >   create mode 100644 doc/usage/cmd/spl.rst
> >> > 
> >> > diff --git a/doc/README.commands.spl b/doc/README.commands.spl
> >> > deleted file mode 100644
> >> > index ecfd3ca9ee58..000000000000
> >> > --- a/doc/README.commands.spl
> >> > +++ /dev/null
> >> > @@ -1,31 +0,0 @@
> >> > -The spl command is used to export a boot parameter image to RAM. Later
> >> > -it may implement more functions connected to the SPL.
> >> > -
> >> > -SUBCOMMAND EXPORT
> >> > -To execute the command everything has to be in place as if bootm should be
> >> > -used. (kernel image, initrd-image, fdt-image etc.)
> >> > -
> >> > -export has two subcommands:
> >> > -	atags: exports the ATAGS
> >> > -	fdt: exports the FDT
> >> > -
> >> > -Call is:
> >> > -spl export <fdt|atags> [kernel_addr] [initrd_addr] [fdt_addr if fdt]
> >> > -
> >> > -
> >> > -TYPICAL CALL
> >> > -
> >> > -on OMAP3:
> >> > -nandecc hw
> >> > -nand read 0x82000000 0x280000 0x400000	/* Read kernel image from NAND*/
> >> > -spl export atags			/* export ATAGS */
> >> > -nand erase 0x680000 0x20000		/* erase - one page */
> >> > -nand write 0x80000100 0x680000 0x20000	/* write the image - one page */
> >> > -
> >> > -call with FDT:
> >> > -nandecc hw
> >> > -nand read 0x82000000 0x280000 0x400000	/* Read kernel image from NAND*/
> >> > -tftpboot 0x80000100 devkit8000.dtb /* Read fdt */
> >> > -spl export fdt 0x82000000 - 0x80000100	/* export FDT */
> >> > -nand erase 0x680000 0x20000		/* erase - one page */
> >> > -nand write <adress shown by spl export> 0x680000 0x20000
> >> > diff --git a/doc/usage/cmd/spl.rst b/doc/usage/cmd/spl.rst
> >> > new file mode 100644
> >> > index 000000000000..59471c65a623
> >> > --- /dev/null
> >> > +++ b/doc/usage/cmd/spl.rst
> >> > @@ -0,0 +1,48 @@
> >> > +.. SPDX-License-Identifier: GPL-2.0+:
> >> 
> >> %s/GPL-2.0+/GPL-2.0-OR-LATER/
> >> 
> >> Cf. https://spdx.org/licenses/GPL-2.0-or-later.html
> >
> >Yes, and it's not a hard requirement to use the new tag, checkpatch.pl
> >doesn't even complain. I got this from the existing command I copied,
> >FWIW.
> >
> >> 
> >> > +
> >> > +.. index::
> >> > +   single: spl (command)
> >> > +
> >> > +spl command
> >> > +===========
> >> > +
> >> > +Synopsis
> >> > +--------
> >> > +
> >> > +::
> >> > +
> >> > +    spl export <fdt|atags> [kernel_addr] [initrd_addr] [fdt_addr if fdt]
> >> 
> >> Those brackets cannot be correct. I definitively cannot remove the
> >> kernel_addr and provide an initrd_addr instead. Do you mean:
> >> 
> >> spl export <fdt|atags> [kernel_addr [initrd_addr [fdt_addr if fdt]]]
> >
> >It's what the command itself says currently, however.
> >
> >I'd be happy to do a follow-up patch to fix both.
> 
> I am fine with the current patch if you supply the follow up.  

OK. But I also think that based on some of your questions, the first
step is to just rip out ATAGS from here. We have zero cases in tree of
ATAGS and SPL_OS_BOOT support, and this is an extremely legacy case.
Deleting that will make things a bit clearer overall. The next part is
that yes, two sentences doesn't explain what's going on here well if you
don't already know what's going on here.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20250915/ecc74fb7/attachment.sig>