lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <156678938543.21459.628373407524491520.stgit@devnote2>
Date:   Mon, 26 Aug 2019 12:16:25 +0900
From:   Masami Hiramatsu <mhiramat@...nel.org>
To:     Steven Rostedt <rostedt@...dmis.org>,
        Frank Rowand <frowand.list@...il.com>
Cc:     Ingo Molnar <mingo@...hat.com>, Namhyung Kim <namhyung@...nel.org>,
        Tim Bird <Tim.Bird@...y.com>, Jiri Olsa <jolsa@...hat.com>,
        Arnaldo Carvalho de Melo <acme@...nel.org>,
        Tom Zanussi <tom.zanussi@...ux.intel.com>,
        Rob Herring <robh+dt@...nel.org>,
        Andrew Morton <akpm@...ux-foundation.org>,
        Thomas Gleixner <tglx@...utronix.de>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Alexey Dobriyan <adobriyan@...il.com>,
        Jonathan Corbet <corbet@....net>,
        Linus Torvalds <torvalds@...ux-foundation.org>,
        linux-doc@...r.kernel.org, linux-fsdevel@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [RFC PATCH v3 04/19] Documentation: skc: Add a doc for supplemental kernel cmdline

Add a documentation for supplemental kernel cmdline under
admin-guide, since it is including the syntax of SKC file.

Signed-off-by: Masami Hiramatsu <mhiramat@...nel.org>
---
 Documentation/admin-guide/index.rst             |    1 
 Documentation/admin-guide/kernel-parameters.txt |    1 
 Documentation/admin-guide/skc.rst               |  123 +++++++++++++++++++++++
 MAINTAINERS                                     |    1 
 4 files changed, 126 insertions(+)
 create mode 100644 Documentation/admin-guide/skc.rst

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 33feab2f4084..44b4cb61003a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -106,6 +106,7 @@ configure specific aspects of kernel behavior to your liking.
    rtc
    svga
    video-output
+   skc
 
 .. only::  subproject and html
 
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 9a955b1bd1bf..334ce59de23a 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4277,6 +4277,7 @@
 			Pass the physical memory address and size of loaded
 			supplemental kernel cmdline (SKC) text. This will
 			be treated by bootloader which loads the SKC file.
+			See Documentation/admin-guide/skc.rst.
 
 	slram=		[HW,MTD]
 
diff --git a/Documentation/admin-guide/skc.rst b/Documentation/admin-guide/skc.rst
new file mode 100644
index 000000000000..dc6f7ba8e1d7
--- /dev/null
+++ b/Documentation/admin-guide/skc.rst
@@ -0,0 +1,123 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
+Supplemental Kernel Commandline
+================================
+
+:Author: Masami Hiramatsu <mhiramat@...nel.org>
+
+Overview
+========
+
+Supplemental Kernel Commandline (SKC) is expanding current kernel cmdline
+to support additional key-value data when boot the kernel in efficient way.
+This allows adoministrators to pass a tree-structured key-value text file
+(SKC file) via bootloaders.
+
+SKC File Syntax
+===============
+
+SKC basic syntax is simple. Each key consists of dot-connected-words, and
+key and value are connected by "=". The value has to be terminated by semi-
+colon (";"). 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 the delimiters, you can use double-quotes to
+quote it. A double quote in VALUE can be escaped by backslash. 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).
+
+Tree Structure
+--------------
+
+SKC 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;
+}
+
+In both style, same key words are automatically merged when parsing it
+at boot time. So you can append similar trees or key-values.
+
+SKC File Limitation
+===================
+
+Currently the maximum SKC file size is 32KB and the total key-words (not
+key-value entries) must be under 512 nodes.
+
+/proc/sup_cmdline
+=================
+
+/proc/sup_cmdline is the user-space interface of supplemental kernel
+cmdline. 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"...];
+
+How to Pass at Boot
+===================
+
+SKC file is passed to kernel via memory, so the boot loader must support
+loading SKC file. After loading the SKC file on memory, the boot loader
+has to add "skc=PADDR,SIZE" argument to kernel cmdline, where the PADDR
+is the physical address of the memory block and SIZE is the size of SKC
+file.
+
+SKC 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 skc_find_value(). If you want to know what keys exist in the SKC
+tree, you can use skc_for_each_key_value() to iterate key-value pairs.
+Note that you need to use skc_array_for_each_value() for accessing
+each arraies value, e.g.
+
+::
+
+ vnode = NULL;
+ skc_find_value("key.word", &vnode);
+ if (vnode && skc_node_is_array(vnode))
+    skc_array_for_each_value(vnode, value) {
+      printk("%s ", value);
+    }
+
+If you want to focus on keys which has a prefix string, you can use
+skc_find_node() to find a node which prefix key words, and iterate
+keys under the prefix node with skc_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 = skc_find_node("key.prefix");
+ value = skc_node_find_value(root, "option", &vnode);
+ ...
+ skc_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, SKC becomes readonly.
+All data and keys must be copied if you need to modify it.
+
+
+Functions and structures
+========================
+
+.. kernel-doc:: include/linux/skc.h
+.. kernel-doc:: lib/skc.c
+
diff --git a/MAINTAINERS b/MAINTAINERS
index 10dd38311d96..9c0b97643515 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15368,6 +15368,7 @@ S:	Maintained
 F:	lib/skc.c
 F:	fs/proc/sup_cmdline.c
 F:	include/linux/skc.h
+F:	Documentation/admin-guide/skc.rst
 
 SUN3/3X
 M:	Sam Creasey <sammy@...my.net>

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ