Documentation: bootconfig: Documentaiton updates
Subsystems (4)
Masami Hiramatsu
maintainerv3 cover Documentation: bootconfig: Documentaiton updates
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) <[email protected]>
Masami Hiramatsu
maintainerPATCH v3 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 v3:
- Specify that comments also count in size.
- Fix a confusing sentence.
- Add O=<builddir> to make command.
Changes in v2:
- Fixes additional typos (Thanks Markus and Randy!)
- Change a section title to "Tree Structured Key".
--- Documentation/admin-guide/bootconfig.rst | 181 +++++++++++++++++++----------- Documentation/trace/boottime-trace.rst | 2 2 files changed, 117 insertions(+), 66 deletions(-)
Documentation/admin-guide/bootconfig.rst +115 -66
@@ -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.
Documentation/trace/boottime-trace.rst +2 -0
@@ -1,5 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 +.. _boottimetrace: + ================= Boot-time tracing =================
Re: [v3 0/1] Documentation: bootconfig: Documentation updates
In reply to Masami HiramatsuQuoted 1 line
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
Re: [PATCH v3] 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.
I have got still understanding difficulties for this wording. How do you choose to distribute settings between the mentioned places?
Review
Quoted 2 lines
(quoted diff) +2
-0+Also, some features may depend on the boot configuration, and it has own +root key.
Will the key hierarchy need any further clarification?
Quoted 1 line
+ # make O=<builddir> -C
tools/bootconfig
Can the order of these parameters matter?
Quoted 1 line
+The boot configuration syntax is a simple structured key-value.
Would you like to discuss any extensions for such software?
Regards,
Markus
Jonathan Corbet
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
In reply to Masami HiramatsuQuoted 9 lines · On Mon, 2 Mar 2020 17:03:48 +0900 Masami Hiramatsu <[email protected]> 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 <[email protected]>
Quoted 9 lines
---
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
Steven Rostedt
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 22 lines · On Mon, 2 Mar 2020 12:50:33 -0700 Jonathan Corbet <[email protected]> wrote:
Quoted 9 lines · On Mon, 2 Mar 2020 17:03:48 +0900 Masami Hiramatsu <[email protected]> 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 <[email protected]>Quoted 9 lines
---
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".
---
Quoted 3 lines
So I tried to apply this but failed - it's built on other changes to
bootconfig.rstthat 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
Jonathan Corbet
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 7 lines · On Mon, 2 Mar 2020 15:08:02 -0500 Steven Rostedt <[email protected]> wrote:
Quoted 3 lines
So I tried to apply this but failed - it's built on other changes to
bootconfig.rstthat 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
Steven Rostedt
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 7 lines · On Mon, 2 Mar 2020 13:13:51 -0700 Jonathan Corbet <[email protected]> wrote:
Quoted 4 lines · On Mon, 2 Mar 2020 15:08:02 -0500 Steven Rostedt <[email protected]> wrote:
Quoted 3 lines
So I tried to apply this but failed - it's built on other changes to
bootconfig.rstthat went into linux-next via Steve's tree. So Steve, would you like to take this one too?
Quoted 7 lines
Quoted 3 lines
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
Randy Dunlap
reviewerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
In reply to Masami HiramatsuQuoted 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 6 lines
Signed-off-by Masami Hiramatsu <[email protected]>---
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.
Quoted 8 lines
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.
Signature · 2 lines
~Randy Reported-by: Randy Dunlap <[email protected]>
Masami Hiramatsu
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 17 lines · On Mon, 2 Mar 2020 17:52:36 -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 6 lines
Signed-off-by Masami Hiramatsu <[email protected]>---
Changes in v3:
- Specify that comments also count in size.
- Fix a confusing sentence.
- Add O=<builddir> to make command.
Quoted 8 lines
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...)
Quoted 11 lines
Quoted 9 lines
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(-)
Quoted 1 line
All of the other changes look good to me.
Thank you!
Quoted 5 lines
thanks.
Signature · 2 lines
~Randy Reported-by: Randy Dunlap <[email protected]>
Signature · 1 line
Masami Hiramatsu <[email protected]>
Masami Hiramatsu
maintainerRe: [PATCH v3] Documentation: bootconfig: Update boot configuration documentation
In reply to Steven RostedtQuoted 14 lines · On Mon, 2 Mar 2020 15:19:39 -0500 Steven Rostedt <[email protected]> wrote:
Quoted 11 lines · On Mon, 2 Mar 2020 13:13:51 -0700 Jonathan Corbet <[email protected]> wrote:
Quoted 7 lines · On Mon, 2 Mar 2020 15:08:02 -0500 Steven Rostedt <[email protected]> wrote:
Quoted 3 lines
So I tried to apply this but failed - it's built on other changes to
bootconfig.rstthat 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?
Quoted 7 lines
Quoted 3 lines
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!
Signature · 1 line
Masami Hiramatsu <[email protected]>
Re: [v3] Documentation: bootconfig: Update boot configuration documentation
In reply to Randy DunlapQuoted 1 line
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
Randy Dunlap
reviewerRe: [v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 5 lines · Markus Elfring
Quoted 1 line
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.
Signature · 1 line
~Randy
Re: [v3] Documentation: bootconfig: Update boot configuration documentation
Quoted 1 line
There are a few other things that I would change,
Would you like to mention these details?
Quoted 1 line
but I don't think that they are showstoppers.
This view can be fine.
Regards,
Markus