Hi Heinrich,
On Mon, 15 Jul 2024 at 22:58, Heinrich Schuchardt <xypron.g...@gmx.de> wrote:
>
> On 7/15/24 12:13, Simon Glass wrote:
> > Before adding more files, move the bootstd docs into a new directory,
> > with an index.
> >
> > Signed-off-by: Simon Glass <s...@chromium.org>
> > ---
> >
> > MAINTAINERS | 2 +-
> > doc/board/starfive/milk-v_mars_cm.rst | 2 +-
> > doc/develop/board_best_practices.rst | 2 +-
> > doc/develop/bootstd/index.rst | 9 +++++++++
> > doc/develop/{bootstd.rst => bootstd/overview.rst} | 14 +++++++-------
> > doc/develop/index.rst | 2 +-
> > doc/usage/cmd/bootdev.rst | 2 +-
> > doc/usage/cmd/bootflow.rst | 2 +-
> > doc/usage/cmd/bootmeth.rst | 2 +-
> > doc/usage/environment.rst | 2 +-
> > 10 files changed, 24 insertions(+), 15 deletions(-)
> > create mode 100644 doc/develop/bootstd/index.rst
> > rename doc/develop/{bootstd.rst => bootstd/overview.rst} (99%)
> >
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 9bee9284cca..86b830aa997 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -927,7 +927,7 @@ F: boot/bootmeth*.c
> > F: boot/bootstd.c
> > F: cmd/bootdev.c
> > F: cmd/bootflow.c
> > -F: doc/develop/bootstd.rst
> > +F: doc/develop/bootstd/
> > F: doc/usage/bootdev.rst
> > F: doc/usage/bootflow.rst
> > F: doc/usage/bootmeth.rst
> > diff --git a/doc/board/starfive/milk-v_mars_cm.rst
> > b/doc/board/starfive/milk-v_mars_cm.rst
> > index b31de6043bb..52d4e5e9098 100644
> > --- a/doc/board/starfive/milk-v_mars_cm.rst
> > +++ b/doc/board/starfive/milk-v_mars_cm.rst
> > @@ -89,7 +89,7 @@ provide a default value.
> >
> > The variable *$fdtfile* is used in the boot process to automatically load
> > a device-tree provided by the operating system. For details of the boot
> > -process refer to the :doc:`U-Boot Standard Boot <../../../develop/bootstd>`
> > +process refer to the :doc:`/develop/bootstd/index`
> > description.
> >
> > Boot source selection
> > diff --git a/doc/develop/board_best_practices.rst
> > b/doc/develop/board_best_practices.rst
> > index f44401eab7d..09632c80ce7 100644
> > --- a/doc/develop/board_best_practices.rst
> > +++ b/doc/develop/board_best_practices.rst
> > @@ -7,7 +7,7 @@ In addition to the regular best practices such as using
> > :doc:`checkpatch` and
> > following the :doc:`docstyle` and the :doc:`codingstyle` there are some
> > things
> > which are specific to creating a new board port.
> >
> > -* Implement :doc:`bootstd` to ensure that most operating systems will be
> > +* Implement :doc:`bootstd/index` to ensure that most operating systems
> > will be
> > supported by the platform.
> >
> > * The platform defconfig file must be generated via `make savedefconfig`.
> > diff --git a/doc/develop/bootstd/index.rst b/doc/develop/bootstd/index.rst
> > new file mode 100644
> > index 00000000000..f4f87c7787c
> > --- /dev/null
> > +++ b/doc/develop/bootstd/index.rst
> > @@ -0,0 +1,9 @@
> > +.. SPDX-License-Identifier: GPL-2.0+:
> > +
> > +Standard Boot
> > +=============
> > +
> > +.. toctree::
> > + :maxdepth: 2
> > +
> > + overview
> > diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd/overview.rst
> > similarity index 99%
> > rename from doc/develop/bootstd.rst
> > rename to doc/develop/bootstd/overview.rst
> > index 34631089ae0..761f61a573b 100644
> > --- a/doc/develop/bootstd.rst
> > +++ b/doc/develop/bootstd/overview.rst
> > @@ -1,7 +1,7 @@
> > .. SPDX-License-Identifier: GPL-2.0+:
> >
> > -U-Boot Standard Boot
> > -====================
> > +Standard Boot Overview
> > +======================
> >
>
>
>
> The text is not optimized for readability, e.g.
>
> "- bootdev - a device which can hold or access a distro (e.g. MMC,
> Ethernet)"
>
> Please, consistently replace the non-words in the boot standard
> documentation:
>
> %s/bootdev/boot device/
> %s/bootmeth/boot method/
> %s/bootflow/boot flow/
I do want to keep the terms, It is easy to search for bootdev or
bootmeth in the code and docs. Once people learn what they mean it is
pretty simple.
>
> "distro" isn't a dictionary word either. Do you mean operating system?
I mean a linux distro, in the sense that 'distro boot' uses it.
> That term would still not catch what a boot device is:
>
> The boot device is the device that holds the next boot stage.
>
> This could for instance be GRUB which in turn will offer a menu allowing
> to select one of multiple operating systems.
>
> Or that next boot stage could be an operating system kernel together
> with its initial ram disk and a device-tree.
This is covered to some extent at [1]. But what you are talking about
here is not covered - e.g. using GRUB. You could perhaps sent a patch
to [1] ?
>
> Best regards
>
> Heinrich
>
>
>
> > Introduction
> > ------------
> > @@ -17,7 +17,7 @@ introduces the following concepts:
> > 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.
> > These bootflows are stored on media so they can be discovered by U-Boot.
> > This
> > -feature is typically called `distro boot` (see :doc:`distro`) because it is
> > +feature is typically called `distro boot` (see :doc:`../distro`) because
> > it is
> > a way for distributions to boot on any hardware.
> >
> > Traditionally U-Boot has relied on scripts to implement this feature. See
> > @@ -32,7 +32,7 @@ way to boot with U-Boot. The feature is extensible to
> > different Operating
> > Systems (such as Chromium OS) and devices (beyond just block and network
> > devices). It supports EFI boot and EFI bootmgr too.
> >
> > -Finally, standard boot supports the operation of :doc:`vbe`.
> > +Finally, standard boot supports the operation of :doc:`../vbe`.
> >
> > Bootflow
> > --------
> > @@ -427,16 +427,16 @@ Three commands are available:
> >
> > `bootdev`
> > Allows listing of available bootdevs, selecting a particular one and
> > - getting information about it. See :doc:`../usage/cmd/bootdev`
> > + getting information about it. See :doc:`/usage/cmd/bootdev`
> >
> > `bootflow`
> > Allows scanning one or more bootdevs for bootflows, listing available
> > bootflows, selecting one, obtaining information about it and booting
> > it.
> > - See :doc:`../usage/cmd/bootflow`
> > + See :doc:`/usage/cmd/bootflow`
> >
> > `bootmeth`
> > Allow listing of available bootmethds and setting the order in which
> > they
> > - are tried. See :doc:`../usage/cmd/bootmeth`
> > + are tried. See :doc:`/usage/cmd/bootmeth`
> >
> > .. _BootflowStates:
> >
> > diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> > index f9c4bf839ee..c0107a783fc 100644
> > --- a/doc/develop/index.rst
> > +++ b/doc/develop/index.rst
> > @@ -29,7 +29,7 @@ Implementation
> >
> > directories
> > bloblist
> > - bootstd
> > + bootstd/index
> > ci_testing
> > commands
> > config_binding
> > diff --git a/doc/usage/cmd/bootdev.rst b/doc/usage/cmd/bootdev.rst
> > index f759abab354..98a0f43c580 100644
> > --- a/doc/usage/cmd/bootdev.rst
> > +++ b/doc/usage/cmd/bootdev.rst
> > @@ -22,7 +22,7 @@ Description
> > The `bootdev` command is used to manage bootdevs. It can list available
> > bootdevs, select one and obtain information about it.
> >
> > -See :doc:`../../develop/bootstd` for more information about bootdevs in
> > general.
> > +See :doc:`/develop/bootstd/index` for more information about bootdevs in
> > general.
> >
> >
> > bootdev list
> > diff --git a/doc/usage/cmd/bootflow.rst b/doc/usage/cmd/bootflow.rst
> > index 6519e4880a9..5d41fe37a7a 100644
> > --- a/doc/usage/cmd/bootflow.rst
> > +++ b/doc/usage/cmd/bootflow.rst
> > @@ -26,7 +26,7 @@ Description
> > The `bootflow` command is used to manage bootflows. It can scan bootdevs
> > to
> > locate bootflows, list them and boot them.
> >
> > -See :doc:`../../develop/bootstd` for more information.
> > +See :doc:`/develop/bootstd/index` for more information.
> >
> > Note that `CONFIG_BOOTSTD_FULL` (which enables `CONFIG_CMD_BOOTFLOW_FULL)
> > must
> > be enabled to obtain full functionality with this command. Otherwise, it
> > only
> > diff --git a/doc/usage/cmd/bootmeth.rst b/doc/usage/cmd/bootmeth.rst
> > index bac9fdf85cd..c3d2ec1574b 100644
> > --- a/doc/usage/cmd/bootmeth.rst
> > +++ b/doc/usage/cmd/bootmeth.rst
> > @@ -21,7 +21,7 @@ Description
> > The `bootmeth` command is used to manage bootmeths. It can list them and
> > change
> > the order in which they are used.
> >
> > -See :doc:`../../develop/bootstd` for more information.
> > +See :doc:`/develop/bootstd/index` for more information.
> >
> >
> > .. _bootmeth_order:
> > diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst
> > index 7d4b448cb30..cc33d3ec0f2 100644
> > --- a/doc/usage/environment.rst
> > +++ b/doc/usage/environment.rst
> > @@ -100,7 +100,7 @@ to add environment variables.
> >
> > Board maintainers are encouraged to migrate to the text-based environment
> > as it
> > is easier to maintain. The distro-board script still requires the
> > old-style
> > -environments, so use :doc:`../develop/bootstd` instead.
> > +environments, so use :doc:`/develop/bootstd/index` instead.
> >
> >
> > List of environment variables
>
[1] https://docs.u-boot.org/en/latest/develop/bootstd.html#bootdev
