[PATCH 03/13] doc: Add a description for bootmeth_extlinux

[Simon Glass]

Hi Heinrich,

On Mon, 15 Jul 2024 at 23:30, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Add documentation for the extlinux bootmeth.
> >
> > Signed-off-by: Simon Glass <sjg at chromium.org>
> > ---
> >
> >   doc/develop/bootstd/extlinux.rst | 27 +++++++++++++++++++++++++++
> >   doc/develop/bootstd/index.rst    |  1 +
> >   doc/develop/bootstd/overview.rst |  2 +-
> >   3 files changed, 29 insertions(+), 1 deletion(-)
> >   create mode 100644 doc/develop/bootstd/extlinux.rst
> >
> > diff --git a/doc/develop/bootstd/extlinux.rst b/doc/develop/bootstd/extlinux.rst
> > new file mode 100644
> > index 00000000000..28490f38899
> > --- /dev/null
> > +++ b/doc/develop/bootstd/extlinux.rst
> > @@ -0,0 +1,27 @@
> > +.. SPDX-License-Identifier: GPL-2.0+:
> > +
> > +Extlinux Bootmeth
> > +=================
> > +
> > +`Extlinux <https://uapi-group.org/specifications/specs/boot_loader_specification>`_
> > +(sometimes called syslinux) allows U-Boot to provide a menu of possible
>
> %s/possible/available/
>
> > +Operating Systems from which the user can choose.
>
> %s/Operating Systems/operating systems/
>
> > +
> > +U-Boot includes a parser for the `extlinux.conf` file. It consists primarily of
> > +a list of named OSes along with the kernel, initial ramdisk and other settings.
>
> Please, avoid abbreviations.
>
> %s/OSes/operating systems/
>
> > +The file is stored in the `extlinux/` subdirectory, possibly under the `boot/`
> > +subdirectory. This list of prefixes ({"/", "/boot"} by default) can be selected
> > +with the `filename-prefixes` property in the bootstd device.
>
> %s/bootstd/boot standard/
>
> > +
> > +Note that PXE (Preboot eXecution-Environment) uses the same file format, but in
> > +a network context.
> > +
> > +When invoked on a bootdev, this bootmeth searches for the file and creates a
>
> Please, replace throughout the text:
>
> %s/bootdev/boot device/
> %s/bootmeth/boot method/
>
>
> > +bootflow if found.
>
> %s/bootflow/bootflow/
>
> > +
> > +When the bootflow is booted, the bootmeth calls pxe_setup_ctx() to set up the
> > +context, then pxe_process() to process the file. Depending on the contents, this
> > +may boot an OS or provide a list of options to the user, perhaps with a timeout.
>
> %/OS/operating system/
>
> > +
> > +The compatible string "u-boot,extlinux" is used for the driver. The driver is
> > +automatically instantiated if there are no bootmeth drivers in the devicetree.
>
> Device-tree never contain boot method drivers. Do you mean:
>
> If no boot method driver is selected by a compatible string in the
> device-tree and CONFIG_BOOTMETH_EXTLINUX=y, the extlinux boot method
> driver is enabled by default.

Not quite. The devicetree can specify the bootmeth devices, iwc the
automatic binding is not enabled. I'll add a note to the main docs and
drop this.

>
> Please, mention that the driver is only available if
> CONFIG_BOOTMETH_EXTLINUX=y.
>
> > diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> > index f4f87c7787c..5bbb3d633a3 100644
> > --- a/doc/develop/bootstd/index.rst
> > +++ b/doc/develop/bootstd/index.rst
> > @@ -7,3 +7,4 @@ Standard Boot
> >      :maxdepth: 2
> >
> >      overview
> > +   extlinux
> > diff --git a/doc/develop/bootstd/overview.rst b/doc/develop/bootstd/overview.rst
> > index 761f61a573b..086a0b1281d 100644
> > --- a/doc/develop/bootstd/overview.rst
> > +++ b/doc/develop/bootstd/overview.rst
> > @@ -412,7 +412,7 @@ Available bootmeth drivers
> >
> >   Bootmeth drivers are provided for:
>
> %s/Bootmeth/Boot method/
>
> >
> > -   - extlinux / syslinux boot from a disk
>  > +   - :doc:`extlinux / syslinux <extlinux>` boot from a disk
>
> After "provided for:" I would expect "booting from a storage device".
>
> You can't use the infinitive here. The days of disks are counted.
>
> Best regards
>
> Heinrich
>
> >      - extlinux boot from a network (PXE)
> >      - U-Boot scripts from disk, network or SPI flash
> >      - EFI boot using bootefi from disk
>

Regards,
Simon