[PATCH v3 0/1] Documentation: bootconfig: Documentaiton updates

[PATCH v3 0/1] Documentation: bootconfig: Documentaiton updates

[Masami Hiramatsu]

Hi,

Here is the 3rd version of the documentation update.
I updated it according to Randy's comment.

Thank you,

---

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


 Documentation/admin-guide/bootconfig.rst |  181 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 117 insertions(+), 66 deletions(-)

--
Masami Hiramatsu (Linaro) <mhiramat@kernel.org>

[PATCH v3] Documentation: bootconfig: Update boot configuration documentation

[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.

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
---
Changes in v3:
 - Specify that comments also count in size.
 - Fix a confusing sentence.
 - Add O=<builddir> to make command.
Changes in v2:
 - Fixes additional typos (Thanks Markus and Randy!)
 - Change a section title to "Tree Structured Key".
---
 Documentation/admin-guide/bootconfig.rst |  181 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 117 insertions(+), 66 deletions(-)

diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index cf2edcd09183..0fb50d691627 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -11,19 +11,99 @@ Boot Configuration
 Overview
 ========
 
-The boot configuration expands the current kernel command line to support
-additional key-value data when booting the kernel in an efficient way.
-This allows administrators to pass a structured-Key config file.
+Boot configuration expands the current kernel command line to support
+additional key-value data while booting the kernel in an efficient way.
+This allows administrators to pass a structured key configuration file
+as a way to supplement the kernel command line to pass system boot parameters.
 
-Config File Syntax
-==================
+Compared with the kernel command line, the boot configuration can provide
+scalability (up to 32 KiB configuration data including comments), readability
+(structured configuration with comments) and compact expression of option
+groups.
+
+When to Use the Boot Configuration?
+-----------------------------------
+
+The boot configuration supports kernel command line options and init daemon
+boot options. All sub-keys under "kernel" root key are passed as a part of
+kernel command line [1]_, and ones under "init" root key are passed as a part
+of init command line. For example, ::
+
+   root=UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82 ro quiet splash console=ttyS0,115200n8 console=tty0
+
+This can be written as following boot configuration file.::
+
+   kernel {
+      root = "UUID=8cd79b08-bda0-4b9d-954c-5d5f34b98c82" # nvme0n1p3
+      ro       # mount rootfs as read only
+      quiet    # No console log
+      splash   # show splash image on boot screen
+      console = "ttyS0,115200n8" # 1st console to serial device
+      console += tty0            # add 2nd console
+   }
+
+If you think that kernel/init options becomes too long to write in boot-loader
+configuration file or you want to comment on each option, the boot
+configuration may be suitable. If unsure, you can still continue to use the
+legacy kernel command line.
+
+Also, some features may depend on the boot configuration, and it has own
+root key. For example, ftrace boot-time tracer uses "ftrace" root key to
+describe its options [2]_. If you want to use such features, you need to
+enable the boot configuration.
+
+.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
+.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`
+
+
+How to Use the Boot Configuration?
+----------------------------------
+
+To enable the boot configuration support on your kernel, it must be built with
+``CONFIG_BOOT_CONFIG=y`` and ``CONFIG_BLK_DEV_INITRD=y``.
+
+Next, you can write a boot configuration file and attach it to initrd image.
+
+The boot configuration file is attached to the end of the initrd (initramfs)
+image file with size, checksum and 12-byte magic word as below.
+
+[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n]
+
+The Linux kernel decodes the last part of the initrd image in memory to
+get the boot configuration data.
+Because of this "piggyback" method, there is no need to change or
+update the boot loader and the kernel image itself.
+
+To do this operation, Linux kernel provides "bootconfig" command under
+tools/bootconfig, which allows admin to apply or delete the configuration
+file to/from initrd image. You can build it by the following command::
+
+ # make O=<builddir> -C tools/bootconfig
+
+To add your boot configuration file to initrd image, run bootconfig as below
+(Old data is removed automatically if exists)::
 
-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``).
+ # <buildir>/tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
+
+To remove the configuration from the image, you can use -d option as below::
+
+ # <builddir>/tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
+
+At last, add ``bootconfig`` on the normal kernel command line to tell the
+kernel to look for the bootconfig at the end of the initrd file. For example::
+
+  GRUB_CMDLINE_LINUX="bootconfig"
+
+
+Boot Configuration Syntax
+=========================
+
+The boot configuration syntax is a simple structured key-value. Each key
+consists of dot-connected-words, and key and value are connected by ``=``.
+The value has to be terminated by semi-colon (``;``) or newline (``\n``).
 For array value, array entries are separated by comma (``,``). ::
 
-KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
+  KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
 
 Unlike the kernel command line syntax, spaces are OK around the comma and ``=``.
 
@@ -39,11 +119,11 @@ you can not escape these quotes.
 There can be a key which doesn't have value or has an empty value. Those keys
 are used for checking if the key exists or not (like a boolean).
 
-Key-Value Syntax
-----------------
+Tree Structured Key
+-------------------
 
-The boot config file syntax allows user to merge partially same word keys
-by brace. For example::
+The boot configuration syntax allows user to merge same parent key using
+braces as tree structured key. For example::
 
  foo.bar.baz = value1
  foo.bar.qux.quux = value2
@@ -80,19 +160,17 @@ you can use ``+=`` operator. For example::
 In this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``.
 
 However, a sub-key and a value can not co-exist under a parent key.
-For example, following config is NOT allowed.::
+For example, following configuration is NOT allowed.::
 
  foo = value1
- foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist
+ foo.bar = value2 # !ERROR! sub-key "bar" and value "value1" can NOT co-exist
 
 
 Comments
 --------
 
-The config syntax accepts shell-script style comments. The comments starting
-with hash ("#") until newline ("\n") will be ignored.
-
-::
+The boot configuration accepts shell-script style comments. The comments
+starting with hash (``#``) until newline (``\n``), will be skipped.::
 
  # comment line
  foo = value # value is set to foo.
@@ -100,74 +178,45 @@ with hash ("#") until newline ("\n") will be ignored.
        2, # 2nd element
        3  # 3rd element
 
-This is parsed as below::
+This is parsed as below.::
 
  foo = value
  bar = 1, 2, 3
 
 Note that you can not put a comment between value and delimiter(``,`` or
-``;``). This means following config has a syntax error ::
+``;``). This means following description has a syntax error. ::
 
- key = 1 # comment
+ key = 1 # !ERROR! comment is not allowed before delimiter
        ,2
 
 
 /proc/bootconfig
 ================
 
-/proc/bootconfig is a user-space interface of the boot config.
+The file /proc/bootconfig is a user-space interface to the configuration
+of system boot parameters.
 Unlike /proc/cmdline, this file shows the key-value style list.
 Each key-value pair is shown in each line with following style::
 
  KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...]
 
 
-Boot Kernel With a Boot Config
-==============================
-
-Since the boot configuration file is loaded with initrd, it will be added
-to the end of the initrd (initramfs) image file with size, checksum and
-12-byte magic word as below.
-
-[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n]
-
-The Linux kernel decodes the last part of the initrd image in memory to
-get the boot configuration data.
-Because of this "piggyback" method, there is no need to change or
-update the boot loader and the kernel image itself.
-
-To do this operation, Linux kernel provides "bootconfig" command under
-tools/bootconfig, which allows admin to apply or delete the config file
-to/from initrd image. You can build it by the following command::
-
- # make -C tools/bootconfig
-
-To add your boot config file to initrd image, run bootconfig as below
-(Old data is removed automatically if exists)::
-
- # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z
-
-To remove the config from the image, you can use -d option as below::
-
- # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
-
-Then add "bootconfig" on the normal kernel command line to tell the
-kernel to look for the bootconfig at the end of the initrd file.
-
 Config File Limitation
 ======================
 
-Currently the maximum config size size is 32KB and the total key-words (not
-key-value entries) must be under 1024 nodes.
-Note: this is not the number of entries but nodes, an entry must consume
-more than 2 nodes (a key-word and a value). So theoretically, it will be
-up to 512 key-value pairs. If keys contains 3 words in average, it can
-contain 256 key-value pairs. In most cases, the number of config items
-will be under 100 entries and smaller than 8KB, so it would be enough.
+Currently the maximum configuration file size (including comments) is 32 KiB
+and the total number of key-words and values must be under 1024 nodes.
+(Note: Each key consists of words separated by dot, and value also consists
+of values separated by comma. Here, each word and each value is generally
+called a "node".)
+Theoretically, it will be up to 512 key-value pairs. If keys contains 3
+words in average, it can contain 256 key-value pairs. In most cases,
+the number of configuration items will be under 100 entries and smaller
+than 8 KiB, so it would be enough.
 If the node number exceeds 1024, parser returns an error even if the file
-size is smaller than 32KB.
-Anyway, since bootconfig command verifies it when appending a boot config
-to initrd image, user can notice it before boot.
+size is smaller than 32 KiB.
+Anyway, since bootconfig command verifies it when appending a boot
+configuration to initrd image, user need to fix it before boot.
 
 
 Bootconfig APIs
@@ -206,7 +255,7 @@ or get the named array under prefix as below::
 This accesses a value of "key.prefix.option" and an array of
 "key.prefix.array-option".
 
-Locking is not needed, since after initialization, the config becomes
+Locking is not needed, since after initialization, the configuration becomes
 read-only. All data and keys must be copied if you need to modify it.
 
 
diff --git a/Documentation/trace/boottime-trace.rst b/Documentation/trace/boottime-trace.rst
index dcb390075ca1..e6cbe22361e9 100644
--- a/Documentation/trace/boottime-trace.rst
+++ b/Documentation/trace/boottime-trace.rst
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+.. _boottimetrace:
+
 =================
 Boot-time tracing
 =================

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

[Markus Elfring]

…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +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.

I have got still understanding difficulties for this wording.
How do you choose to distribute settings between the mentioned places?


> +Also, some features may depend on the boot configuration, and it has own
> +root key.

Will the key hierarchy need any further clarification?


> + # make O=<builddir> -C tools/bootconfig

Can the order of these parameters matter?


> +The boot configuration syntax is a simple structured key-value.

Would you like to discuss any extensions for such software?

Regards,
Markus

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

[Markus Elfring]

…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +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.

I have got still understanding difficulties for this wording.
How do you choose to distribute settings between the mentioned places?


> +Also, some features may depend on the boot configuration, and it has own
> +root key.

Will the key hierarchy need any further clarification?


> + # make O=<builddir> -C tools/bootconfig

Can the order of these parameters matter?


> +The boot configuration syntax is a simple structured key-value.

Would you like to discuss any extensions for such software?

Regards,
Markus

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

[Jonathan Corbet]

On Mon,  2 Mar 2020 17:03:48 +0900
Masami Hiramatsu <mhiramat@kernel.org> wrote:

> Update boot configuration documentation.
> 
>  - Not using "config" abbreviation but configuration or description.
>  - Rewrite descriptions of node and its maxinum number.
>  - Add a section of use cases of boot configuration.
>  - Move how to use bootconfig to earlier section.
>  - Fix some typos, indents and format mistakes.
> 
> Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> ---
> Changes in 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".
> ---

So I tried to apply this but failed - it's built on other changes to
bootconfig.rst that went into linux-next via Steve's tree.  So Steve,
would you like to take this one too?

Thanks,

jon

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

[Steven Rostedt]

On Mon, 2 Mar 2020 12:50:33 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> On Mon,  2 Mar 2020 17:03:48 +0900
> Masami Hiramatsu <mhiramat@kernel.org> wrote:
> 
> > Update boot configuration documentation.
> > 
> >  - Not using "config" abbreviation but configuration or description.
> >  - Rewrite descriptions of node and its maxinum number.
> >  - Add a section of use cases of boot configuration.
> >  - Move how to use bootconfig to earlier section.
> >  - Fix some typos, indents and format mistakes.
> > 
> > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > ---
> > Changes in 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".
> > ---  
> 
> So I tried to apply this but failed - it's built on other changes to
> bootconfig.rst that went into linux-next via Steve's tree.  So Steve,
> would you like to take this one too?

All my changes in linux-next have already hit Linus's tree. I haven't
started pushing my next merge window changes yet. Are you up to date with
Linus?

-- Steve

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

[Jonathan Corbet]

On Mon, 2 Mar 2020 15:08:02 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> > So I tried to apply this but failed - it's built on other changes to
> > bootconfig.rst that went into linux-next via Steve's tree.  So Steve,
> > would you like to take this one too?  
> 
> All my changes in linux-next have already hit Linus's tree. I haven't
> started pushing my next merge window changes yet. Are you up to date with
> Linus?

I try not to do too many backmerges with mainline, so no.  I can pull
forward if I have to, I guess.

jon

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

[Steven Rostedt]

On Mon, 2 Mar 2020 13:13:51 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> On Mon, 2 Mar 2020 15:08:02 -0500
> Steven Rostedt <rostedt@goodmis.org> wrote:
> 
> > > So I tried to apply this but failed - it's built on other changes to
> > > bootconfig.rst that went into linux-next via Steve's tree.  So Steve,
> > > would you like to take this one too?    
> > 
> > All my changes in linux-next have already hit Linus's tree. I haven't
> > started pushing my next merge window changes yet. Are you up to date with
> > Linus?  
> 
> I try not to do too many backmerges with mainline, so no.  I can pull
> forward if I have to, I guess.
>

I can add it to my tree, but I may not send it to Linus unless I have
another urgent request to send to him. So it may not make it till the next
merge window.

-- Steve

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

[Masami Hiramatsu]

On Mon, 2 Mar 2020 15:19:39 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> On Mon, 2 Mar 2020 13:13:51 -0700
> Jonathan Corbet <corbet@lwn.net> wrote:
> 
> > On Mon, 2 Mar 2020 15:08:02 -0500
> > Steven Rostedt <rostedt@goodmis.org> wrote:
> > 
> > > > So I tried to apply this but failed - it's built on other changes to
> > > > bootconfig.rst that went into linux-next via Steve's tree.  So Steve,
> > > > would you like to take this one too?    
> > > 
> > > All my changes in linux-next have already hit Linus's tree. I haven't
> > > started pushing my next merge window changes yet. Are you up to date with
> > > Linus?  
> > 
> > I try not to do too many backmerges with mainline, so no.  I can pull
> > forward if I have to, I guess.
> >
> 
> I can add it to my tree, but I may not send it to Linus unless I have
> another urgent request to send to him. So it may not make it till the next
> merge window.

OK, then I'll wait for the next window. Anyway, I found a mistake and
it needs to be updated (again).

Thank you!


-- 
Masami Hiramatsu <mhiramat@kernel.org>

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

[Randy Dunlap]

On 3/2/20 12:03 AM, Masami Hiramatsu wrote:
> Update boot configuration documentation.
> 
>  - Not using "config" abbreviation but configuration or description.
>  - Rewrite descriptions of node and its maxinum number.
>  - Add a section of use cases of boot configuration.
>  - Move how to use bootconfig to earlier section.
>  - Fix some typos, indents and format mistakes.
> 
> Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> ---
> Changes in v3:
>  - Specify that comments also count in size.
>  - Fix a confusing sentence.
>  - Add O=<builddir> to make command.


Hi Masami-san,

I think that you misunderstood me.  I am asking that you
make "make O=builddir -C tools/bootconfig" work properly, i.e.,
the bootconfig binary should be built in the <builddir>.

Presently when I enter that command, the bootconfig binary
is still built in the kernel source tree.

> 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(-)
> 


All of the other changes look good to me.

thanks.
-- 
~Randy
Reported-by: Randy Dunlap <rdunlap@infradead.org>

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

[Masami Hiramatsu]

On Mon, 2 Mar 2020 17:52:36 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 3/2/20 12:03 AM, Masami Hiramatsu wrote:
> > Update boot configuration documentation.
> > 
> >  - Not using "config" abbreviation but configuration or description.
> >  - Rewrite descriptions of node and its maxinum number.
> >  - Add a section of use cases of boot configuration.
> >  - Move how to use bootconfig to earlier section.
> >  - Fix some typos, indents and format mistakes.
> > 
> > Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
> > ---
> > Changes in v3:
> >  - Specify that comments also count in size.
> >  - Fix a confusing sentence.
> >  - Add O=<builddir> to make command.
> 
> 
> Hi Masami-san,
> 
> I think that you misunderstood me.  I am asking that you
> make "make O=builddir -C tools/bootconfig" work properly, i.e.,
> the bootconfig binary should be built in the <builddir>.
> 
> Presently when I enter that command, the bootconfig binary
> is still built in the kernel source tree.

Oops, that's my mistake! It needs to be fixed soon.
Thank you for reporting it!

(Also, I misunderstood what O= option means for tools...)

> 
> > 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(-)
> > 
> 
> 
> All of the other changes look good to me.

Thank you!



> 
> thanks.
> -- 
> ~Randy
> Reported-by: Randy Dunlap <rdunlap@infradead.org>


-- 
Masami Hiramatsu <mhiramat@kernel.org>

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

[Markus Elfring]

> All of the other changes look good to me.

I suggest to take another closer look.
Would you like to help with the clarification of any remaining
software documentation concerns?

Regards,
Markus

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

[Randy Dunlap]

On 3/2/20 10:52 PM, Markus Elfring wrote:
>> All of the other changes look good to me.
> 
> I suggest to take another closer look.
> Would you like to help with the clarification of any remaining
> software documentation concerns?

There are a few other things that I would change, but I don't think
that they are showstoppers.

-- 
~Randy

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

[Markus Elfring]

> There are a few other things that I would change,

Would you like to mention these details?


> but I don't think that they are showstoppers.

This view can be fine.

Regards,
Markus

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

[Markus Elfring]

> Here is the 3rd version of the documentation update.

I suggest to omit a cover letter for such information
(according to a single patch).
The repetition of a typo would be also avoided then.

Regards,
Markus