[RFC,v4,09/22] Documentation: bootconfig: Add a doc for extended boot config
diff mbox series

Message ID 157528169879.22451.14360457853087960991.stgit@devnote2
State New
Headers show
  • tracing: bootconfig: Boot-time tracing and Extra boot config
Related show

Commit Message

Masami Hiramatsu Dec. 2, 2019, 10:14 a.m. UTC
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 v4:
  - Rename suppremental kernel command line to boot config.
  - Update document according to the recent changes.
  - Add How to load it on boot.
  - Style bugfix.
 Documentation/admin-guide/bootconfig.rst |  174 ++++++++++++++++++++++++++++++
 Documentation/admin-guide/index.rst      |    1 
 MAINTAINERS                              |    1 
 3 files changed, 176 insertions(+)
 create mode 100644 Documentation/admin-guide/bootconfig.rst

diff mbox series

diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
new file mode 100644
index 000000000000..db35cee8a00a
--- /dev/null
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -0,0 +1,174 @@ 
+.. SPDX-License-Identifier: GPL-2.0
+Boot Configuration
+:Author: Masami Hiramatsu <mhiramat@kernel.org>
+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 only contains alphabet, number, dash ("-") or underscore ("_").
+If a value need to contain comma (",") as delimiter, you can use double-quotes
+or single-quotes to quote it. Quotes in VALUE can be escaped by backslash("\")
+(however, the backslash + quotes are passed AS-IS.)
+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.
+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
+/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
+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
+Config 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
+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 34cc20ee7f3a..01e0994a435b 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -111,6 +111,7 @@  configure specific aspects of kernel behavior to your liking.
+   bootconfig
 .. only::  subproject and html
index 08185de1652b..dffe3ecdec7a 100644
@@ -15696,6 +15696,7 @@  F:	lib/bootconfig.c
 F:	fs/proc/bootconfig.c
 F:	include/linux/bootconfig.h
 F:	tools/bootconfig/*
+F:	Documentation/admin-guide/bootconfig.rst
 M:	Sam Creasey <sammy@sammy.net>