[PATCH 0/2] Documentation: bootconfig: Documentaiton updates

[PATCH 0/2] Documentation: bootconfig: Documentaiton updates

[Masami Hiramatsu]

Hello,

Here is a couple of patches to update the bootconfig documentation.
I hope this clarify what the boot configuration is :)

Thank you,

---

Masami Hiramatsu (2):
      Documentation: bootconfig: Update boot configuration documentation
      Documentation: bootconfig: Add EBNF syntax file


 Documentation/admin-guide/bootconfig.ebnf |   41 +++++++
 Documentation/admin-guide/bootconfig.rst  |  180 +++++++++++++++++++----------
 Documentation/trace/boottime-trace.rst    |    2 
 MAINTAINERS                               |    1 
 4 files changed, 162 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/admin-guide/bootconfig.ebnf

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

[PATCH 1/2] 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>
---
 Documentation/admin-guide/bootconfig.rst |  172 +++++++++++++++++++-----------
 Documentation/trace/boottime-trace.rst   |    2 
 2 files changed, 112 insertions(+), 62 deletions(-)

diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index cf2edcd09183..4bac98250bc0 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -11,19 +11,98 @@ Boot Configuration
 Overview
 ========
 
-The boot configuration expands the current kernel command line to support
+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.
+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 configurations), 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 one 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 want to comment on each options, you can use this
+boot configuration. If unsure, you can still continue to use the legacy
+kernel command line.
+
+Also, some subsystem may depend on the boot configuration, and it has own
+root key. For example, ftrace boot-time tracer uses "ftrace" root key to
+describe their options [2]_. In this case, you need to use 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 ``=``.
 
@@ -42,7 +121,7 @@ are used for checking if the key exists or not (like a boolean).
 Key-Value Syntax
 ----------------
 
-The boot config file syntax allows user to merge partially same word keys
+The boot configuration syntax allows user to merge partially same word keys
 by brace. For example::
 
  foo.bar.baz = value1
@@ -80,19 +159,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 +177,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 size 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 +254,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 1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

> +This allows administrators to pass a structured-Key configuration file

Does capitalisation matter here for the word “Key”?


> +If you think that kernel/init options becomes too long to write in boot-loader
> +configuration file or want to comment on each options, you can use this

Can the following wording variant be a bit nicer?

+… or you want to comment on each option, …


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

Would you like to explain the influence of a key hierarchy any further?


> +The boot configuration syntax allows user to merge partially same word keys
>  by brace. For example::

“by braces.
For example::”?


> +The file /proc/bootconfig is a user-space interface to the configuration

“… is an user-…”?


> +Currently the maximum configuration size is 32 KiB and the total number
> +of key-words and values must be under 1024 nodes.

* How were these constraints chosen?

* Can such system limits become more configurable?


> +(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".)

I would prefer the interpretation that nodes contain corresponding attributes.

How do you think about to add a link to a formal file format description?

Regards,
Markus

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Randy Dunlap]

On 2/27/20 11:12 AM, Markus Elfring wrote:
> 
>> +The boot configuration syntax allows user to merge partially same word keys
>>  by brace. For example::
> 
> “by braces.
> For example::”?

It is fine as Masami has it IMO.

> 
> 
>> +The file /proc/bootconfig is a user-space interface to the configuration
> 
> “… is an user-…”?

No, "is a user-space" or "is a userspace" is good.


-- 
~Randy

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu]

On Thu, 27 Feb 2020 20:12:17 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> > +This allows administrators to pass a structured-Key configuration file
> 
> Does capitalisation matter here for the word “Key”?

Oops, thanks! that's a typo of key.

> > +If you think that kernel/init options becomes too long to write in boot-loader
> > +configuration file or want to comment on each options, you can use this
> 
> Can the following wording variant be a bit nicer?
> 
> +… or you want to comment on each option, …

OK, since the previous sentence is too long, it is more readable to put the
subject there.

> > +Also, some subsystem may depend on the boot configuration, and it has own
> > +root key.
> 
> Would you like to explain the influence of a key hierarchy any further?

Please read the example (boot time tracer) carefully :)

> > +The boot configuration syntax allows user to merge partially same word keys
> >  by brace. For example::
> 
> “by braces.
> For example::”?

I think current one is shorter and compact.

> > +The file /proc/bootconfig is a user-space interface to the configuration
> 
> “… is an user-…”?

Hm, it seems "a user" is correct wording.
https://www.quora.com/Which-is-the-correct-usage-a-user-or-an-user

> > +Currently the maximum configuration size is 32 KiB and the total number
> > +of key-words and values must be under 1024 nodes.
> 
> * How were these constraints chosen?
> 
> * Can such system limits become more configurable?

No.

> > +(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".)
> 
> I would prefer the interpretation that nodes contain corresponding attributes.

No. Node is a node. It is merely generic.

> 
> How do you think about to add a link to a formal file format description?

Oh, nice idea. Please contribute it :)

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

>>> +Also, some subsystem may depend on the boot configuration, and it has own
>>> +root key.
>>
>> Would you like to explain the influence of a key hierarchy any further?
>
> Please read the example (boot time tracer) carefully :)

I find the descriptions still too terse for corresponding relationships.


>> * Can such system limits become more configurable?
>
> No.

The possibility remains to adjust the source code also for special needs.


>>> +(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".)
>>
>> I would prefer the interpretation that nodes contain corresponding attributes.
>
> No. Node is a node. It is merely generic.

I hope that the applied ontology will be clarified a bit more.


>> How do you think about to add a link to a formal file format description?
>
> Oh, nice idea. Please contribute it :)

Did you provide it (according to a RST include directive in the subsequent
update step)?

Can it be helpful to reorder any changes for the discussed patch series?

Regards,
Markus

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu]

On Fri, 28 Feb 2020 09:30:27 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> >> How do you think about to add a link to a formal file format description?
> >
> > Oh, nice idea. Please contribute it :)
> 
> Did you provide it (according to a RST include directive in the subsequent
> update step)?

No I didn't. I you think that is important, feel free to write up. You have
a parser code in the kernel already. It might be not hard for you. :)

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [1/2] Documentation: bootconfig: Update boot configuration documentation

[Markus Elfring]

>>>> How do you think about to add a link to a formal file format description?
>>>
>>> Oh, nice idea. Please contribute it :)
>>
>> Did you provide it (according to a RST include directive in the subsequent
>> update step)?
>
> No I didn't.

I hope that more progress can be achieved around the published suggestion
“bootconfig: Add EBNF syntax file”.
https://lore.kernel.org/linux-doc/158278836196.14966.3881489301852781521.stgit@devnote2/
https://lore.kernel.org/patchwork/patch/1200987/
https://lkml.org/lkml/2020/2/27/72


> I you think that is important, feel free to write up.

I am curious how the software development attention will evolve further.


> You have a parser code in the kernel already.

This software component is useful there.


> It might be not hard for you. :)

Some challenges are waiting on corresponding solutions.

Regards,
Markus

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Randy Dunlap]

Hi,
A few more comments for you:

On 2/26/20 11:25 PM, 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>
> ---
>  Documentation/admin-guide/bootconfig.rst |  172 +++++++++++++++++++-----------
>  Documentation/trace/boottime-trace.rst   |    2 
>  2 files changed, 112 insertions(+), 62 deletions(-)
> 
> diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> index cf2edcd09183..4bac98250bc0 100644
> --- a/Documentation/admin-guide/bootconfig.rst
> +++ b/Documentation/admin-guide/bootconfig.rst
> @@ -11,19 +11,98 @@ Boot Configuration
>  Overview
>  ========
>  
> -The boot configuration expands the current kernel command line to support
> +Boot configuration expands the current kernel command line to support
>  additional key-value data when booting the kernel in an efficient way.

                maybe      s/when/while/

> -This allows administrators to pass a structured-Key config file.
> +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 configurations), readability (structured

This makes it sound like bootconfig supports 32 thousand configurations, but
(I think) it allows up to 32 KiB of configuration data.

> +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 one under "init" root key are passed as a part

                                 ones  {or those}

> +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 want to comment on each options, you can use this

                                         on each option,

> +boot configuration. If unsure, you can still continue to use the legacy
> +kernel command line.
> +
> +Also, some subsystem may depend on the boot configuration, and it has own
> +root key. For example, ftrace boot-time tracer uses "ftrace" root key to
> +describe their options [2]_. In this case, you need to use the boot

            its

> +configuration.
> +
> +.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> +.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`


-- 
~Randy

Re: [PATCH 1/2] Documentation: bootconfig: Update boot configuration documentation

[Masami Hiramatsu]

On Thu, 27 Feb 2020 20:50:19 -0800
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi,
> A few more comments for you:
> 
> On 2/26/20 11:25 PM, 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>
> > ---
> >  Documentation/admin-guide/bootconfig.rst |  172 +++++++++++++++++++-----------
> >  Documentation/trace/boottime-trace.rst   |    2 
> >  2 files changed, 112 insertions(+), 62 deletions(-)
> > 
> > diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> > index cf2edcd09183..4bac98250bc0 100644
> > --- a/Documentation/admin-guide/bootconfig.rst
> > +++ b/Documentation/admin-guide/bootconfig.rst
> > @@ -11,19 +11,98 @@ Boot Configuration
> >  Overview
> >  ========
> >  
> > -The boot configuration expands the current kernel command line to support
> > +Boot configuration expands the current kernel command line to support
> >  additional key-value data when booting the kernel in an efficient way.
> 
>                 maybe      s/when/while/

Ah, right.

> 
> > -This allows administrators to pass a structured-Key config file.
> > +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 configurations), readability (structured
> 
> This makes it sound like bootconfig supports 32 thousand configurations, but
> (I think) it allows up to 32 KiB of configuration data.

OK, I'll add "data".

> 
> > +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 one under "init" root key are passed as a part
> 
>                                  ones  {or those}

OK.

> 
> > +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 want to comment on each options, you can use this
> 
>                                          on each option,

Oops, OK. 

> 
> > +boot configuration. If unsure, you can still continue to use the legacy
> > +kernel command line.
> > +
> > +Also, some subsystem may depend on the boot configuration, and it has own
> > +root key. For example, ftrace boot-time tracer uses "ftrace" root key to
> > +describe their options [2]_. In this case, you need to use the boot
> 
>             its

OK

Thank you!

> 
> > +configuration.
> > +
> > +.. [1] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
> > +.. [2] See :ref:`Documentation/trace/boottime-trace.rst <boottimetrace>`
> 
> 
> -- 
> ~Randy
> 


-- 
Masami Hiramatsu <mhiramat@kernel.org>

[PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Masami Hiramatsu]

Add an extended Backus–Naur form (EBNF) syntax file for
bootconfig so that user can logically understand how they
can write correct boot configuration file.

Signed-off-by: Masami Hiramatsu <mhiramat@kernel.org>
---
 Documentation/admin-guide/bootconfig.ebnf |   41 +++++++++++++++++++++++++++++
 Documentation/admin-guide/bootconfig.rst  |    8 ++++++
 MAINTAINERS                               |    1 +
 3 files changed, 50 insertions(+)
 create mode 100644 Documentation/admin-guide/bootconfig.ebnf

diff --git a/Documentation/admin-guide/bootconfig.ebnf b/Documentation/admin-guide/bootconfig.ebnf
new file mode 100644
index 000000000000..fe27007dc23f
--- /dev/null
+++ b/Documentation/admin-guide/bootconfig.ebnf
@@ -0,0 +1,41 @@
+# Boot Configuration Syntax in EBNF
+
+# Characters
+digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
+alphabet = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k"
+	| "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v"
+	| "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G"
+	| "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R"
+	| "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
+white space = ? white space characters (isspace() compatible ) ? ;
+all characters = ? all visible characters (isprint() compatible ) ? ;
+
+# Value definition
+value delimiter = "," | ";" | "\n" | "}" | "#" ;
+value string = { all characters - value delimiter } ;
+single quoted string = "'" , { all characters - "'" } , "'" ;
+double quoted string = '"' , { all characters - '"' } , '"' ;
+quoted string = double quoted string | single quoted string ;
+value = { white space }, quoted string | value string , { white space } ;
+
+# Non array value is equal to one-element array
+comment = "#" , { all characters - "\n" } , "\n" ;
+array delimiter = "," , { { white space }, ( comment | "\n" ) } ;
+array = { value , array delimiter } , value ;
+
+# Key definition
+key word character = alphabet | digit | "-" | "_" ;
+key word = { key word character } , key word character ;
+key = { white space } , { key word , "." } , key word , { white space } ;
+
+# Assignment definitions
+delimiter = { white space } , ( comment | ";" | "\n" ) ;
+assign operator = [ "+" ] , "=" ;
+assignment = key , [ assign operator , array ] ;
+assignment tree = key , "{" , { assignment sequence } , [ assignment ] , "}" ;
+assignment sequence = ( assignment , delimiter ) | assignment tree
+	| delimiter | white space ;
+
+# Boot configuration definition
+configuration = { assignment sequence } , (assignment | assignment tree)
+	, { delimiter | white space } ;
diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
index 4bac98250bc0..8d336af948a8 100644
--- a/Documentation/admin-guide/bootconfig.rst
+++ b/Documentation/admin-guide/bootconfig.rst
@@ -188,6 +188,14 @@ Note that you can not put a comment between value and delimiter(``,`` or
  key = 1 # !ERROR! comment is not allowed before delimiter
        ,2
 
+Syntax in EBNF
+--------------
+
+Here is the boot configuration file syntax written in EBNF.
+
+.. include:: bootconfig.ebnf
+   :literal:
+
 
 /proc/bootconfig
 ================
diff --git a/MAINTAINERS b/MAINTAINERS
index 47873f2e6696..3e792f0a2237 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15778,6 +15778,7 @@ F:	fs/proc/bootconfig.c
 F:	include/linux/bootconfig.h
 F:	tools/bootconfig/*
 F:	Documentation/admin-guide/bootconfig.rst
+F:	Documentation/admin-guide/bootconfig.ebnf
 
 SUN3/3X
 M:	Sam Creasey <sammy@sammy.net>

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Markus Elfring]

Thanks for such a contribution.


> Add an extended Backus–Naur form (EBNF) syntax file for

Can it matter to mention the specific file format specification version
which should be applied finally?

Would you like to refer to any standard variant?


> bootconfig so that user can logically understand how they

Wording alternative “… that users can …”?


> can write correct boot configuration file.

Related development tools provide some benefits then, don't they?



…
> +++ b/Documentation/admin-guide/bootconfig.ebnf
…
> +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Can the specification of such alternatives (or value ranges) become
more compact (depending on a selected standard)?


…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +Here is the boot configuration file syntax written in EBNF.

I suggest to replace the abbreviation “EBNF” by the term “extended Backus–Naur form”
in such a sentence.

Regards,
Markus

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Masami Hiramatsu]

On Thu, 27 Feb 2020 20:53:03 +0100
Markus Elfring <Markus.Elfring@web.de> wrote:

> Thanks for such a contribution.
> 
> 
> > Add an extended Backus–Naur form (EBNF) syntax file for
> 
> Can it matter to mention the specific file format specification version
> which should be applied finally?
> 
> Would you like to refer to any standard variant?

I choose ISO/IEC 14977 : 1996(E), but it seems no good.

Don’t Use ISO/IEC 14977 Extended Backus-Naur Form (EBNF)
https://dwheeler.com/essays/dont-use-iso-14977-ebnf.html

I agree with this article. the ISO 14977 is halfway...
Not easy for human, but not good for machine too.
(at least it should support #xN as same as W3C BNF.

I'll drop it until rewriten by other standerd.

> > bootconfig so that user can logically understand how they
> 
> Wording alternative “… that users can …”?
> 
> 
> > can write correct boot configuration file.
> 
> Related development tools provide some benefits then, don't they?
> 
> 
> 
> …
> > +++ b/Documentation/admin-guide/bootconfig.ebnf
> …
> > +digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
> 
> Can the specification of such alternatives (or value ranges) become
> more compact (depending on a selected standard)?

W3C EBNF support it, ISO14977 doesn't.

> …
> > +++ b/Documentation/admin-guide/bootconfig.rst
> …
> > +Here is the boot configuration file syntax written in EBNF.
> 
> I suggest to replace the abbreviation “EBNF” by the term “extended Backus–Naur form”
> in such a sentence.

I think EBNF is enough.

Thank you,

-- 
Masami Hiramatsu <mhiramat@kernel.org>

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Markus Elfring]

…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +.. include:: bootconfig.ebnf
> +   :literal:

Can the markup directive “code EBNF” be more appropriate for the discussed extension?

Regards,
Markus

Re: [PATCH 2/2] Documentation: bootconfig: Add EBNF syntax file

[Markus Elfring]

…
> +++ b/Documentation/admin-guide/bootconfig.rst
…
> +Syntax in EBNF
> +--------------
> +
> +Here is the boot configuration file syntax written in EBNF.
> +
> +.. include:: bootconfig.ebnf
> +   :literal:

How do you think about to move the content for this section into another RST file
so that it can be used as a text module?

Would you like to improve the outline and corresponding reuse
for such information any further?

Regards,
Markus