[PATCH v3 30/31] bootstd: doc: Add documentation

[Simon Glass]

Hi,

On Fri, 21 Jan 2022 at 08:08, Tom Rini <trini at konsulko.com> wrote:
>
> On Wed, Jan 19, 2022 at 12:39:03PM +0100, Heinrich Schuchardt wrote:
> > On 1/19/22 02:43, Simon Glass wrote:
> > > Add documentation for this feature, including the commands and full
> > > devicetree bindings.
> > >
> > > Signed-off-by: Simon Glass <sjg at chromium.org>
> > > ---
> > >
> > > Changes in v3:
> > > - Update docs for "bootmeths" and "boot_targets" env vars
> > >
> > >   MAINTAINERS                           |   4 +
> > >   doc/develop/bootstd.rst               | 638 ++++++++++++++++++++++++++
> > >   doc/develop/distro.rst                |   3 +
> > >   doc/develop/index.rst                 |   1 +
> > >   doc/device-tree-bindings/bootdev.txt  |  18 +
> > >   doc/device-tree-bindings/bootmeth.txt |  31 ++
> > >   doc/device-tree-bindings/bootstd.txt  |   8 +
> > >   doc/usage/bootdev.rst                 | 135 ++++++
> > >   doc/usage/bootflow.rst                | 427 +++++++++++++++++
> > >   doc/usage/bootmeth.rst                | 108 +++++
> > >   doc/usage/index.rst                   |   3 +
> > >   11 files changed, 1376 insertions(+)
> > >   create mode 100644 doc/develop/bootstd.rst
> > >   create mode 100644 doc/device-tree-bindings/bootmeth.txt
> > >   create mode 100644 doc/usage/bootdev.rst
> > >   create mode 100644 doc/usage/bootflow.rst
> > >   create mode 100644 doc/usage/bootmeth.rst
> > >
> > > diff --git a/MAINTAINERS b/MAINTAINERS
> > > index 8ad70d3d968..c2af8ada3c9 100644
> > > --- a/MAINTAINERS
> > > +++ b/MAINTAINERS
> > > @@ -669,6 +669,10 @@ F:     boot/bootmeth*.c
> > >   F:        boot/bootstd.c
> > >   F:        cmd/bootdev.c
> > >   F:        cmd/bootflow.c
> > > +F: doc/develop/bootstd.rst
> > > +F: doc/usage/bootdev.rst
> > > +F: doc/usage/bootflow.rst
> > > +F: doc/usage/bootmeth.rst
> > >   F:        drivers/mmc/mmc_bootdev.c
> > >   F:        include/bootdev.h
> > >   F:        include/bootflow.h
> > > diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst
> > > new file mode 100644
> > > index 00000000000..1b65a806efb
> > > --- /dev/null
> > > +++ b/doc/develop/bootstd.rst
> > > @@ -0,0 +1,638 @@
> > > +.. SPDX-License-Identifier: GPL-2.0+:
> > > +
> > > +U-Boot Standard Boot
> > > +====================
> > > +
> > > +Introduction
> > > +------------
> > > +
> > > +Standard boot provides a built-in way for U-Boot to automatically boot
> > > +an Operating System without custom scripting and other customisation. It
> > > +introduces the following concepts:
> > > +
> > > +   - bootdev  - a device which can hold or access a distro (e.g. MMC, Ethernet)
> > > +   - bootmeth - a method to scan a bootdev to find bootflows (e.g. distro boot)
> > > +   - bootflow - a description of how to boot (provided by the distro)
> > > +
> > > +For Linux, the distro (Linux distribution, e.g. Debian, Fedora) is responsible
> > > +for creating a bootflow for each kernel combination that it wants to offer.
> >
> > This gets it completely wrong. There is one standardized boot flow: UEFI.
> > All major distros support this. U-Boot has to offer UEFI booting out of the
> > box.
>
> I want to jump up and down and emphasize this part as well.  While I
> believe our UEFI bootmgr is still missing the normal scan code, that's
> something that has been promised to be implemented.  And that turns the
> bootcmd for platforms that just want to support modern off the shelf
> distros in to something fairly small.

Sigh...

UEFI is a bootflow in this model, one of many. If we don't support the
others, then U-Boot is not U-Boot anymore, it is just EFI Boot.

If we get EFI bootmgr going, then are you saying you want to disable
everything else?

You say 'major distros' but there are many that don't use it,
particularly in the embedded space. I'll go out on a limb and say that
the vast majority of embedded devices in the world don't use it. Are
you really saying we should drop support for everything else? Even the
distro stuff supports other options.

Also Heinrich your comment says 'U-Boot has to offer UEFI booting out
of the box'. Which bit of this series is in conflict with that? What
exactly is "completely wrong" ?? Is it just the wording that is
confusing?

??

Regards,
Simon