Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu <mhiramat@kernel.org>]

On Thu, 27 Feb 2020 20:50:19 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi,
> A few more comments for you:
> 
> On 2/26/20 11:25 PM, Masami Hiramatsu wrote:
> > Update boot configuration documentation.
> > 
> >  - Not using "config" abbreviation but configuration or description.
> >  - Rewrite descriptions of node and its maxinum number.
> >  - Add a section of use cases of boot configuration.
> >  - Move how to use bootconfig to earlier section.
> >  - Fix some typos, indents and format mistakes.
> > 
> > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > ---
> >  Documentation/admin-guide/bootconfig.rst |  172 +++++++++++++++++++-----------
> >  Documentation/trace/boottime-trace.rst   |    2 
> >  2 files changed, 112 insertions(+), 62 deletions(-)
> > 
> > diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> > index cf2edcd09183..4bac98250bc0 100644
> > --- a/Documentation/admin-guide/bootconfig.rst
> > +++ b/Documentation/admin-guide/bootconfig.rst
> > @@ -11,19 +11,98 @@ Boot Configuration
> >  Overview
> >  ========
> >  
> > -The boot configuration expands the current kernel command line to support
> > +Boot configuration expands the current kernel command line to support
> >  additional key-value data when booting the kernel in an efficient way.
> 
>                 maybe      s/when/while/

Ah, right.

> 
> > -This allows administrators to pass a structured-Key config file.
> > +This allows administrators to pass a structured-Key configuration file
> > +as a way to supplement the kernel command line to pass system boot parameters.
> >  
> > -Config File Syntax
> > -==================
> > +Compared with the kernel command line, the boot configuration can provide
> > +scalability (up to 32 KiB configurations), readability (structured
> 
> This makes it sound like bootconfig supports 32 thousand configurations, but
> (I think) it allows up to 32 KiB of configuration data.

OK, I'll add "data".

> 
> > +configuration with comments) and compact expression of option groups.
> > +
> > +When to Use the Boot Configuration?
> > +-----------------------------------
> > +
> > +The boot configuration supports kernel command line options and init daemon
> > +boot options. All sub-keys under "kernel" root key are passed as a part of
> > +kernel command line [1]_, and one under "init" root key are passed as a part
> 
>                                  ones  {or those}

OK.

> 
> > +of init command line. For example, ::
> > +
> > +   root=UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82 ro quiet splash console=ttyS0,115200n8 console=tty0
> > +
> > +This can be written as following boot configuration file.::
> > +
> > +   kernel {
> > +      root = "UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82" # nvme0n1p3
> > +      ro       # mount rootfs as read only
> > +      quiet    # No console log
> > +      splash   # show splash image on boot screen
> > +      console = "ttyS0,115200n8" # 1st console to serial device
> > +      console += tty0            # add 2nd console
> > +   }
> > +
> > +If you think that kernel/init options becomes too long to write in boot-loader
> > +configuration file or want to comment on each options, you can use this
> 
>                                          on each option,

Oops, OK. 

> 
> > +boot configuration. If unsure, you can still continue to use the legacy
> > +kernel command line.
> > +
> > +Also, some subsystem may depend on the boot configuration, and it has own
> > +root key. For example, ftrace boot-time tracer uses "ftrace" root key to
> > +describe their options [2]_. In this case, you need to use the boot
> 
>             its

OK

Thank you!

> 
> > +configuration.
> > +
> > +.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> > +.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`
> 
> 
> -- 
> ~Randy
> 


-- 
Masami Hiramatsu <mhiramat@kernel.org>