Re: [PATCH v5] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu <mhiramat@kernel.org>]

On Wed, 4 Mar 2020 23:01:21 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 3/4/20 10:44 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>
> 
> Hi Masami,
> 
> I swear that I am not trying to cause another version...

Oh, no problem. I'll go along with your reviews.

> 
> > ---
> > Changes in v5:
> >  - Elaborate the document.
> >  - Fix some typos.
> > Changes in v4:
> >  - Remove O= option from examples.
> > Changes in v3:
> >  - Specify that comments also count in size.
> >  - Fix a confusing sentence.
> >  - Add O=<builddir> to make command.
> > Changes in v2:
> >  - Fixes additional typos (Thanks Markus and Randy!)
> >  - Change a section title to "Tree Structured Key".
> > ---
> >  Documentation/admin-guide/bootconfig.rst |  201 +++++++++++++++++++-----------
> >  Documentation/trace/boottime-trace.rst   |    2 
> >  2 files changed, 131 insertions(+), 72 deletions(-)
> > 
> > diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> > index cf2edcd09183..3bfc9ddf68e1 100644
> > --- a/Documentation/admin-guide/bootconfig.rst
> > +++ b/Documentation/admin-guide/bootconfig.rst
> > @@ -11,25 +11,106 @@ Boot Configuration
> 
> > +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
> > +the kernel command line [1]_, and ones under "init" root key are passed as
> > +a part of the init daemon's 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
> 
>                                          become

OK.

> 
> > +configuration file or you want to comment on each option, the boot
> > +configuration may be suitable. If unsure, you can still continue to use the
> > +legacy kernel command line.
> 
> 
> > +Boot Configuration Syntax
> > +=========================
> > +
> > +The boot configuration syntax is a simple structured key-value. Each key
> > +consists of dot-connected-words, and key and value are connected by ``=``.
> > +The value has to be terminated by semicolon (``;``) or newline (``\n``).
> > +For an array, its entries are separated by comma (``,``). ::
> > +
> > +  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
> >  
> >  Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
> >  
> >  Each key word must contain only alphabets, numbers, dash (``-``) or underscore
> >  (``_``). And each value only contains printable characters or spaces except
> > -for delimiters such as semi-colon (``;``), new-line (``\n``), comma (``,``),
> > +for delimiters such as semicolon (``;``), new-line (``\n``), comma (``,``),
> 
>             usually called:                  newline

Yeah, I wonder why I have written so...

> 
> >  hash (``#``) and closing brace (``}``).
> >  
> >  If you want to use those delimiters in a value, you can use either double-
> 
> 
> >  Comments
> >  --------
> >  
> > -The config syntax accepts shell-script style comments. The comments starting
> > -with hash ("#") until newline ("\n") will be ignored.
> > -
> > -::
> > +The boot configuration accepts shell-script style comments. The comments,
> > +beginning with hash (``#``) continues until newline (``\n``), will be
> 
>                                and continuing until newline

OK.

> 
> > +skipped.::
> >  
> >   # comment line
> >   foo = value # value is set to foo.
> 
> 
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thank you!

-- 
Masami Hiramatsu <mhiramat@kernel.org>