All of lore.kernel.org
 help / color / mirror / Atom feed
From: Masami Hiramatsu <mhiramat@kernel.org>
To: Randy Dunlap <rdunlap@infradead.org>
Cc: Steven Rostedt <rostedt@goodmis.org>,
	Ingo Molnar <mingo@redhat.com>,
	Frank Rowand <frowand.list@gmail.com>,
	Namhyung Kim <namhyung@kernel.org>, Tim Bird <Tim.Bird@sony.com>,
	Jiri Olsa <jolsa@redhat.com>,
	Arnaldo Carvalho de Melo <acme@kernel.org>,
	Tom Zanussi <tom.zanussi@linux.intel.com>,
	Rob Herring <robh+dt@kernel.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Thomas Gleixner <tglx@linutronix.de>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Alexey Dobriyan <adobriyan@gmail.com>,
	Jonathan Corbet <corbet@lwn.net>,
	Linus Torvalds <torvalds@linux-foundation.org>,
	linux-doc@vger.kernel.org, linux-fsdevel@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH v6 09/22] Documentation: bootconfig: Add a doc for extended boot config
Date: Sun, 19 Jan 2020 22:36:20 +0900	[thread overview]
Message-ID: <20200119223620.059338427abadec036adc3fa@kernel.org> (raw)
In-Reply-To: <7823298a-88e6-4625-ff10-94b00f7963cb@infradead.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>

  reply	other threads:[~2020-01-19 13:36 UTC|newest]

Thread overview: 40+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-01-10 16:03 [PATCH v6 00/22] tracing: bootconfig: Boot-time tracing and Extra " Masami Hiramatsu
2020-01-10 16:03 ` [PATCH v6 01/22] bootconfig: Add Extra Boot Config support Masami Hiramatsu
2020-01-18 18:33   ` Randy Dunlap
2020-01-19 12:23     ` Masami Hiramatsu
2020-01-10 16:03 ` [PATCH v6 02/22] bootconfig: Load boot config from the tail of initrd Masami Hiramatsu
2020-01-10 16:03 ` [PATCH v6 03/22] tools: bootconfig: Add bootconfig command Masami Hiramatsu
2020-01-10 16:04 ` [PATCH v6 04/22] tools: bootconfig: Add bootconfig test script Masami Hiramatsu
2020-01-10 16:04 ` [PATCH v6 05/22] proc: bootconfig: Add /proc/bootconfig to show boot config list Masami Hiramatsu
2020-01-10 16:04 ` [PATCH v6 06/22] init/main.c: Alloc initcall_command_line in do_initcall() and free it Masami Hiramatsu
2020-01-10 16:04 ` [PATCH v6 07/22] bootconfig: init: Allow admin to use bootconfig for kernel command line Masami Hiramatsu
2020-01-10 16:04 ` [PATCH v6 08/22] bootconfig: init: Allow admin to use bootconfig for init " Masami Hiramatsu
2020-02-07 18:03   ` Kees Cook
2020-02-07 19:31     ` Arvind Sankar
2020-02-07 19:46     ` Steven Rostedt
2020-02-08  0:44       ` Kees Cook
2020-08-02  2:33       ` Arvind Sankar
2020-08-03 15:03         ` Masami Hiramatsu
2020-08-03 15:29           ` Arvind Sankar
2020-08-03 17:22             ` Steven Rostedt
2020-08-04  0:29               ` Masami Hiramatsu
2020-01-10 16:05 ` [PATCH v6 09/22] Documentation: bootconfig: Add a doc for extended boot config Masami Hiramatsu
2020-01-18 18:28   ` Randy Dunlap
2020-01-19 13:36     ` Masami Hiramatsu [this message]
2020-01-10 16:05 ` [PATCH v6 10/22] tracing: Apply soft-disabled and filter to tracepoints printk Masami Hiramatsu
2020-01-10 16:05 ` [PATCH v6 11/22] tracing: kprobes: Output kprobe event to printk buffer Masami Hiramatsu
2020-01-10 16:05 ` [PATCH v6 12/22] tracing: kprobes: Register to dynevent earlier stage Masami Hiramatsu
2020-01-10 16:05 ` [PATCH v6 13/22] tracing: Accept different type for synthetic event fields Masami Hiramatsu
2020-01-10 16:06 ` [PATCH v6 14/22] tracing: Add NULL trace-array check in print_synth_event() Masami Hiramatsu
2020-01-10 16:06 ` [PATCH v6 15/22] tracing/boot: Add boot-time tracing Masami Hiramatsu
2020-01-10 16:06 ` [PATCH v6 16/22] tracing/boot: Add per-event settings Masami Hiramatsu
2020-01-10 16:06 ` [PATCH v6 17/22] tracing/boot Add kprobe event support Masami Hiramatsu
2020-01-10 16:06 ` [PATCH v6 18/22] tracing/boot: Add synthetic " Masami Hiramatsu
2020-01-10 16:07 ` [PATCH v6 19/22] tracing/boot: Add instance node support Masami Hiramatsu
2020-01-10 16:07 ` [PATCH v6 20/22] tracing/boot: Add cpu_mask option support Masami Hiramatsu
2020-01-10 16:07 ` [PATCH v6 21/22] tracing/boot: Add function tracer filter options Masami Hiramatsu
2020-01-10 16:07 ` [PATCH v6 22/22] Documentation: tracing: Add boot-time tracing document Masami Hiramatsu
2020-01-18 18:14   ` Randy Dunlap
2020-01-19 14:15     ` Masami Hiramatsu
2020-01-19 14:20 ` [PATCH v6 00/22] tracing: bootconfig: Boot-time tracing and Extra boot config Masami Hiramatsu
2020-01-19 14:59   ` Steven Rostedt

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200119223620.059338427abadec036adc3fa@kernel.org \
    --to=mhiramat@kernel.org \
    --cc=Tim.Bird@sony.com \
    --cc=acme@kernel.org \
    --cc=adobriyan@gmail.com \
    --cc=akpm@linux-foundation.org \
    --cc=corbet@lwn.net \
    --cc=frowand.list@gmail.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=jolsa@redhat.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mingo@redhat.com \
    --cc=namhyung@kernel.org \
    --cc=rdunlap@infradead.org \
    --cc=robh+dt@kernel.org \
    --cc=rostedt@goodmis.org \
    --cc=tglx@linutronix.de \
    --cc=tom.zanussi@linux.intel.com \
    --cc=torvalds@linux-foundation.org \
    --subject='Re: [PATCH v6 09/22] Documentation: bootconfig: Add a doc for extended boot config' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.