Re: [PATCH v6 09/22] Documentation: bootconfig: Add a doc for extended boot config

[Masami Hiramatsu <mhiramat@kernel.org>]

Hi Randy,

On Sat, 18 Jan 2020 10:28:40 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi,
> 
> Editorial comments/corrections below...

Thank you for your comments! This is very helpful for me.

> 
> On 1/10/20 8:05 AM, Masami Hiramatsu wrote:
> > Add a documentation for extended boot config under
> > admin-guide, since it is including the syntax of boot config.
> > 
> > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > ---
> >  Changes in v6:
> >   - Add a note about comment after value.
> >  Changes in v5:
> >   - Fix to insert bootconfig to TOC list alphabetically.
> >   - Add notes about avaliable characters in values.
> >   - Fix to use correct quotes (``) for .rst.
> >  Changes in v4:
> >   - Rename suppremental kernel command line to boot config.
> 
>              supplemental
> 
> >   - Update document according to the recent changes.
> >   - Add How to load it on boot.
> >   - Style bugfix.
> > ---
> >  Documentation/admin-guide/bootconfig.rst |  184 ++++++++++++++++++++++++++++++
> >  Documentation/admin-guide/index.rst      |    1 
> >  MAINTAINERS                              |    1 
> >  3 files changed, 186 insertions(+)
> >  create mode 100644 Documentation/admin-guide/bootconfig.rst
> > 
> 
> > diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> > new file mode 100644
> > index 000000000000..f7475df2a718
> > --- /dev/null
> > +++ b/Documentation/admin-guide/bootconfig.rst
> > @@ -0,0 +1,184 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +==================
> > +Boot Configuration
> > +==================
> > +
> > +:Author: Masami Hiramatsu <mhiramat@kernel.org>
> > +
> > +Overview
> > +========
> > +
> > +The boot configuration is expanding current kernel cmdline to support
> 
>                           expands the current kernel command line to support

OK.

> 
> > +additional key-value data when boot the kernel in an efficient way.
> 
>                                   booting

OK.

> 
> > +This allows adoministrators to pass a structured-Key config file.
> 
>                administrators

Oops. OK.

> 
> > +
> > +Config File Syntax
> > +==================
> > +
> > +The boot config 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 semi-colon (``;``) or newline (``\n``).
> > +For array value, array entries are separated by comma (``,``). ::
> > +
> > +KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
> 
> (just a note: spaces are OK here, unlike in kernel command line syntax [unless quoted].)

Yes.

> > +
> > +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 (``,``),
> > +hash (``#``) and closing brace (``}``).
> 
> what about opening brace '{'?

Good question! Since the bootconfig doesn't support anonymous key-word block,
opening brace doesn't become a delimiter. (So, the above explanation might better
use "except for *some* delimiters"...)

For example, following data should be wrong.

key = value { key2 = value }


> 
> > +
> > +If you want to use those delimiters in a value, you can use either double-
> > +quotes (``"VALUE"``) or single-quotes (``'VALUE'``) to quote it. Note that
> > +you can not escape these quotes.
> > +
> > +There can be a key which doesn't have value or has an empty value. Those keys
> > +are used for checking the key exists or not (like a boolean).
> 
> I would say:    checking if the key exists or not

OK.

> 
> > +
> > +Key-Value Syntax
> > +----------------
> > +
> > +The boot config file syntax allows user to merge partially same word keys
> > +by brace. For example::
> > +
> > + foo.bar.baz = value1
> > + foo.bar.qux.quux = value2
> > +
> > +These can be written also in::
> > +
> > + foo.bar {
> > +    baz = value1
> > +    qux.quux = value2
> > + }
> > +
> > +Or more shorter, written as following::
> > +
> > + foo.bar { baz = value1; qux.quux = value2 }
> > +
> > +In both styles, same key words are automatically merged when parsing it
> > +at boot time. So you can append similar trees or key-values.
> > +
> > +Comments
> > +--------
> > +
> > +The config syntax accepts shell-script style comments. The comments start
> 
> s/start/starting/

OK.

> 
> > +with hash ("#") until newline ("\n") will be ignored.
> > +
> > +::
> > +
> > + # comment line
> > + foo = value # value is set to foo.
> > + bar = 1, # 1st element
> > +       2, # 2nd element
> > +       3  # 3rd element
> > +
> > +This is parsed as below::
> > +
> > + foo = value
> > + bar = 1, 2, 3
> > +
> > +Note that you can not put a comment between value and delimiter(``,`` or
> > +``;``). This means following config has a syntax error ::
> > +
> > + key = 1 # comment
> > +       ,2
> > +
> > +
> > +/proc/bootconfig
> > +================
> > +
> > +/proc/bootconfig is a user-space interface of the boot config.
> > +Unlike /proc/cmdline, this file shows the key-value style list.
> > +Each key-value pair is shown in each line with following style::
> > +
> > + KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...]
> > +
> > +
> > +Boot Kernel With a Boot Config
> > +==============================
> > +
> > +Since the boot configuration file is loaded with initrd, it will be added
> > +to the end of the initrd (initramfs) image file. The Linux kernel decodes
> > +the last part of the initrd image in memory to get the boot configuration
> > +data.
> > +Because of this "piggyback" method, there is no need to change or
> > +update the boot loader and the kernel image itself.
> > +
> > +To do this operation, Linux kernel provides "bootconfig" command under
> > +tools/bootconfig, which allows admin to apply or delete the config file
> > +to/from initrd image. You can build it by follwoing command::
> 
>                                           by the following

Oops, a typo...

> 
> > +
> > + # make -C tools/bootconfig
> > +
> > +To add your boot config file to initrd image, run bootconfig as below
> > +(Old data is removed automatically if exists)::
> > +
> > + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
> > +
> > +To remove the config from the image, you can use -d option as below::
> > +
> > + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
> > +
> > +
> > +C onfig File Limitation
> 
>    Config

Oops

> 
> > +======================
> > +
> > +Currently the maximum config size size is 32KB and the total key-words (not
> > +key-value entries) must be under 1024 nodes.
> > +Note: this is not the number of entries but nodes, an entry must consume
> > +more than 2 nodes (a key-word and a value). So theoretically, it will be
> > +up to 512 key-value pairs. If keys contains 3 words in average, it can
> > +contain 256 key-value pairs. In most cases, the number of config items
> > +will be under 100 entries and smaller than 8KB, so it would be enough.
> > +If the node number exceeds 1024, parser returns an error even if the file
> > +size is smaller than 32KB.
> > +Anyway, since bootconfig command verifies it when appending a boot config
> > +to initrd image, user can notice it before boot.
> > +
> > +
> > +Bootconfig APIs
> > +===============
> > +
> > +User can query or loop on key-value pairs, also it is possible to find
> > +a root (prefix) key node and find key-values under that node.
> > +
> > +If you have a key string, you can query the value directly with the key
> > +using xbc_find_value(). If you want to know what keys exist in the SKC
> > +tree, you can use xbc_for_each_key_value() to iterate key-value pairs.
> > +Note that you need to use xbc_array_for_each_value() for accessing
> > +each arraies value, e.g.::
> 
>         array's
> (I think)

Yes, OK. 

> 
> > +
> > + vnode = NULL;
> > + xbc_find_value("key.word", &vnode);
> > + if (vnode && xbc_node_is_array(vnode))
> > +    xbc_array_for_each_value(vnode, value) {
> > +      printk("%s ", value);
> > +    }
> > +
> > +If you want to focus on keys which has a prefix string, you can use
> 
>                                       have

OK.

> 
> > +xbc_find_node() to find a node which prefix key words, and iterate
> 
> [confusing above]

Ah, it should be "to find a node by the prefix string,"


> 
> > +keys under the prefix node with xbc_node_for_each_key_value().
> > +
> > +But the most typical usage is to get the named value under prefix
> > +or get the named array under prefix as below::
> > +
> > + root = xbc_find_node("key.prefix");
> > + value = xbc_node_find_value(root, "option", &vnode);
> > + ...
> > + xbc_node_for_each_array_value(root, "array-option", value, anode) {
> > +    ...
> > + }
> > +
> > +This accesses a value of "key.prefix.option" and an array of
> > +"key.prefix.array-option".
> > +
> > +Locking is not needed, since after initialized, the config becomes readonly.
> 
>                                 after initialization,

OK.

> 
> > +All data and keys must be copied if you need to modify it.
> > +
> > +
> > +Functions and structures
> > +========================
> > +
> > +.. kernel-doc:: include/linux/bootconfig.h
> > +.. kernel-doc:: lib/bootconfig.c
> > +
> 
> HTH.

Thank you very much!

> -- 
> ~Randy


-- 
Masami Hiramatsu <mhiramat@kernel.org>