| Message ID | 157867230658.17873.9309879174829924324.stgit@devnote2 (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | tracing: bootconfig: Boot-time tracing and Extra boot config | expand |
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.
Hi Randy, On Sat, 18 Jan 2020 10:28:40 -0800 Randy Dunlap <rdunlap@infradead.org> wrote: > Hi, > > Editorial comments/corrections below... Thank you for your comments! This is very helpful for me. > > 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 OK. > > > +additional key-value data when boot the kernel in an efficient way. > > booting OK. > > > +This allows adoministrators to pass a structured-Key config file. > > administrators Oops. OK. > > > + > > +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].) Yes. > > + > > +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 '{'? Good question! Since the bootconfig doesn't support anonymous key-word block, opening brace doesn't become a delimiter. (So, the above explanation might better use "except for *some* delimiters"...) For example, following data should be wrong. key = value { key2 = value } > > > + > > +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 OK. > > > + > > +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/ OK. > > > +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 Oops, a typo... > > > + > > + # 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 Oops > > > +====================== > > + > > +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) Yes, OK. > > > + > > + 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 OK. > > > +xbc_find_node() to find a node which prefix key words, and iterate > > [confusing above] Ah, it should be "to find a node by the prefix string," > > > +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, OK. > > > +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. Thank you very much! > -- > ~Randy
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 d0da06bdf3d8..c14a956343b9 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -15780,6 +15780,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>
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. - 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