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
next prev parent 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 boot config 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 \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).