linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Steven Rostedt <rostedt@goodmis.org>
To: linux-kernel@vger.kernel.org
Cc: Ingo Molnar <mingo@kernel.org>,
	Andrew Morton <akpm@linux-foundation.org>,
	Masami Hiramatsu <mhiramat@kernel.org>
Subject: [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config
Date: Tue, 14 Jan 2020 16:03:28 -0500	[thread overview]
Message-ID: <20200114210337.472405913@goodmis.org> (raw)
In-Reply-To: <20200114210316.450821675@goodmis.org>

From: Masami Hiramatsu <mhiramat@kernel.org>

Add a documentation for extended boot config under
admin-guide, since it is including the syntax of boot config.

Link: http://lkml.kernel.org/r/157867230658.17873.9309879174829924324.stgit@devnote2

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Steven Rostedt (VMware) <rostedt@goodmis.org>
---
 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
+additional key-value data when boot the kernel in an efficient way.
+This allows adoministrators to pass a structured-Key config file.
+
+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[...]][;]
+
+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 (``}``).
+
+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).
+
+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
+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::
+
+ # 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
+======================
+
+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.::
+
+ 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
+xbc_find_node() to find a node which prefix key words, and iterate
+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.
+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
+
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 4405b7485312..9e0f1e3fd152 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -64,6 +64,7 @@ configure specific aspects of kernel behavior to your liking.
    binderfs
    binfmt-misc
    blockdev/index
+   bootconfig
    braille-console
    btmrvl
    cgroup-v1/index
diff --git a/MAINTAINERS b/MAINTAINERS
index 903e8a7ed0bf..47873f2e6696 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15777,6 +15777,7 @@ F:	lib/bootconfig.c
 F:	fs/proc/bootconfig.c
 F:	include/linux/bootconfig.h
 F:	tools/bootconfig/*
+F:	Documentation/admin-guide/bootconfig.rst
 
 SUN3/3X
 M:	Sam Creasey <sammy@sammy.net>
-- 
2.24.1



  parent reply	other threads:[~2020-01-14 21:04 UTC|newest]

Thread overview: 69+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-01-14 21:03 [for-next][PATCH 00/26] tracing: Updates for 5.6 Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 01/26] perf: Make struct ring_buffer less ambiguous Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 02/26] tracing: Rename trace_buffer to array_buffer Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 03/26] tracing: Make struct ring_buffer less ambiguous Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 04/26] bootconfig: Add Extra Boot Config support Steven Rostedt
2020-02-06 11:54   ` Borislav Petkov
2020-02-06 14:41     ` Masami Hiramatsu
2020-02-06 17:20       ` Geert Uytterhoeven
2020-02-07  0:30         ` Masami Hiramatsu
2020-02-07  8:49           ` Geert Uytterhoeven
2020-02-07 13:17             ` Masami Hiramatsu
2020-02-07 14:28               ` [PATCH] bootconfig: Allocate xbc_nodes array dynamically Masami Hiramatsu
2020-02-06 17:58       ` [for-next][PATCH 04/26] bootconfig: Add Extra Boot Config support Borislav Petkov
2020-02-06 18:10         ` Randy Dunlap
2020-02-06 22:39           ` Steven Rostedt
2020-02-06 22:51             ` Borislav Petkov
2020-02-07  8:59             ` Geert Uytterhoeven
2020-02-07  2:46         ` Masami Hiramatsu
2020-02-07 11:41           ` Borislav Petkov
2020-02-07 15:06             ` Masami Hiramatsu
2020-02-10 11:25               ` Borislav Petkov
2020-02-10 15:10                 ` Masami Hiramatsu
2020-02-10 17:40                   ` Borislav Petkov
2020-02-11  2:02                     ` Masami Hiramatsu
2020-02-18 13:27                       ` Borislav Petkov
2020-02-18 17:57                         ` Steven Rostedt
2020-02-18 19:38                           ` Borislav Petkov
2020-02-19  2:26                             ` Masami Hiramatsu
2020-02-19  2:26                           ` Masami Hiramatsu
2020-02-19  2:26                         ` Masami Hiramatsu
2020-02-11  9:25                     ` Geert Uytterhoeven
2020-01-14 21:03 ` [for-next][PATCH 05/26] bootconfig: Load boot config from the tail of initrd Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 06/26] tools: bootconfig: Add bootconfig command Steven Rostedt
2020-02-07 13:02   ` Michael Ellerman
2020-02-07 13:39     ` Masami Hiramatsu
2020-02-07 13:55     ` [PATCH] tools/bootconfig: Fix wrong __VA_ARGS__ usage Masami Hiramatsu
2020-02-08 11:10       ` Michael Ellerman
2020-02-09  4:09         ` Masami Hiramatsu
2020-02-09 13:05         ` [PATCH] tools/bootconfig: Suppress non-error messages Masami Hiramatsu
2020-02-10  2:06           ` Michael Ellerman
2020-02-10  7:18             ` Masami Hiramatsu
2020-02-10  9:50               ` Michael Ellerman
2020-02-10  9:50       ` [PATCH] tools/bootconfig: Fix wrong __VA_ARGS__ usage Michael Ellerman
2020-02-10 17:07         ` Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 07/26] tools: bootconfig: Add bootconfig test script Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 08/26] proc: bootconfig: Add /proc/bootconfig to show boot config list Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 09/26] init/main.c: Alloc initcall_command_line in do_initcall() and free it Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 10/26] bootconfig: init: Allow admin to use bootconfig for kernel command line Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 11/26] bootconfig: init: Allow admin to use bootconfig for init " Steven Rostedt
2020-01-14 21:03 ` Steven Rostedt [this message]
2020-01-14 21:03 ` [for-next][PATCH 13/26] tracing: Apply soft-disabled and filter to tracepoints printk Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 14/26] tracing: kprobes: Output kprobe event to printk buffer Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 15/26] tracing: kprobes: Register to dynevent earlier stage Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 16/26] tracing: Accept different type for synthetic event fields Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 17/26] tracing: Add NULL trace-array check in print_synth_event() Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 18/26] tracing/boot: Add boot-time tracing Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 19/26] tracing/boot: Add per-event settings Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 20/26] tracing/boot Add kprobe event support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 21/26] tracing/boot: Add synthetic " Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 22/26] tracing/boot: Add instance node support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 23/26] tracing/boot: Add cpu_mask option support Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 24/26] tracing/boot: Add function tracer filter options Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 25/26] Documentation: tracing: Add boot-time tracing document Steven Rostedt
2020-01-14 21:03 ` [for-next][PATCH 26/26] tracing: trigger: Replace unneeded RCU-list traversals Steven Rostedt
2020-01-14 22:11   ` Steven Rostedt
2020-02-20  9:10 [for-next][PATCH 12/26] Documentation: bootconfig: Add a doc for extended boot config Markus Elfring
2020-02-20 13:13 ` Masami Hiramatsu
2020-02-20 15:00   ` Markus Elfring
2020-02-21 10:16     ` Masami Hiramatsu

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=20200114210337.472405913@goodmis.org \
    --to=rostedt@goodmis.org \
    --cc=akpm@linux-foundation.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mhiramat@kernel.org \
    --cc=mingo@kernel.org \
    --subject='Re: [for-next][PATCH 12/26] 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 a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox