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?
> +
> +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.
> +
> +.. [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.
> +
> +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.
--
~Randy
