* [PATCH v4 0/1] Documentation: bootconfig: Documentaiton updates
@ 2020-03-03 9:05 Masami Hiramatsu
2020-03-03 9:05 ` [PATCH v4] Documentation: bootconfig: Update boot configuration documentation Masami Hiramatsu
2020-03-03 9:50 ` [v4 0/1] Documentation: bootconfig: Documentation updates Markus Elfring
0 siblings, 2 replies; 15+ messages in thread
From: Masami Hiramatsu @ 2020-03-03 9:05 UTC (permalink / raw)
To: Steven Rostedt, Jonathan Corbet
Cc: Randy Dunlap, linux-doc, linux-kernel, Masami Hiramatsu, Markus Elfring
Hi,
Here is the 4th version of the documentation update.
This removes O= option from example. (This feature will be
implemented in another series.)
Thank you,
---
Masami Hiramatsu (1):
Documentation: bootconfig: Update boot configuration documentation
Documentation/admin-guide/bootconfig.rst | 181 +++++++++++++++++++-----------
Documentation/trace/boottime-trace.rst | 2
2 files changed, 117 insertions(+), 66 deletions(-)
--
Masami Hiramatsu (Linaro) <mhiramat@kernel.org>
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-03 9:05 [PATCH v4 0/1] Documentation: bootconfig: Documentaiton updates Masami Hiramatsu
@ 2020-03-03 9:05 ` Masami Hiramatsu
2020-03-03 10:10 ` Markus Elfring
2020-03-04 4:55 ` Randy Dunlap
2020-03-03 9:50 ` [v4 0/1] Documentation: bootconfig: Documentation updates Markus Elfring
1 sibling, 2 replies; 15+ messages in thread
From: Masami Hiramatsu @ 2020-03-03 9:05 UTC (permalink / raw)
To: Steven Rostedt, Jonathan Corbet
Cc: Randy Dunlap, linux-doc, linux-kernel, Masami Hiramatsu, Markus Elfring
Update boot configuration documentation.
- Not using "config" abbreviation but configuration or description.
- Rewrite descriptions of node and its maxinum number.
- Add a section of use cases of boot configuration.
- Move how to use bootconfig to earlier section.
- Fix some typos, indents and format mistakes.
Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
---
Changes in v4:
- Remove O= option from examples.
Changes in v3:
- Specify that comments also count in size.
- Fix a confusing sentence.
- Add O=<builddir> to make command.
Changes in v2:
- Fixes additional typos (Thanks Markus and Randy!)
- Change a section title to "Tree Structured Key".
---
Documentation/admin-guide/bootconfig.rst | 181 +++++++++++++++++++-----------
Documentation/trace/boottime-trace.rst | 2
2 files changed, 117 insertions(+), 66 deletions(-)
diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index cf2edcd09183..b719b257b579 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -11,19 +11,99 @@ Boot Configuration
Overview
========
-The boot configuration expands the current kernel command line to support
-additional key-value data when booting the kernel in an efficient way.
-This allows administrators to pass a structured-Key config file.
+Boot configuration expands the current kernel command line to support
+additional key-value data while booting the kernel in an efficient way.
+This allows administrators to pass a structured key configuration file
+as a way to supplement the kernel command line to pass system boot parameters.
-Config File Syntax
-==================
+Compared with the kernel command line, the boot configuration can provide
+scalability (up to 32 KiB configuration data including comments), readability
+(structured configuration with comments) and compact expression of option
+groups.
+
+When to Use the Boot Configuration?
+-----------------------------------
+
+The boot configuration supports kernel command line options and init daemon
+boot options. All sub-keys under "kernel" root key are passed as a part of
+kernel command line [1]_, and ones under "init" root key are passed as a part
+of init command line. For example, ::
+
+ root=UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82 ro quiet splash console=ttyS0,115200n8 console=tty0
+
+This can be written as following boot configuration file.::
+
+ kernel {
+ root = "UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82" # nvme0n1p3
+ ro # mount rootfs as read only
+ quiet # No console log
+ splash # show splash image on boot screen
+ console = "ttyS0,115200n8" # 1st console to serial device
+ console += tty0 # add 2nd console
+ }
+
+If you think that kernel/init options becomes too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. If unsure, you can still continue to use the
+legacy kernel command line.
+
+Also, some features may depend on the boot configuration, and it has own
+root key. For example, ftrace boot-time tracer uses "ftrace" root key to
+describe its options [2]_. If you want to use such features, you need to
+enable the boot configuration.
+
+.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
+.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`
+
+
+How to Use the Boot Configuration?
+----------------------------------
+
+To enable the boot configuration support on your kernel, it must be built with
+``CONFIG_BOOT_CONFIG=y`` and ``CONFIG_BLK_DEV_INITRD=y``.
+
+Next, you can write a boot configuration file and attach it to initrd image.
+
+The boot configuration file is attached to the end of the initrd (initramfs)
+image file with size, checksum and 12-byte magic word as below.
+
+[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n]
+
+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 configuration
+file to/from initrd image. You can build it by the following command::
+
+ # make -C tools/bootconfig
+
+To add your boot configuration 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
-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``).
+To remove the configuration from the image, you can use -d option as below::
+
+ # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
+
+At last, add ``bootconfig`` on the normal kernel command line to tell the
+kernel to look for the bootconfig at the end of the initrd file. For example::
+
+ GRUB_CMDLINE_LINUX="bootconfig"
+
+
+Boot Configuration Syntax
+=========================
+
+The boot configuration 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[...]][;]
+ KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
@@ -39,11 +119,11 @@ 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 if the key exists or not (like a boolean).
-Key-Value Syntax
-----------------
+Tree Structured Key
+-------------------
-The boot config file syntax allows user to merge partially same word keys
-by brace. For example::
+The boot configuration syntax allows user to merge same parent key using
+braces as tree structured key. For example::
foo.bar.baz = value1
foo.bar.qux.quux = value2
@@ -80,19 +160,17 @@ you can use ``+=`` operator. For example::
In this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``.
However, a sub-key and a value can not co-exist under a parent key.
-For example, following config is NOT allowed.::
+For example, following configuration is NOT allowed.::
foo = value1
- foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist
+ foo.bar = value2 # !ERROR! sub-key "bar" and value "value1" can NOT co-exist
Comments
--------
-The config syntax accepts shell-script style comments. The comments starting
-with hash ("#") until newline ("\n") will be ignored.
-
-::
+The boot configuration accepts shell-script style comments. The comments
+starting with hash (``#``) until newline (``\n``), will be skipped.::
# comment line
foo = value # value is set to foo.
@@ -100,74 +178,45 @@ with hash ("#") until newline ("\n") will be ignored.
2, # 2nd element
3 # 3rd element
-This is parsed as below::
+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 ::
+``;``). This means following description has a syntax error. ::
- key = 1 # comment
+ key = 1 # !ERROR! comment is not allowed before delimiter
,2
/proc/bootconfig
================
-/proc/bootconfig is a user-space interface of the boot config.
+The file /proc/bootconfig is a user-space interface to the configuration
+of system boot parameters.
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 with size, checksum and
-12-byte magic word as below.
-
-[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n]
-
-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 the following 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
-
-Then add "bootconfig" on the normal kernel command line to tell the
-kernel to look for the bootconfig at the end of the initrd file.
-
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.
+Currently the maximum configuration file size (including comments) is 32 KiB
+and the total number of key-words and values must be under 1024 nodes.
+(Note: Each key consists of words separated by dot, and value also consists
+of values separated by comma. Here, each word and each value is generally
+called a "node".)
+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 configuration items will be under 100 entries and smaller
+than 8 KiB, 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.
+size is smaller than 32 KiB.
+Anyway, since bootconfig command verifies it when appending a boot
+configuration to initrd image, user need to fix it before boot.
Bootconfig APIs
@@ -206,7 +255,7 @@ or get the named array under prefix as below::
This accesses a value of "key.prefix.option" and an array of
"key.prefix.array-option".
-Locking is not needed, since after initialization, the config becomes
+Locking is not needed, since after initialization, the configuration becomes
read-only. All data and keys must be copied if you need to modify it.
diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
index dcb390075ca1..e6cbe22361e9 100644
--- a/Documentation/trace/boottime-trace.rst
+++ b/Documentation/trace/boottime-trace.rst
@@ -1,5 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
+.. _boottimetrace:
+
=================
Boot-time tracing
=================
^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [v4 0/1] Documentation: bootconfig: Documentation updates
2020-03-03 9:05 [PATCH v4 0/1] Documentation: bootconfig: Documentaiton updates Masami Hiramatsu
2020-03-03 9:05 ` [PATCH v4] Documentation: bootconfig: Update boot configuration documentation Masami Hiramatsu
@ 2020-03-03 9:50 ` Markus Elfring
1 sibling, 0 replies; 15+ messages in thread
From: Markus Elfring @ 2020-03-03 9:50 UTC (permalink / raw)
To: Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, Randy Dunlap, linux-kernel
> Here is the 4th version of the documentation update.
How do you think about to take previous review comments better into account?
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-03 9:05 ` [PATCH v4] Documentation: bootconfig: Update boot configuration documentation Masami Hiramatsu
@ 2020-03-03 10:10 ` Markus Elfring
2020-03-04 4:55 ` Randy Dunlap
1 sibling, 0 replies; 15+ messages in thread
From: Markus Elfring @ 2020-03-03 10:10 UTC (permalink / raw)
To: Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, Randy Dunlap, linux-kernel
> Changes in v4:
> - Remove O= option from examples.
Will any more constructive responses follow according to previous review comments?
…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +… If keys contains 3
Wording correction “… keys contain …”?
Would you like to improve the provided information at any more places
(besides typos)?
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-03 9:05 ` [PATCH v4] Documentation: bootconfig: Update boot configuration documentation Masami Hiramatsu
2020-03-03 10:10 ` Markus Elfring
@ 2020-03-04 4:55 ` Randy Dunlap
2020-03-04 11:37 ` Masami Hiramatsu
1 sibling, 1 reply; 15+ messages in thread
From: Randy Dunlap @ 2020-03-04 4:55 UTC (permalink / raw)
To: Masami Hiramatsu, Steven Rostedt, Jonathan Corbet
Cc: linux-doc, linux-kernel, Markus Elfring
Hi again, :)
On 3/3/20 1:05 AM, Masami Hiramatsu wrote:
> Update boot configuration documentation.
>
> - Not using "config" abbreviation but configuration or description.
> - Rewrite descriptions of node and its maxinum number.
> - Add a section of use cases of boot configuration.
> - Move how to use bootconfig to earlier section.
> - Fix some typos, indents and format mistakes.
>
> Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> ---
> Changes in v4:
> - Remove O= option from examples.
> Changes in v3:
> - Specify that comments also count in size.
> - Fix a confusing sentence.
> - Add O=<builddir> to make command.
> Changes in v2:
> - Fixes additional typos (Thanks Markus and Randy!)
> - Change a section title to "Tree Structured Key".
> ---
> Documentation/admin-guide/bootconfig.rst | 181 +++++++++++++++++++-----------
> Documentation/trace/boottime-trace.rst | 2
> 2 files changed, 117 insertions(+), 66 deletions(-)
>
> diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> index cf2edcd09183..b719b257b579 100644
> --- a/Documentation/admin-guide/bootconfig.rst
> +++ b/Documentation/admin-guide/bootconfig.rst
> @@ -11,19 +11,99 @@ Boot Configuration
> Overview
> ========
>
> -The boot configuration expands the current kernel command line to support
> -additional key-value data when booting the kernel in an efficient way.
> -This allows administrators to pass a structured-Key config file.
> +Boot configuration expands the current kernel command line to support
> +additional key-value data while booting the kernel in an efficient way.
> +This allows administrators to pass a structured key configuration file
> +as a way to supplement the kernel command line to pass system boot parameters.
>
> -Config File Syntax
> -==================
> +Compared with the kernel command line, the boot configuration can provide
> +scalability (up to 32 KiB configuration data including comments), readability
> +(structured configuration with comments) and compact expression of option
> +groups.
> +
> +When to Use the Boot Configuration?
> +-----------------------------------
> +
> +The boot configuration supports kernel command line options and init daemon
> +boot options. All sub-keys under "kernel" root key are passed as a part of
> +kernel command line [1]_, and ones under "init" root key are passed as a part
> +of init command line. For example, ::
> +
> + root=UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82 ro quiet splash console=ttyS0,115200n8 console=tty0
> +
> +This can be written as following boot configuration file.::
> +
> + kernel {
> + root = "UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82" # nvme0n1p3
> + ro # mount rootfs as read only
> + quiet # No console log
> + splash # show splash image on boot screen
> + console = "ttyS0,115200n8" # 1st console to serial device
> + console += tty0 # add 2nd console
> + }
> +
> +If you think that kernel/init options becomes too long to write in boot-loader
> +configuration file or you want to comment on each option, the boot
> +configuration may be suitable. If unsure, you can still continue to use the
> +legacy kernel command line.
> +
> +Also, some features may depend on the boot configuration, and it has own
and each such
feature has its own root key.
> +root key. For example, ftrace boot-time tracer uses "ftrace" root key to
> +describe its options [2]_. If you want to use such features, you need to
> +enable the boot configuration.
> +
> +.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> +.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`
> +
> +
> +How to Use the Boot Configuration?
> +----------------------------------
> +
> +To enable the boot configuration support on your kernel, it must be built with
> +``CONFIG_BOOT_CONFIG=y`` and ``CONFIG_BLK_DEV_INITRD=y``.
> +
> +Next, you can write a boot configuration file and attach it to initrd image.
> +
> +The boot configuration file is attached to the end of the initrd (initramfs)
> +image file with size, checksum and 12-byte magic word as below.
> +
> +[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n]
> +
> +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.
boot loader or the kernel image itself.
> +
> +To do this operation, Linux kernel provides "bootconfig" command under
provides the "bootconfig" command under
> +tools/bootconfig, which allows admin to apply or delete the configuration
> +file to/from initrd image. You can build it by the following command::
to/from an initrd image.
> +
> + # make -C tools/bootconfig
> +
> +To add your boot configuration file to initrd image, run bootconfig as below
to an initrd image,
> +(Old data is removed automatically if exists)::
if it exists)::
> +
> + # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
>
> -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``).
> +To remove the configuration from the image, you can use -d option as below::
you can use the -d option as below::
> +
> + # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
> +
> +At last, add ``bootconfig`` on the normal kernel command line to tell the
> +kernel to look for the bootconfig at the end of the initrd file. For example::
> +
> + GRUB_CMDLINE_LINUX="bootconfig"
> +
> +
> +Boot Configuration Syntax
> +=========================
> +
> +The boot configuration 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 (``,``). ::
values,
or just
For an array, its entries are separated by
>
> -KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
> + KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
>
> Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
>
> @@ -39,11 +119,11 @@ 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 if the key exists or not (like a boolean).
>
> -Key-Value Syntax
> -----------------
> +Tree Structured Key
> +-------------------
>
> -The boot config file syntax allows user to merge partially same word keys
> -by brace. For example::
> +The boot configuration syntax allows user to merge same parent key using
allows the user
although I am having problems with the rest of that sentence.
> +braces as tree structured key. For example::
>
> foo.bar.baz = value1
> foo.bar.qux.quux = value2
> @@ -80,19 +160,17 @@ you can use ``+=`` operator. For example::
> In this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``.
>
> However, a sub-key and a value can not co-exist under a parent key.
> -For example, following config is NOT allowed.::
> +For example, following configuration is NOT allowed.::
example, the following
>
> foo = value1
> - foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist
> + foo.bar = value2 # !ERROR! sub-key "bar" and value "value1" can NOT co-exist
>
>
> Comments
> --------
>
> -The config syntax accepts shell-script style comments. The comments starting
> -with hash ("#") until newline ("\n") will be ignored.
> -
> -::
> +The boot configuration accepts shell-script style comments. The comments
> +starting with hash (``#``) until newline (``\n``), will be skipped.::
no comma. or 2 commas:
The comments,
beginning with hash (``#``) and continuing until newline (``\n``), will be skipped.::
>
> # comment line
> foo = value # value is set to foo.
> @@ -100,74 +178,45 @@ with hash ("#") until newline ("\n") will be ignored.
> 2, # 2nd element
> 3 # 3rd element
>
> -This is parsed as below::
> +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 ::
> +``;``). This means following description has a syntax error. ::
This means the following
>
> - key = 1 # comment
> + key = 1 # !ERROR! comment is not allowed before delimiter
> ,2
>
>
> /proc/bootconfig
> ================
>
[snip]
> 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.
> +Currently the maximum configuration file size (including comments) is 32 KiB
> +and the total number of key-words and values must be under 1024 nodes.
> +(Note: Each key consists of words separated by dot, and value also consists
> +of values separated by comma. Here, each word and each value is generally
> +called a "node".)
[blank line would be nice here]
> +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 configuration items will be under 100 entries and smaller
> +than 8 KiB, so it would be enough.
> If the node number exceeds 1024, parser returns an error even if the file
the parser
> -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.
> +size is smaller than 32 KiB.
> +Anyway, since bootconfig command verifies it when appending a boot
since the bootconfig command
> +configuration to initrd image, user need to fix it before boot.
to an initrd image, the user needs to fix any errors before boot.
--
~Randy
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 4:55 ` Randy Dunlap
@ 2020-03-04 11:37 ` Masami Hiramatsu
2020-03-04 14:45 ` [v4] " Markus Elfring
0 siblings, 1 reply; 15+ messages in thread
From: Masami Hiramatsu @ 2020-03-04 11:37 UTC (permalink / raw)
To: Randy Dunlap
Cc: Steven Rostedt, Jonathan Corbet, linux-doc, linux-kernel, Markus Elfring
Hi Randy,
Thanks for review and good suggestions!
On Tue, 3 Mar 2020 20:55:39 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:
> > +Boot Configuration Syntax
> > +=========================
> > +
> > +The boot configuration 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 (``,``). ::
>
> values,
> or just
> For an array, its entries are separated by
I like this latter one.
[...]
> > +Tree Structured Key
> > +-------------------
> >
> > -The boot config file syntax allows user to merge partially same word keys
> > -by brace. For example::
> > +The boot configuration syntax allows user to merge same parent key using
>
> allows the user
> although I am having problems with the rest of that sentence.
What about the following?
User can group identical parent keys together and use braces to list child keys
under them.
Thank you,
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 11:37 ` Masami Hiramatsu
@ 2020-03-04 14:45 ` Markus Elfring
2020-03-04 16:20 ` Randy Dunlap
0 siblings, 1 reply; 15+ messages in thread
From: Markus Elfring @ 2020-03-04 14:45 UTC (permalink / raw)
To: Masami Hiramatsu, Randy Dunlap, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, linux-kernel
> What about the following?
>
> User can group identical parent keys together and use braces to list child keys
> under them.
Another wording alternative:
The user can group settings together. Curly brackets enclose a configuration then
according to a parent context.
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 14:45 ` [v4] " Markus Elfring
@ 2020-03-04 16:20 ` Randy Dunlap
2020-03-04 18:09 ` Markus Elfring
2020-03-05 0:58 ` Masami Hiramatsu
0 siblings, 2 replies; 15+ messages in thread
From: Randy Dunlap @ 2020-03-04 16:20 UTC (permalink / raw)
To: Markus Elfring, Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, linux-kernel
On 3/4/20 6:45 AM, Markus Elfring wrote:
>> What about the following?
>>
>> User can group identical parent keys together and use braces to list child keys
The user
(as Markus noted)
>> under them.
>
> Another wording alternative:
>
> The user can group settings together. Curly brackets enclose a configuration then
> according to a parent context.
I slightly prefer Masami's text.
--
~Randy
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 16:20 ` Randy Dunlap
@ 2020-03-04 18:09 ` Markus Elfring
2020-03-04 21:07 ` Randy Dunlap
2020-03-05 0:58 ` Masami Hiramatsu
1 sibling, 1 reply; 15+ messages in thread
From: Markus Elfring @ 2020-03-04 18:09 UTC (permalink / raw)
To: Randy Dunlap, Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, linux-kernel
>>> What about the following?
>>>
>>> User can group identical parent keys together and use braces to list child keys
>
> The user
…
>>> under them.
>>
>> Another wording alternative:
>>
>> The user can group settings together. Curly brackets enclose a configuration then
>> according to a parent context.
>
> I slightly prefer Masami's text.
Would you like to improve the distinction for grouping the involved items?
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 18:09 ` Markus Elfring
@ 2020-03-04 21:07 ` Randy Dunlap
2020-03-04 21:20 ` Markus Elfring
0 siblings, 1 reply; 15+ messages in thread
From: Randy Dunlap @ 2020-03-04 21:07 UTC (permalink / raw)
To: Markus Elfring, Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, linux-kernel
On 3/4/20 10:09 AM, Markus Elfring wrote:
>>>> What about the following?
>>>>
>>>> User can group identical parent keys together and use braces to list child keys
>>
>> The user
> …
>>>> under them.
>>>
>>> Another wording alternative:
>>>
>>> The user can group settings together. Curly brackets enclose a configuration then
>>> according to a parent context.
>>
>> I slightly prefer Masami's text.
>
> Would you like to improve the distinction for grouping the involved items?
I'm hoping to be done with the current changes. :)
--
~Randy
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 21:07 ` Randy Dunlap
@ 2020-03-04 21:20 ` Markus Elfring
2020-03-04 21:22 ` Jonathan Corbet
0 siblings, 1 reply; 15+ messages in thread
From: Markus Elfring @ 2020-03-04 21:20 UTC (permalink / raw)
To: Randy Dunlap, Masami Hiramatsu, linux-doc
Cc: Steven Rostedt, Jonathan Corbet, linux-kernel
> I'm hoping to be done with the current changes. :)
Will a term like “grouping of parent keys” need any additional explanation?
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 21:20 ` Markus Elfring
@ 2020-03-04 21:22 ` Jonathan Corbet
2020-03-04 21:30 ` Markus Elfring
2020-03-05 0:59 ` Masami Hiramatsu
0 siblings, 2 replies; 15+ messages in thread
From: Jonathan Corbet @ 2020-03-04 21:22 UTC (permalink / raw)
To: Markus Elfring
Cc: Randy Dunlap, Masami Hiramatsu, linux-doc, Steven Rostedt, linux-kernel
On Wed, 4 Mar 2020 22:20:07 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:
> > I'm hoping to be done with the current changes. :)
>
> Will a term like “grouping of parent keys” need any additional explanation?
Honestly, Markus, I think that the patch is good enough for now; time to
merge it and move on to something else.
Thanks,
jon
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 21:22 ` Jonathan Corbet
@ 2020-03-04 21:30 ` Markus Elfring
2020-03-05 0:59 ` Masami Hiramatsu
1 sibling, 0 replies; 15+ messages in thread
From: Markus Elfring @ 2020-03-04 21:30 UTC (permalink / raw)
To: Jonathan Corbet, Masami Hiramatsu, linux-doc
Cc: Randy Dunlap, Steven Rostedt, linux-kernel
> Honestly, Markus, I think that the patch is good enough for now; time to
> merge it and move on to something else.
I pointed a few details out for further considerations.
I am curious if they will get more attention for the desired clarification.
Regards,
Markus
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 16:20 ` Randy Dunlap
2020-03-04 18:09 ` Markus Elfring
@ 2020-03-05 0:58 ` Masami Hiramatsu
1 sibling, 0 replies; 15+ messages in thread
From: Masami Hiramatsu @ 2020-03-05 0:58 UTC (permalink / raw)
To: Randy Dunlap
Cc: Markus Elfring, linux-doc, Steven Rostedt, Jonathan Corbet, linux-kernel
On Wed, 4 Mar 2020 08:20:35 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:
> On 3/4/20 6:45 AM, Markus Elfring wrote:
> >> What about the following?
> >>
> >> User can group identical parent keys together and use braces to list child keys
>
> The user
> (as Markus noted)
OK.
>
> >> under them.
> >
> > Another wording alternative:
> >
> > The user can group settings together. Curly brackets enclose a configuration then
> > according to a parent context.
>
> I slightly prefer Masami's text.
Thank you,
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [v4] Documentation: bootconfig: Update boot configuration documentation
2020-03-04 21:22 ` Jonathan Corbet
2020-03-04 21:30 ` Markus Elfring
@ 2020-03-05 0:59 ` Masami Hiramatsu
1 sibling, 0 replies; 15+ messages in thread
From: Masami Hiramatsu @ 2020-03-05 0:59 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Markus Elfring, Randy Dunlap, Masami Hiramatsu, linux-doc,
Steven Rostedt, linux-kernel
On Wed, 4 Mar 2020 14:22:59 -0700
Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed, 4 Mar 2020 22:20:07 +0100
> Markus Elfring <Markus.Elfring@web.de> wrote:
>
> > > I'm hoping to be done with the current changes. :)
> >
> > Will a term like “grouping of parent keys” need any additional explanation?
>
> Honestly, Markus, I think that the patch is good enough for now; time to
> merge it and move on to something else.
Thanks Jon,
I'll send the final version soon.
--
Masami Hiramatsu <mhiramat@kernel.org>
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2020-03-05 0:59 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-03-03 9:05 [PATCH v4 0/1] Documentation: bootconfig: Documentaiton updates Masami Hiramatsu
2020-03-03 9:05 ` [PATCH v4] Documentation: bootconfig: Update boot configuration documentation Masami Hiramatsu
2020-03-03 10:10 ` Markus Elfring
2020-03-04 4:55 ` Randy Dunlap
2020-03-04 11:37 ` Masami Hiramatsu
2020-03-04 14:45 ` [v4] " Markus Elfring
2020-03-04 16:20 ` Randy Dunlap
2020-03-04 18:09 ` Markus Elfring
2020-03-04 21:07 ` Randy Dunlap
2020-03-04 21:20 ` Markus Elfring
2020-03-04 21:22 ` Jonathan Corbet
2020-03-04 21:30 ` Markus Elfring
2020-03-05 0:59 ` Masami Hiramatsu
2020-03-05 0:58 ` Masami Hiramatsu
2020-03-03 9:50 ` [v4 0/1] Documentation: bootconfig: Documentation updates Markus Elfring
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).