Skip to contentSkip to conversation

Documentation: bootconfig: Documentaiton updates

PATCH Superseded Masami Hiramatsu 4 participants 15 messages Mar 3, 2020 – Mar 5, 2020

Subsystems (3)

v4 of 5 Superseded Latest is v5 →

lore
Share & tools
lore

Masami Hiramatsu

author maintainer
#0 lore raw

v4 cover Documentation: bootconfig: Documentaiton updates

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) <[email protected]>

author maintainer
#1 lore raw

PATCH v4 1/1 Documentation: bootconfig: Update boot configuration documentation

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.

---
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(-)
Documentation/admin-guide/bootconfig.rst +115 -66
index cf2edcd09183..b719b257b579 100644
@@ -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.
 
 
Documentation/trace/boottime-trace.rst +2 -0
index dcb390075ca1..e6cbe22361e9 100644
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _boottimetrace:
+
 =================
 Boot-time tracing
 =================
#2 lore raw

Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 2 lines

Changes in v4:
- Remove O= option from examples.

Will any more constructive responses follow according to previous review comments?

…

Quoted 1 line

+++ b/Documentation/admin-guide/bootconfig.rst

…

Quoted 1 line

+… If keys contains 3

Wording correction “… keys contain …”?

Would you like to improve the provided information at any more places (besides typos)?

Regards,
Markus

reviewer
#3 lore raw

Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation

In reply to Masami Hiramatsu

Hi again, :)

Quoted 64 lines · Masami Hiramatsu

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.

---
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(-)
Documentation/admin-guide/bootconfig.rst +26 -5
index cf2edcd09183..b719b257b579 100644
@@ -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

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 50

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +10 -0
+      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.

Quoted 15 lines
Documentation/admin-guide/bootconfig.rst +15 -0
+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.

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 75

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +10 -0
+
+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.

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 77

Quoted 2 lines
Documentation/admin-guide/bootconfig.rst +2 -0
+
+To do this operation, Linux kernel provides "bootconfig" command under

provides the "bootconfig" command under

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 79

Quoted 2 lines
Documentation/admin-guide/bootconfig.rst +2 -0
+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.

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 83

Quoted 4 lines
Documentation/admin-guide/bootconfig.rst +4 -0
+
+ # make -C tools/bootconfig
+
+To add your boot configuration file to initrd image, run bootconfig as below

to an initrd image,

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 84

Quoted 1 line
Documentation/admin-guide/bootconfig.rst +1 -0
+(Old data is removed automatically if exists)::

if it exists)::

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 88

Quoted 7 lines
Documentation/admin-guide/bootconfig.rst +3 -3
+
+ # 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::

Quoted 6 lines
Documentation/admin-guide/bootconfig.rst +6 -0
+
+ # 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::
+

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 104

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +9 -0
+  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

Quoted 8 lines
Documentation/admin-guide/bootconfig.rst +1 -1
-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

Documentation/admin-guide/bootconfig.rst you can not escape these quotes. · line 125

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +3 -4
 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.

Documentation/admin-guide/bootconfig.rst you can use ``+=`` operator. For example:: · line 163

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +2 -1
+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

Quoted 5 lines
Documentation/admin-guide/bootconfig.rst +1 -1
  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
 

Documentation/admin-guide/bootconfig.rst you can use ``+=`` operator. For example:: · line 173

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +2 -4
 
 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.::

Quoted 6 lines
Documentation/admin-guide/bootconfig.rst +0 -0
  # 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

Documentation/admin-guide/bootconfig.rst with hash ("#") until newline ("\n") will be ignored. · line 187

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +2 -2
 
-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

Quoted 9 lines
Documentation/admin-guide/bootconfig.rst +1 -1
- key = 1 # comment
+ key = 1 # !ERROR! comment is not allowed before delimiter
        ,2
 
 
 /proc/bootconfig
 ================
 

[snip]

Quoted 5 lines

Config File Limitation
======================

Documentation/admin-guide/bootconfig.rst +0 -2
-Currently the maximum config size size is 32KB and the total key-words (not
-key-value entries) must be under 1024 nodes.

Documentation/admin-guide/bootconfig.rst with hash ("#") until newline ("\n") will be ignored. · line 211

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +5 -5
-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]

Documentation/admin-guide/bootconfig.rst with hash ("#") until newline ("\n") will be ignored. · line 216

Quoted 5 lines
Documentation/admin-guide/bootconfig.rst +4 -0
+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

Documentation/admin-guide/bootconfig.rst with hash ("#") until newline ("\n") will be ignored. · line 218

Quoted 5 lines
Documentation/admin-guide/bootconfig.rst +2 -3
-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

Quoted 1 line

+configuration to initrd image, user need to fix it before boot.

to an initrd image, the user needs to fix any errors before boot.

Signature · 1 line
~Randy
author maintainer
#4 lore raw

Re: [PATCH v4] Documentation: bootconfig: Update boot configuration documentation

Hi Randy,

Thanks for review and good suggestions!

Quoted 11 lines · On Tue, 3 Mar 2020 20:55:39 -0800 Randy Dunlap <[email protected]> wrote:

Documentation/admin-guide/bootconfig.rst Boot Configuration · line 104

Quoted 7 lines
Documentation/admin-guide/bootconfig.rst +6 -0
+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.

[...]

Quoted 9 lines

Documentation/admin-guide/bootconfig.rst you can not escape these quotes. · line 125

Quoted 6 lines
Documentation/admin-guide/bootconfig.rst +3 -2
+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,

Signature · 1 line
Masami Hiramatsu <[email protected]>
#5 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 4 lines

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

reviewer
#6 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 3 lines · Markus Elfring
Quoted 3 lines

What about the following?

User can group identical parent keys together and use braces to list child keys

The user
(as Markus noted)

Quoted 6 lines
Quoted 1 line

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.

Signature · 1 line
~Randy
#7 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 5 lines
Quoted 3 lines
Quoted 3 lines

What about the following?

User can group identical parent keys together and use braces to list child keys

The user

…

Quoted 8 lines
Quoted 6 lines
Quoted 1 line

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

reviewer
#8 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 8 lines · Markus Elfring
Quoted 5 lines
Quoted 3 lines
Quoted 3 lines

What about the following?

User can group identical parent keys together and use braces to list child keys

The user

…

Quoted 2 lines
Quoted 2 lines
Quoted 1 line

under them.

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines

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. :)

Signature · 1 line
~Randy
#9 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 1 line

I'm hoping to be done with the current changes. :)

Will a term like “grouping of parent keys” need any additional explanation?

Regards,
Markus

maintainer
#10 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 3 lines · On Wed, 4 Mar 2020 22:20:07 +0100 Markus Elfring <[email protected]> wrote:
Quoted 1 line

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

#11 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

Quoted 2 lines

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

author maintainer
#12 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

In reply to Jonathan Corbet
Quoted 9 lines · On Wed, 4 Mar 2020 14:22:59 -0700 Jonathan Corbet <[email protected]> wrote:
Quoted 3 lines · On Wed, 4 Mar 2020 22:20:07 +0100 Markus Elfring <[email protected]> wrote:
Quoted 1 line

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.

Signature · 1 line
Masami Hiramatsu <[email protected]>
author maintainer
#13 lore raw

Re: [v4] Documentation: bootconfig: Update boot configuration documentation

In reply to Randy Dunlap
Quoted 7 lines · On Wed, 4 Mar 2020 08:20:35 -0800 Randy Dunlap <[email protected]> wrote:
Quoted 3 lines · Markus Elfring
Quoted 3 lines

What about the following?

User can group identical parent keys together and use braces to list child keys

The user
(as Markus noted)

OK.

Quoted 9 lines
Quoted 7 lines
Quoted 2 lines

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,

Signature · 1 line
Masami Hiramatsu <[email protected]>
#14 lore raw

Re: [v4 0/1] Documentation: bootconfig: Documentation updates

In reply to Masami Hiramatsu
Quoted 1 line

Here is the 4th version of the documentation update.

How do you think about to take previous review comments better into account?

Regards,
Markus