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

Sat Jan 22 12:44:52 CET 2022

> Date: Fri, 21 Jan 2022 23:05:34 +0100
> From: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> 
> On 1/21/22 20:17, Simon Glass wrote:
> > Hi Mark,
> > 
> > On Fri, 21 Jan 2022 at 11:23, Mark Kettenis <mark.kettenis at xs4all.nl> wrote:
> >>
> >>> From: Simon Glass <sjg at chromium.org>
> >>> Date: Fri, 21 Jan 2022 09:53:37 -0700
> >>>
> >>> 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.
> 
> You could set kaslr-seed in the device-tree using one of our hardware 
> RNG drivers. This would allow address randomization when booting via the 
> legacy entry point.

No quite.  Setting kaslr-seed will only do randomization of virtual
addresses.  But because the bottom 21 bits of the virtual address have
to match the bottom 21 bits of the physical address, which isn't
randomized, the number of randomized bits in your virtual addresses
will be somewhat limited.  With EFISTUB booting, physical addresses
are also randomized giving you more randomized bits in your virtual
addresses.  This is what ardb pointed out when we were discussing
Ilias's patch to remove kaslr-seed from the device tree.

This points out another downside of legacy booting.  As far as I can
tell you have to run the kaslrseed command to set kaslr-seed in the
device tree.  Unless it is already set by a prior boot stage of
course.  But none of the boards in the U-Boot tree enable that
command.  Whereas support for EFI_RNG_PROTOCOL is enabled
automatically if DM_RNG is enabled.

> >>>
> >>> 'legacy'? Isn't it just a case of relocating the kernel to a random
> >>> address? I'm pretty sure U-Boot can do that :-)
> 
> Instead of 'legacy' you could call it vendor lock in.
> If a firmware does not support UEFI you cannot boot other operating 
> systems than Linux, e.g. BSD.

Well yes.  That is why I keep fighting for enabling EFI_LOADER support
for as many arm/arm64/riscv64 boards as possible. ;)

> >> The problem is that the legacy boot protocol for the Linux arm64
> >> kernel requires a 2MB aligned kernel base, which reduces the number of
> >> randomized bits.  That also means that virtual addresses are not fully
> >> randomized as the kernel uses large mappings to map itself.  My
> >> understanding is that the UEFI stub can relocate the kernel to any 64K
> >> aligned address.  I suppose it is possible to add code to achieve the
> >> same thing for the legacy boot path, but I don't think the arm64
> >> maintainers are really interested in doing that.
> >>
> >> But yes, U-Boot should certainly try to load arm64 kernels at a random
> >> address instead hardcoding the load address ;)