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

[Masami Hiramatsu]

On Fri, 28 Feb 2020 21:59:45 -0800
Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote:

> On 2/28/20 12:30 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@xxxxxxxxxx>
> > ---
> > Changes in v2:
> >  - Fixes additional typos (Thanks Markus and Randy!)
> >  - Change a section title to "Tree Structured Key".
> > ---
> >  Documentation/admin-guide/bootconfig.rst |  180 +++++++++++++++++++-----------
> >  Documentation/trace/boottime-trace.rst   |    2 
> >  2 files changed, 116 insertions(+), 66 deletions(-)
> > 
> > diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst
> > index cf2edcd09183..6a58d5e64896 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
> > -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), readability (structured
> > +configuration with comments) and compact expression of option groups.
> 
> Do the comments count in the 32 KiB of data?  I.e., is the max bootconfig
> file size 32 KiB?

Yes, the max bootconfig file size is 32 KiB. This could be fixed by filtering
out the comments by bootconfig tool.

> > +
> > +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 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 its options [2]_. In this case, you need to use the boot
> > +configuration.
> 
> Does this say that "ftrace" requires use of bootconfig?
> It seems to say that.

Ah, I got it. The last sentence is confusing. How about below?

"If you want to use the boot-time tracer, 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
> 
> Please make that honor O=builddir instead of building in the kernel
> source tree and ignoring O=builddir.

OK.

> 
> > +
> > +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"
> 
> 
> thanks.

Thanks for your review!

> -- 
> ~Randy
> 


-- 
Masami Hiramatsu <mhiramat@xxxxxxxxxx>