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@xxxxxxxxxx>
---
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@xxxxxxxxxx>
+
+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@xxxxxxxxx>
