Skip to contentSkip to conversation

Documentation: bootconfig: Documentaiton updates

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

Subsystems (4)
lore
Share & tools
lore

Masami Hiramatsu

author maintainer
#0 lore raw

v5 cover Documentation: bootconfig: Documentaiton updates

Hi,

Here is the 5th version of the documentation update.
- Elaborated according to Randy's comment.
- Fix some typos.

Thank you,

---

Masami Hiramatsu (1):
Documentation: bootconfig: Update boot configuration documentation

 Documentation/admin-guide/bootconfig.rst |  201 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 131 insertions(+), 72 deletions(-)

--
Masami Hiramatsu (Linaro) <[email protected]>

author maintainer
#1 lore raw

PATCH v5 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 v5:
- Elaborate the document.
- Fix some typos.
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 |  201 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 131 insertions(+), 72 deletions(-)
Documentation/admin-guide/bootconfig.rst +129 -72
index cf2edcd09183..3bfc9ddf68e1 100644
@@ -11,25 +11,106 @@ 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
+the kernel command line [1]_, and ones under "init" root key are passed as
+a part of the init daemon's 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.
 
-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 (``,``). ::
+Also, some features may depend on the boot configuration, and each such
+feature has its 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.
 
-KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
+.. [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 or the kernel image itself.
+
+To do this operation, Linux kernel provides the "bootconfig" command under
+tools/bootconfig, which allows admin to apply or delete the configuration
+file to/from an initrd image. You can build it by the following command::
+
+ # make -C tools/bootconfig
+
+To add your boot configuration file to an initrd image, run bootconfig as
+below (Old bootconfig is removed automatically if it exists)::
+
+ # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
+
+To remove the configuration from the image, 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 semicolon (``;``) or newline (``\n``).
+For an array, its entries are separated by comma (``,``). ::
+
+  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
 
 Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
 
 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 (``,``),
+for delimiters such as semicolon (``;``), new-line (``\n``), comma (``,``),
 hash (``#``) and closing brace (``}``).
 
 If you want to use those delimiters in a value, you can use either double-
@@ -39,25 +120,29 @@ 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 user can group identical parent keys together and use braces to list child
+keys under them. For example::
 
  foo.bar.baz = value1
  foo.bar.qux.quux = value2
+ foo.bar.qux.quuz = value3
 
 These can be written also in::
 
  foo.bar {
-    baz = value1
-    qux.quux = value2
+   baz = value1
+   qux {
+      quux = value2
+      quuz = value3
+   }
  }
 
 Or more shorter, written as following::
 
- foo.bar { baz = value1; qux.quux = value2 }
+ foo.bar { baz = value1; qux { quux = value2; quuz = value3 } }
 
 In both styles, same key words are automatically merged when parsing it
 at boot time. So you can append similar trees or key-values.
@@ -80,19 +165,18 @@ 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, the 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,
+beginning with hash (``#``) continues until newline (``\n``), will be
+skipped.::
 
  # comment line
  foo = value # value is set to foo.
@@ -100,74 +184,47 @@ 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 the 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.
-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.
+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 contain 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, the parser returns an error even if the
+file size is smaller than 32 KiB.
+Anyway, since the bootconfig command verifies it when appending a boot
+configuration to an initrd image, the user needs to fix any errors
+before boot.
 
 
 Bootconfig APIs
@@ -206,7 +263,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
 =================
reviewer Reviewed-by on v5 1/1
#2 lore raw

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

Quoted 9 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.

Hi Masami,

I swear that I am not trying to cause another version...

Quoted 36 lines

---
Changes in v5:
- Elaborate the document.
- Fix some typos.
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 |  201 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 131 insertions(+), 72 deletions(-)
Documentation/admin-guide/bootconfig.rst +12 -0
index cf2edcd09183..3bfc9ddf68e1 100644
@@ -11,25 +11,106 @@ Boot Configuration
 
+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
+the kernel command line [1]_, and ones under "init" root key are passed as
+a part of the init daemon's 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.::
+

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

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

become

Quoted 11 lines
Documentation/admin-guide/bootconfig.rst +9 -0
+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.
 
 
+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 semicolon (``;``) or newline (``\n``).

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

Quoted 10 lines
Documentation/admin-guide/bootconfig.rst +4 -1
+For an array, its entries are separated by comma (``,``). ::
+
+  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
 
 Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
 
 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 (``,``),
+for delimiters such as semicolon (``;``), new-line (``\n``), comma (``,``),

usually called: newline

Quoted 4 lines
Documentation/admin-guide/bootconfig.rst +0 -0
 hash (``#``) and closing brace (``}``).
 
 If you want to use those delimiters in a value, you can use either double-
 

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

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,
+beginning with hash (``#``) continues until newline (``\n``), will be

and continuing until newline

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

Quoted 4 lines
Documentation/admin-guide/bootconfig.rst +1 -0
+skipped.::
 
  # comment line
  foo = value # value is set to foo.

thanks.

Signature · 1 line
~Randy
reviewer
#4 lore raw

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

Quoted 3 lines · Markus Elfring
Quoted 1 line

How does this feedback fit to known concerns around the discussed wordings?

As far as I am concerned, it means that the documentation is sufficiently good enough to be useful and not difficult to read.

It does not mean that it's perfect. Patches can still be made to it.

Signature · 1 line
~Randy
#5 lore raw

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

Quoted 4 lines
Quoted 1 line

How does this feedback fit to known concerns around the discussed wordings?

As far as I am concerned, it means that the documentation is sufficiently good enough to be useful and not difficult to read.

Would you like to add anything to my previous review comments (besides simple typo adjustments)?

Quoted 1 line

It does not mean that it's perfect. Patches can still be made to it.

I hope that corresponding agreements will be achieved for further improvements.

Regards,
Markus

reviewer
#6 lore raw

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

Quoted 7 lines · Markus Elfring
Quoted 4 lines
Quoted 1 line

How does this feedback fit to known concerns around the discussed wordings?

As far as I am concerned, it means that the documentation is sufficiently good enough to be useful and not difficult to read.

Would you like to add anything to my previous review comments (besides simple typo adjustments)?

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Quoted 6 lines
Quoted 3 lines

It does not mean that it's perfect. Patches can still be made to it.

I hope that corresponding agreements will be achieved for further improvements.

Signature · 1 line
~Randy
#7 lore raw

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

Quoted 2 lines

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Does this view indicate any communication difficulties?

Which of the possibly unanswered issues do you find not concrete enough so far?

Regards,
Markus

reviewer
#8 lore raw

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

Quoted 4 lines · Markus Elfring
Quoted 2 lines

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Does this view indicate any communication difficulties?

Probably.

Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Signature · 1 line
~Randy
#9 lore raw

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

Quoted 11 lines
Quoted 4 lines
Quoted 2 lines

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Does this view indicate any communication difficulties?

Probably.

Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

How do you think about the desired tracking of bug reports also for this software?

Regards,
Markus

reviewer
#10 lore raw

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

Quoted 5 lines · Markus Elfring
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Does this view indicate any communication difficulties?

Quoted 8 lines
Quoted 6 lines

Probably.

Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

Ideally not, but not very much is ideal.

IOW, it is sometimes required (if one cares enough; sometimes one just gives up).

Quoted 2 lines

How do you think about the desired tracking of bug reports also for this software?

I expect that more users will begin to use it and report problems as they see fit. They can use mailing list(s) and/or bugzilla.kernel.org. I'm not terribly concerned about it. Masami seems to be responsive.

thanks.

Signature · 1 line
~Randy
#11 lore raw

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

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

Ideally not, but not very much is ideal.

Did you notice any aspects where I would be still looking for more helpful answers?

Quoted 2 lines

IOW, it is sometimes required (if one cares enough; sometimes one just gives up).

I find this communication detail unfortunate occasionally.

Quoted 2 lines
Quoted 2 lines

How do you think about the desired tracking of bug reports also for this software?

…

Quoted 1 line

Masami seems to be responsive.

The involved contributors show different response delays, don't they?

Regards,
Markus

reviewer
#12 lore raw

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

Quoted 10 lines · Markus Elfring
Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

Ideally not, but not very much is ideal.

Did you notice any aspects where I would be still looking for more helpful answers?

Sorry, I haven't been tracking all of the email Q&A/response/replies all that carefully.

Quoted 5 lines
Quoted 3 lines

IOW, it is sometimes required (if one cares enough; sometimes one just gives up).

I find this communication detail unfortunate occasionally.

Sure. I do too.

Quoted 7 lines
Quoted 3 lines
Quoted 3 lines

How do you think about the desired tracking of bug reports also for this software?

…

Quoted 1 line

Masami seems to be responsive.

The involved contributors show different response delays, don't they?

That's always the case, in any of the Linux subsystems that I have been involved with.

Signature · 1 line
~Randy
#13 lore raw

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

Quoted 4 lines
Quoted 1 line

The involved contributors show different response delays, don't they?

That's always the case, in any of the Linux subsystems that I have been involved with.

Some delays are usual.

But I can occasionally get the concern that specific constructive feedback would be overlooked or intentionally ignored.
Such a view would be unfortunate if I would like to achieve further improvements also around this software.

Regards,
Markus

maintainer
#14 lore raw

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

In reply to Markus Elfring
Quoted 10 lines · On Thu, 5 Mar 2020 20:06:47 +0100 Markus Elfring <[email protected]> wrote:
Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

Ideally not, but not very much is ideal.

Did you notice any aspects where I would be still looking for more helpful answers?

What does that even mean?

Quoted 6 lines
Quoted 4 lines

IOW, it is sometimes required (if one cares enough; sometimes one just gives up).

I find this communication detail unfortunate occasionally.

Well, it's better than slamming one's head into their desk.

Quoted 9 lines
Quoted 4 lines
Quoted 4 lines

How do you think about the desired tracking of bug reports also for this software?

…

Quoted 1 line

Masami seems to be responsive.

The involved contributors show different response delays, don't they?

Of course! Masami is in Japan, and is probably sleeping right now. That's what happens when you work in a global environment.

-- Steve

#15 lore raw

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

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

Masami seems to be responsive.

The involved contributors show different response delays, don't they?

Of course! Masami is in Japan, and is probably sleeping right now.

I am not so concerned about the global distribution of contributors.

Quoted 1 line

That's what happens when you work in a global environment.

I am used to this fact for years.

I became more concerned about information which was not directly provided in patch change logs (according to my software development expectations).

Regards,
Markus

maintainer
#16 lore raw

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

Quoted 9 lines · On Thu, 5 Mar 2020 21:26:40 +0100 Markus Elfring <[email protected]> wrote:
Quoted 5 lines
Quoted 3 lines
Quoted 1 line

Masami seems to be responsive.

The involved contributors show different response delays, don't they?

Of course! Masami is in Japan, and is probably sleeping right now.

I am not so concerned about the global distribution of contributors.

Quoted 7 lines
Quoted 1 line

That's what happens when you work in a global environment.

I am used to this fact for years.

I became more concerned about information which was not directly provided in patch change logs (according to my software development expectations).

Well, the information added was enough for my own software development expectations, and that's all I care about.

-- Steve

maintainer
#17 lore raw

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

In reply to Markus Elfring
Quoted 5 lines · On Thu, 5 Mar 2020 19:43:59 +0100 Markus Elfring <[email protected]> wrote:
Quoted 5 lines
Quoted 4 lines
Quoted 2 lines

If you would (could) be more concrete (or discrete) in your suggestions, I would be glad to comment on them.

Does this view indicate any communication difficulties?

Quoted 8 lines
Quoted 6 lines

Probably.

Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

I'm clueless about what you are talking about. Yes there's communication difficulties.

Quoted 3 lines

How do you think about the desired tracking of bug reports also for this software?

What does that statement have to do with this patch series????

-- Steve

#18 lore raw

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

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

I'm clueless about what you are talking about.

I suggest to take another look at review comments for previous patch versions.

Quoted 1 line

Yes there's communication difficulties.

I hope that we can reduce them somehow.

Quoted 4 lines
Quoted 2 lines

How do you think about the desired tracking of bug reports also for this software?

What does that statement have to do with this patch series????

Do you identify any feedback as a bug report (or clarification request) here?

Regards,
Markus

maintainer
#19 lore raw

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

Quoted 10 lines · On Thu, 5 Mar 2020 20:14:00 +0100 Markus Elfring <[email protected]> wrote:
Quoted 8 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

Which of the possibly unanswered issues do you find not concrete enough so far?

e.g.:

Quoted 1 line
Quoted 1 line
Quoted 1 line

Will the clarification become more constructive for remaining challenges?

Do you expect that known open issues need to be repeated for each patch revision?

I'm clueless about what you are talking about.

I suggest to take another look at review comments for previous patch versions.

I have, and I believe Masami has satisfactory addressed them, if they needed addressing.

Quoted 5 lines
Quoted 3 lines

Yes there's communication difficulties.

I hope that we can reduce them somehow.

Then please be more specific in your correspondence.

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines

How do you think about the desired tracking of bug reports also for this software?

What does that statement have to do with this patch series????

Do you identify any feedback as a bug report (or clarification request) here?

I still don't have the foggiest clue what you are talking about. What bug are you reporting?

-- Steve

#20 lore raw

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

Quoted 3 lines
Quoted 1 line

I suggest to take another look at review comments for previous patch versions.

I have, and I believe Masami has satisfactory addressed them,

I agree to parts of the shown software evolution.

Quoted 1 line

if they needed addressing.

Remaining issues will eventually be clarified under other circumstances.

Quoted 3 lines
Quoted 1 line

Do you identify any feedback as a bug report (or clarification request) here?

I still don't have the foggiest clue what you are talking about.

It seems that a few reminders can help here.

Quoted 1 line

What bug are you reporting?

Examples:

* Another typo
“… contain only alphabets, …”
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/247

* Use case explanation
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/429

* Challenges for the safe application of key hierarchies “kernel.ftrace”?
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/28/363

* Feature request for syntax description
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/27/1869

Regards,
Markus

maintainer
#21 lore raw

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

Quoted 19 lines · On Thu, 5 Mar 2020 21:10:21 +0100 Markus Elfring <[email protected]> wrote:
Quoted 3 lines
Quoted 1 line

I suggest to take another look at review comments for previous patch versions.

I have, and I believe Masami has satisfactory addressed them,

I agree to parts of the shown software evolution.

Quoted 1 line

if they needed addressing.

Remaining issues will eventually be clarified under other circumstances.

Quoted 3 lines
Quoted 1 line

Do you identify any feedback as a bug report (or clarification request) here?

I still don't have the foggiest clue what you are talking about.

It seems that a few reminders can help here.

Quoted 8 lines
Quoted 1 line

What bug are you reporting?

Examples:

* Another typo
“… contain only alphabets, …”
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/247

Legitimate but not critical.

Quoted 4 lines

* Use case explanation
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/429

I believe what Masami has is sufficient.

Quoted 5 lines

* Challenges for the safe application of key hierarchies “kernel.ftrace”?
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/28/363

Again, what Masami has is sufficient.

Quoted 5 lines

* Feature request for syntax description
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/27/1869

Masami's reply to you was sufficient.

Of your examples, only one do I see can be applied, but is just a minor change in wording.

I don't know where you are going with this, and unless you plan on submitting patches, I think this document is complete as is.

-- Steve

#22 lore raw

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

Quoted 10 lines
Quoted 8 lines
Quoted 1 line

What bug are you reporting?

Examples:

* Another typo
“… contain only alphabets, …”
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/247

Legitimate but not critical.

Thanks for such a view.

It might be that less simple update candidates were left over now.

Quoted 5 lines
Quoted 3 lines

* Use case explanation
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/3/5/429

I believe what Masami has is sufficient.

I got an other impression.

An other document contains background information like the following.

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/trace/boottime-trace.rst?id=b8381ce7aa8ef1ab5a79bf710508e504c494acf7
“…
Since kernel command line is not enough to control these complex features, this uses bootconfig file to describe tracing feature programming. …”

Quoted 6 lines
Quoted 4 lines

* Challenges for the safe application of key hierarchies “kernel.ftrace”?
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/28/363

Again, what Masami has is sufficient.

I would appreciate further clarification also in this area.

Quoted 5 lines
Quoted 3 lines

* Feature request for syntax description
https://lore.kernel.org/linux-doc/[email protected]/
https://lkml.org/lkml/2020/2/27/1869

Masami's reply to you was sufficient.

Yes (in principle).

But I hope to achieve collateral evolution here, too.

Quoted 2 lines

Of your examples, only one do I see can be applied, but is just a minor change in wording.

I am trying again to resolve disagreements somehow.

Quoted 2 lines

I don't know where you are going with this, and unless you plan on submitting patches, I think this document is complete as is.

I hope also to influence the software development attention another bit.

Regards,
Markus

author maintainer
#23 lore raw

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

In reply to Randy Dunlap
Quoted 9 lines · On Wed, 4 Mar 2020 23:01:21 -0800 Randy Dunlap <[email protected]> wrote:
Quoted 8 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.

Quoted 5 lines
Quoted 1 line

Hi Masami,

I swear that I am not trying to cause another version...

Oh, no problem. I'll go along with your reviews.

Quoted 41 lines
Quoted 41 lines

---
Changes in v5:
- Elaborate the document.
- Fix some typos.
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 |  201 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 131 insertions(+), 72 deletions(-)
Documentation/admin-guide/bootconfig.rst +16 -0
index cf2edcd09183..3bfc9ddf68e1 100644
@@ -11,25 +11,106 @@ Boot Configuration
 
+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
+the kernel command line [1]_, and ones under "init" root key are passed as
+a part of the init daemon's 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
Quoted 8 lines

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

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

become

OK.

Quoted 16 lines
Quoted 16 lines
Documentation/admin-guide/bootconfig.rst +12 -0
+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.
 
 
+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 semicolon (``;``) or newline (``\n``).
+For an array, its entries are separated by comma (``,``). ::
+
+  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
 
Quoted 8 lines

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

Quoted 6 lines
Documentation/admin-guide/bootconfig.rst +1 -1
 Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
 
 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 (``,``),
+for delimiters such as semicolon (``;``), new-line (``\n``), comma (``,``),

usually called: newline

Yeah, I wonder why I have written so...

Quoted 9 lines
Quoted 9 lines
Documentation/admin-guide/bootconfig.rst +0 -0
 hash (``#``) and closing brace (``}``).
 
 If you want to use those delimiters in a value, you can use either double-
 
 
 Comments
 --------
 
Quoted 8 lines

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

Quoted 6 lines
Documentation/admin-guide/bootconfig.rst +2 -4
-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,
+beginning with hash (``#``) continues until newline (``\n``), will be

and continuing until newline

OK.

Quoted 8 lines

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

Quoted 5 lines
Documentation/admin-guide/bootconfig.rst +1 -0
+skipped.::
 
  # comment line
  foo = value # value is set to foo.

Thank you!

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

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

In reply to Randy Dunlap

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 v5.1:
- Fix some mistakes (Thanks Randy!)
Changes in v5:
- Elaborate the document.
- Fix some typos.
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 |  201 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 131 insertions(+), 72 deletions(-)
Documentation/admin-guide/bootconfig.rst +129 -72
index cf2edcd09183..e620d525b73f 100644
@@ -11,25 +11,106 @@ 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
+the kernel command line [1]_, and ones under "init" root key are passed as
+a part of the init daemon's 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 become 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.
 
-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 (``,``). ::
+Also, some features may depend on the boot configuration, and each such
+feature has its 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.
 
-KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
+.. [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 or the kernel image itself.
+
+To do this operation, Linux kernel provides the "bootconfig" command under
+tools/bootconfig, which allows admin to apply or delete the configuration
+file to/from an initrd image. You can build it by the following command::
+
+ # make -C tools/bootconfig
+
+To add your boot configuration file to an initrd image, run bootconfig as
+below (Old bootconfig is removed automatically if it exists)::
+
+ # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
+
+To remove the configuration from the image, 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 semicolon (``;``) or newline (``\n``).
+For an array, its entries are separated by comma (``,``). ::
+
+  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
 
 Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
 
 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 (``,``),
+for delimiters such as semicolon (``;``), newline (``\n``), comma (``,``),
 hash (``#``) and closing brace (``}``).
 
 If you want to use those delimiters in a value, you can use either double-
@@ -39,25 +120,29 @@ 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 user can group identical parent keys together and use braces to list child
+keys under them. For example::
 
  foo.bar.baz = value1
  foo.bar.qux.quux = value2
+ foo.bar.qux.quuz = value3
 
 These can be written also in::
 
  foo.bar {
-    baz = value1
-    qux.quux = value2
+   baz = value1
+   qux {
+      quux = value2
+      quuz = value3
+   }
  }
 
 Or more shorter, written as following::
 
- foo.bar { baz = value1; qux.quux = value2 }
+ foo.bar { baz = value1; qux { quux = value2; quuz = value3 } }
 
 In both styles, same key words are automatically merged when parsing it
 at boot time. So you can append similar trees or key-values.
@@ -80,19 +165,18 @@ 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, the 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,
+beginning with hash (``#``) and continuing until newline (``\n``), will be
+skipped.::
 
  # comment line
  foo = value # value is set to foo.
@@ -100,74 +184,47 @@ 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 the 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.
-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.
+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 contain 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, the parser returns an error even if the
+file size is smaller than 32 KiB.
+Anyway, since the bootconfig command verifies it when appending a boot
+configuration to an initrd image, the user needs to fix any errors
+before boot.
 
 
 Bootconfig APIs
@@ -206,7 +263,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
 =================
#25 lore raw

Re: [PATCH v5.1] Documentation: bootconfig: Update boot configuration documentation

Quoted 2 lines

Changes in v5.1:
- Fix some mistakes (Thanks Randy!)

Do you need any more reminders for remaining update candidates?

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

Quoted 3 lines
Documentation/admin-guide/bootconfig.rst +3 -0
+If you think that kernel/init options become too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. …

Would you like to specify any settings in the boot configuration file because the provided storage capacity would be too limited by the kernel command line?

Regards,
Markus

author maintainer
#26 lore raw

Re: [PATCH v5.1] Documentation: bootconfig: Update boot configuration documentation

Quoted 4 lines · On Thu, 5 Mar 2020 15:00:14 +0100 Markus Elfring <[email protected]> wrote:
Quoted 2 lines

Changes in v5.1:
- Fix some mistakes (Thanks Randy!)

Do you need any more reminders for remaining update candidates?

Hmm, no, I don't need it any more at this point. This is good enough.

If you think you have "any more" update candidates, feel free to make an update "patch" and send to us. That will be the next step.

Quoted 9 lines

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

Quoted 3 lines
Documentation/admin-guide/bootconfig.rst +3 -0
+If you think that kernel/init options become too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. …

Would you like to specify any settings in the boot configuration file because the provided storage capacity would be too limited by the kernel command line?

Yes.

Thank you,

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

Re: [PATCH v5.1] Documentation: bootconfig: Update boot configuration documentation

Quoted 2 lines

If you think you have "any more" update candidates, feel free to make an update "patch" and send to us.

I pointed a few change possibilities out already.

Quoted 1 line

That will be the next step.

I got the impression that we are in the process of constructing another patch together which will fix known wording weaknesses.

By the way:
I wonder about the shown version identifier.
Will the patch numbering need also further considerations?

Quoted 11 lines
Quoted 9 lines

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

Quoted 3 lines
Documentation/admin-guide/bootconfig.rst +3 -0
+If you think that kernel/init options become too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. …

Would you like to specify any settings in the boot configuration file because the provided storage capacity would be too limited by the kernel command line?

Yes.

How will affected places be improved after such an agreement?

Regards,
Markus

author maintainer
#28 lore raw

Re: [PATCH v5.1] Documentation: bootconfig: Update boot configuration documentation

Quoted 4 lines · On Fri, 6 Mar 2020 10:34:30 +0100 Markus Elfring <[email protected]> wrote:
Quoted 2 lines

If you think you have "any more" update candidates, feel free to make an update "patch" and send to us.

I pointed a few change possibilities out already.

I can not respond to requests only for possibility.

Quoted 4 lines
Quoted 1 line

That will be the next step.

I got the impression that we are in the process of constructing another patch together which will fix known wording weaknesses.

Would you mean the broken EBNF part? Yeah, maybe, but it is another story. I decided to drop it this time.
You can refine it but please use better format instead of such incomplete one.

Quoted 3 lines

By the way:
I wonder about the shown version identifier.
Will the patch numbering need also further considerations?

No.

Quoted 10 lines
Quoted 10 lines
Quoted 9 lines

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

Quoted 3 lines
Documentation/admin-guide/bootconfig.rst +3 -0
+If you think that kernel/init options become too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. …

Would you like to specify any settings in the boot configuration file because the provided storage capacity would be too limited by the kernel command line?

Quoted 3 lines
Quoted 1 line

Yes.

How will affected places be improved after such an agreement?

Would you please make a patch of new sentence?

Thank you,

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

Re: [v5.1] Documentation: bootconfig: Update boot configuration documentation

Quoted 4 lines
Quoted 2 lines

I got the impression that we are in the process of constructing another patch together which will fix known wording weaknesses.

Would you mean the broken EBNF part?

I hope that such software design approaches can also be reconsidered.

Quoted 1 line

Yeah, maybe, but it is another story.

Other concrete update suggestions are probably easier to integrate before. Which change opportunities will be picked up next?

Regards,
Markus

#30 lore raw

Re: [v5.1] Documentation: bootconfig: Update boot configuration documentation

In reply to Masami Hiramatsu
Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Quoted 9 lines

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

Quoted 3 lines
Documentation/admin-guide/bootconfig.rst +3 -0
+If you think that kernel/init options become too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. …

Would you like to specify any settings in the boot configuration file because the provided storage capacity would be too limited by the kernel command line?

Quoted 5 lines
Quoted 3 lines
Quoted 1 line

Yes.

How will affected places be improved after such an agreement?

Would you please make a patch of new sentence?

Not directly.

* If I would need to provide another wording alternative as a concrete patch, I would have to wait until previously accepted changes would become available in a Linux development repository.

* So I would find it easier to agree on wording variants during our current development discussion from which you would present results as a subsequent patch.

Regards,
Markus

#31 lore raw

Re: [PATCH v5.1] Documentation: bootconfig: Update boot configuration documentation

In reply to Masami Hiramatsu

…

Quoted 2 lines

Changes in v5.1:
- Fix some mistakes (Thanks Randy!)

…

Quoted 2 lines

Changes in v2:
- Fixes additional typos (Thanks Markus and Randy!)

…

Can such information trigger the addition of the tag “Reported-by”?
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=fffb08b37df928475fef9c7f2aafddc2f6ebfaf4#n584

Regards,
Markus

#32 lore raw

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

In reply to Masami Hiramatsu

…

Quoted 1 line

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

…

Documentation/admin-guide/bootconfig.rst Boot Configuration

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

Will remaining open issues get any attention for such software?

Will further collateral evolution happen around presented information?

Regards,
Markus

#33 lore raw

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

In reply to Masami Hiramatsu

…

Quoted 1 line

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

…

Quoted 1 line

… word must contain only alphabets, numbers, …

Would the wording “… alphanumeric characters …” be nicer?

Regards,
Markus

reviewer
#34 lore raw

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

Quoted 6 lines · Markus Elfring

…

Quoted 1 line

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

…

Quoted 1 line

… word must contain only alphabets, numbers, …

Would the wording “… alphanumeric characters …” be nicer?

Sure.

Signature · 1 line
~Randy