All of lore.kernel.org
 help / color / mirror / Atom feed
From: Randy Dunlap <rdunlap@infradead.org>
To: Masami Hiramatsu <mhiramat@kernel.org>,
	Steven Rostedt <rostedt@goodmis.org>
Cc: 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: Sat, 18 Jan 2020 10:28:40 -0800	[thread overview]
Message-ID: <7823298a-88e6-4625-ff10-94b00f7963cb@infradead.org> (raw)
In-Reply-To: <157867230658.17873.9309879174829924324.stgit@devnote2>

Hi,

Editorial comments/corrections below...

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

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

                                  booting

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

               administrators

> +
> +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].)

> +
> +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 '{'?

> +
> +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

> +
> +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/

> +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

> +
> + # 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

> +======================
> +
> +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)

> +
> + 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

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

[confusing above]

> +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,

> +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.
-- 
~Randy

  reply	other threads:[~2020-01-18 18:29 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 [this message]
2020-01-19 13:36     ` Masami Hiramatsu
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=7823298a-88e6-4625-ff10-94b00f7963cb@infradead.org \
    --to=rdunlap@infradead.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=mhiramat@kernel.org \
    --cc=mingo@redhat.com \
    --cc=namhyung@kernel.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.