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

[Simon Glass]

Hi Mark,

On Fri, 21 Jan 2022 at 09:03, Mark Kettenis <mark.kettenis at xs4all.nl> wrote:
>
> > From: Simon Glass <sjg at chromium.org>
> > Date: Fri, 21 Jan 2022 08:20:17 -0700
> >
> > 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.
>
> And U-Boot supports a wide variety of CPUs and some of those don't
> even have official UEFI support.
>
> However, on arm64 (and possibly riscv64) even the embedded folks
> should seriously consider using the UEFI bootflow.  Linux now supports
> physical address randomization when loaded via the UEFI stub, which is
> something that can't really be implemented using the legacy boot path.
> Note that you don't have to use a separate UEFI bootloader as U-Boot
> can directly boot kernels with the UEFI stub.

'legacy'? Isn't it just a case of relocating the kernel to a random
address? I'm pretty sure U-Boot can do that :-)

Re direct boot, the issue seems to me that distros really want to use
grub. I think a lot of people talk about direct boot, but it doesn't
seem to be happening?

>
> > 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?
>
> Possibly.  The documentation seems to suggest that OSes have to
> specify a bootflow for U-Boot.  Whereas one of the main advantages of
> the UEFI bootflow is that this allows OSes not to care whether we're
> booted by U-Boot, EDK2 or a closed source firmware implementation.  I
> think the docs should say that the bootflow can be customized by an
> OS, but that in general this isn't necessary.

The definition of a bootflow is pretty broad. In the case of grub, it
isn't even visible to U-Boot so there is a bootflow ('bootmeth_efi' in
this series) but no actual file (grub.cfg) is visible to U-Boot other
than the grub.efi that it boots. But if grub is not used, then the
bootflow may be a file.

We could perhaps use the next U-Boot contributor call to discuss it.

Regards,
Simon