17b9b816fSMasami Hiramatsu.. SPDX-License-Identifier: GPL-2.0 27b9b816fSMasami Hiramatsu 347781947SMasami Hiramatsu.. _bootconfig: 447781947SMasami Hiramatsu 57b9b816fSMasami Hiramatsu================== 67b9b816fSMasami HiramatsuBoot Configuration 77b9b816fSMasami Hiramatsu================== 87b9b816fSMasami Hiramatsu 97b9b816fSMasami Hiramatsu:Author: Masami Hiramatsu <mhiramat@kernel.org> 107b9b816fSMasami Hiramatsu 117b9b816fSMasami HiramatsuOverview 127b9b816fSMasami Hiramatsu======== 137b9b816fSMasami Hiramatsu 14a4798eb4SMasami HiramatsuThe boot configuration expands the current kernel command line to support 15a4798eb4SMasami Hiramatsuadditional key-value data when booting the kernel in an efficient way. 16a4798eb4SMasami HiramatsuThis allows administrators to pass a structured-Key config file. 177b9b816fSMasami Hiramatsu 187b9b816fSMasami HiramatsuConfig File Syntax 197b9b816fSMasami Hiramatsu================== 207b9b816fSMasami Hiramatsu 217b9b816fSMasami HiramatsuThe boot config syntax is a simple structured key-value. Each key consists 22a4798eb4SMasami Hiramatsuof dot-connected-words, and key and value are connected by ``=``. The value 237b9b816fSMasami Hiramatsuhas to be terminated by semi-colon (``;``) or newline (``\n``). 247b9b816fSMasami HiramatsuFor array value, array entries are separated by comma (``,``). :: 257b9b816fSMasami Hiramatsu 267b9b816fSMasami Hiramatsu KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] 277b9b816fSMasami Hiramatsu 28a4798eb4SMasami HiramatsuUnlike the kernel command line syntax, spaces are OK around the comma and ``=``. 29a4798eb4SMasami Hiramatsu 307b9b816fSMasami HiramatsuEach key word must contain only alphabets, numbers, dash (``-``) or underscore 317b9b816fSMasami Hiramatsu(``_``). And each value only contains printable characters or spaces except 327b9b816fSMasami Hiramatsufor delimiters such as semi-colon (``;``), new-line (``\n``), comma (``,``), 337b9b816fSMasami Hiramatsuhash (``#``) and closing brace (``}``). 347b9b816fSMasami Hiramatsu 357b9b816fSMasami HiramatsuIf you want to use those delimiters in a value, you can use either double- 367b9b816fSMasami Hiramatsuquotes (``"VALUE"``) or single-quotes (``'VALUE'``) to quote it. Note that 377b9b816fSMasami Hiramatsuyou can not escape these quotes. 387b9b816fSMasami Hiramatsu 397b9b816fSMasami HiramatsuThere can be a key which doesn't have value or has an empty value. Those keys 40a4798eb4SMasami Hiramatsuare used for checking if the key exists or not (like a boolean). 417b9b816fSMasami Hiramatsu 427b9b816fSMasami HiramatsuKey-Value Syntax 437b9b816fSMasami Hiramatsu---------------- 447b9b816fSMasami Hiramatsu 457b9b816fSMasami HiramatsuThe boot config file syntax allows user to merge partially same word keys 467b9b816fSMasami Hiramatsuby brace. For example:: 477b9b816fSMasami Hiramatsu 487b9b816fSMasami Hiramatsu foo.bar.baz = value1 497b9b816fSMasami Hiramatsu foo.bar.qux.quux = value2 507b9b816fSMasami Hiramatsu 517b9b816fSMasami HiramatsuThese can be written also in:: 527b9b816fSMasami Hiramatsu 537b9b816fSMasami Hiramatsu foo.bar { 547b9b816fSMasami Hiramatsu baz = value1 557b9b816fSMasami Hiramatsu qux.quux = value2 567b9b816fSMasami Hiramatsu } 577b9b816fSMasami Hiramatsu 587b9b816fSMasami HiramatsuOr more shorter, written as following:: 597b9b816fSMasami Hiramatsu 607b9b816fSMasami Hiramatsu foo.bar { baz = value1; qux.quux = value2 } 617b9b816fSMasami Hiramatsu 627b9b816fSMasami HiramatsuIn both styles, same key words are automatically merged when parsing it 637b9b816fSMasami Hiramatsuat boot time. So you can append similar trees or key-values. 647b9b816fSMasami Hiramatsu 654e4694d8SMasami HiramatsuSame-key Values 664e4694d8SMasami Hiramatsu--------------- 674e4694d8SMasami Hiramatsu 684e4694d8SMasami HiramatsuIt is prohibited that two or more values or arrays share a same-key. 694e4694d8SMasami HiramatsuFor example,:: 704e4694d8SMasami Hiramatsu 714e4694d8SMasami Hiramatsu foo = bar, baz 724e4694d8SMasami Hiramatsu foo = qux # !ERROR! we can not re-define same key 734e4694d8SMasami Hiramatsu 74c58b46cbSMasami HiramatsuIf you want to update the value, you must use the override operator 75c58b46cbSMasami Hiramatsu``:=`` explicitly. For example:: 76c58b46cbSMasami Hiramatsu 77c58b46cbSMasami Hiramatsu foo = bar, baz 78c58b46cbSMasami Hiramatsu foo := qux 79c58b46cbSMasami Hiramatsu 80c58b46cbSMasami Hiramatsuthen, the ``qux`` is assigned to ``foo`` key. This is useful for 81c58b46cbSMasami Hiramatsuoverriding the default value by adding (partial) custom bootconfigs 82c58b46cbSMasami Hiramatsuwithout parsing the default bootconfig. 83c58b46cbSMasami Hiramatsu 845f811c57SMasami HiramatsuIf you want to append the value to existing key as an array member, 855f811c57SMasami Hiramatsuyou can use ``+=`` operator. For example:: 865f811c57SMasami Hiramatsu 875f811c57SMasami Hiramatsu foo = bar, baz 885f811c57SMasami Hiramatsu foo += qux 895f811c57SMasami Hiramatsu 905f811c57SMasami HiramatsuIn this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``. 915f811c57SMasami Hiramatsu 920ff2bb7dSMasami HiramatsuMoreover, sub-keys and a value can coexist under a parent key. 930ff2bb7dSMasami HiramatsuFor example, following config is allowed.:: 94a24d286fSMasami Hiramatsu 95a24d286fSMasami Hiramatsu foo = value1 960ff2bb7dSMasami Hiramatsu foo.bar = value2 970ff2bb7dSMasami Hiramatsu foo := value3 # This will update foo's value. 98a24d286fSMasami Hiramatsu 990ff2bb7dSMasami HiramatsuNote, since there is no syntax to put a raw value directly under a 1000ff2bb7dSMasami Hiramatsustructured key, you have to define it outside of the brace. For example:: 1010ff2bb7dSMasami Hiramatsu 1020ff2bb7dSMasami Hiramatsu foo { 1030ff2bb7dSMasami Hiramatsu bar = value1 1040ff2bb7dSMasami Hiramatsu bar { 1050ff2bb7dSMasami Hiramatsu baz = value2 1060ff2bb7dSMasami Hiramatsu qux = value3 1070ff2bb7dSMasami Hiramatsu } 1080ff2bb7dSMasami Hiramatsu } 1090ff2bb7dSMasami Hiramatsu 1100ff2bb7dSMasami HiramatsuAlso, the order of the value node under a key is fixed. If there 1110ff2bb7dSMasami Hiramatsuare a value and subkeys, the value is always the first child node 1120ff2bb7dSMasami Hiramatsuof the key. Thus if user specifies subkeys first, e.g.:: 1130ff2bb7dSMasami Hiramatsu 1140ff2bb7dSMasami Hiramatsu foo.bar = value1 1150ff2bb7dSMasami Hiramatsu foo = value2 1160ff2bb7dSMasami Hiramatsu 1170ff2bb7dSMasami HiramatsuIn the program (and /proc/bootconfig), it will be shown as below:: 1180ff2bb7dSMasami Hiramatsu 1190ff2bb7dSMasami Hiramatsu foo = value2 1200ff2bb7dSMasami Hiramatsu foo.bar = value1 121a24d286fSMasami Hiramatsu 1227b9b816fSMasami HiramatsuComments 1237b9b816fSMasami Hiramatsu-------- 1247b9b816fSMasami Hiramatsu 125a4798eb4SMasami HiramatsuThe config syntax accepts shell-script style comments. The comments starting 1267b9b816fSMasami Hiramatsuwith hash ("#") until newline ("\n") will be ignored. 1277b9b816fSMasami Hiramatsu 1287b9b816fSMasami Hiramatsu:: 1297b9b816fSMasami Hiramatsu 1307b9b816fSMasami Hiramatsu # comment line 1317b9b816fSMasami Hiramatsu foo = value # value is set to foo. 1327b9b816fSMasami Hiramatsu bar = 1, # 1st element 1337b9b816fSMasami Hiramatsu 2, # 2nd element 1347b9b816fSMasami Hiramatsu 3 # 3rd element 1357b9b816fSMasami Hiramatsu 1367b9b816fSMasami HiramatsuThis is parsed as below:: 1377b9b816fSMasami Hiramatsu 1387b9b816fSMasami Hiramatsu foo = value 1397b9b816fSMasami Hiramatsu bar = 1, 2, 3 1407b9b816fSMasami Hiramatsu 1417b9b816fSMasami HiramatsuNote that you can not put a comment between value and delimiter(``,`` or 1427b9b816fSMasami Hiramatsu``;``). This means following config has a syntax error :: 1437b9b816fSMasami Hiramatsu 1447b9b816fSMasami Hiramatsu key = 1 # comment 1457b9b816fSMasami Hiramatsu ,2 1467b9b816fSMasami Hiramatsu 1477b9b816fSMasami Hiramatsu 1487b9b816fSMasami Hiramatsu/proc/bootconfig 1497b9b816fSMasami Hiramatsu================ 1507b9b816fSMasami Hiramatsu 1517b9b816fSMasami Hiramatsu/proc/bootconfig is a user-space interface of the boot config. 1527b9b816fSMasami HiramatsuUnlike /proc/cmdline, this file shows the key-value style list. 1537b9b816fSMasami HiramatsuEach key-value pair is shown in each line with following style:: 1547b9b816fSMasami Hiramatsu 1557b9b816fSMasami Hiramatsu KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] 1567b9b816fSMasami Hiramatsu 1577b9b816fSMasami Hiramatsu 1587b9b816fSMasami HiramatsuBoot Kernel With a Boot Config 1597b9b816fSMasami Hiramatsu============================== 1607b9b816fSMasami Hiramatsu 1612f51efc6SMasami HiramatsuThere are two options to boot the kernel with bootconfig: attaching the 1622f51efc6SMasami Hiramatsubootconfig to the initrd image or embedding it in the kernel itself. 1632f51efc6SMasami Hiramatsu 1642f51efc6SMasami HiramatsuAttaching a Boot Config to Initrd 1652f51efc6SMasami Hiramatsu--------------------------------- 1662f51efc6SMasami Hiramatsu 1672f51efc6SMasami HiramatsuSince the boot configuration file is loaded with initrd by default, 1682f51efc6SMasami Hiramatsuit will be added to the end of the initrd (initramfs) image file with 1692f51efc6SMasami Hiramatsupadding, size, checksum and 12-byte magic word as below. 17085c46b78SMasami Hiramatsu 17105227490SMasami Hiramatsu[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n] 17205227490SMasami Hiramatsu 17305227490SMasami HiramatsuThe size and checksum fields are unsigned 32bit little endian value. 174fbc6e1c6SMasami Hiramatsu 175fbc6e1c6SMasami HiramatsuWhen the boot configuration is added to the initrd image, the total 176fbc6e1c6SMasami Hiramatsufile size is aligned to 4 bytes. To fill the gap, null characters 177fbc6e1c6SMasami Hiramatsu(``\0``) will be added. Thus the ``size`` is the length of the bootconfig 178fbc6e1c6SMasami Hiramatsufile + padding bytes. 17985c46b78SMasami Hiramatsu 18085c46b78SMasami HiramatsuThe Linux kernel decodes the last part of the initrd image in memory to 18185c46b78SMasami Hiramatsuget the boot configuration data. 1827b9b816fSMasami HiramatsuBecause of this "piggyback" method, there is no need to change or 183fbc6e1c6SMasami Hiramatsuupdate the boot loader and the kernel image itself as long as the boot 184fbc6e1c6SMasami Hiramatsuloader passes the correct initrd file size. If by any chance, the boot 1859d54ee78SBhaskar Chowdhuryloader passes a longer size, the kernel fails to find the bootconfig data. 1867b9b816fSMasami Hiramatsu 18726c9c72fSMasami HiramatsuTo do this operation, Linux kernel provides ``bootconfig`` command under 1887b9b816fSMasami Hiramatsutools/bootconfig, which allows admin to apply or delete the config file 189a4798eb4SMasami Hiramatsuto/from initrd image. You can build it by the following command:: 1907b9b816fSMasami Hiramatsu 1917b9b816fSMasami Hiramatsu # make -C tools/bootconfig 1927b9b816fSMasami Hiramatsu 1937b9b816fSMasami HiramatsuTo add your boot config file to initrd image, run bootconfig as below 1947b9b816fSMasami Hiramatsu(Old data is removed automatically if exists):: 1957b9b816fSMasami Hiramatsu 1967b9b816fSMasami Hiramatsu # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z 1977b9b816fSMasami Hiramatsu 1987b9b816fSMasami HiramatsuTo remove the config from the image, you can use -d option as below:: 1997b9b816fSMasami Hiramatsu 2007b9b816fSMasami Hiramatsu # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z 2017b9b816fSMasami Hiramatsu 2027495e092SSteven Rostedt (VMware)Then add "bootconfig" on the normal kernel command line to tell the 2037495e092SSteven Rostedt (VMware)kernel to look for the bootconfig at the end of the initrd file. 204*b743852cSPaul E. McKenneyAlternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE`` 205*b743852cSPaul E. McKenneyKconfig option selected. 2067b9b816fSMasami Hiramatsu 2072f51efc6SMasami HiramatsuEmbedding a Boot Config into Kernel 2082f51efc6SMasami Hiramatsu----------------------------------- 2092f51efc6SMasami Hiramatsu 2102f51efc6SMasami HiramatsuIf you can not use initrd, you can also embed the bootconfig file in the 2112f51efc6SMasami Hiramatsukernel by Kconfig options. In this case, you need to recompile the kernel 2122f51efc6SMasami Hiramatsuwith the following configs:: 2132f51efc6SMasami Hiramatsu 2142f51efc6SMasami Hiramatsu CONFIG_BOOT_CONFIG_EMBED=y 2152f51efc6SMasami Hiramatsu CONFIG_BOOT_CONFIG_EMBED_FILE="/PATH/TO/BOOTCONFIG/FILE" 2162f51efc6SMasami Hiramatsu 2172f51efc6SMasami Hiramatsu``CONFIG_BOOT_CONFIG_EMBED_FILE`` requires an absolute path or a relative 2182f51efc6SMasami Hiramatsupath to the bootconfig file from source tree or object tree. 2192f51efc6SMasami HiramatsuThe kernel will embed it as the default bootconfig. 2202f51efc6SMasami Hiramatsu 2212f51efc6SMasami HiramatsuJust as when attaching the bootconfig to the initrd, you need ``bootconfig`` 222*b743852cSPaul E. McKenneyoption on the kernel command line to enable the embedded bootconfig, or, 223*b743852cSPaul E. McKenneyalternatively, build your kernel with the ``CONFIG_BOOT_CONFIG_FORCE`` 224*b743852cSPaul E. McKenneyKconfig option selected. 2252f51efc6SMasami Hiramatsu 2262f51efc6SMasami HiramatsuNote that even if you set this option, you can override the embedded 2272f51efc6SMasami Hiramatsubootconfig by another bootconfig which attached to the initrd. 22826c9c72fSMasami Hiramatsu 22926c9c72fSMasami HiramatsuKernel parameters via Boot Config 23026c9c72fSMasami Hiramatsu================================= 23126c9c72fSMasami Hiramatsu 23226c9c72fSMasami HiramatsuIn addition to the kernel command line, the boot config can be used for 23326c9c72fSMasami Hiramatsupassing the kernel parameters. All the key-value pairs under ``kernel`` 23426c9c72fSMasami Hiramatsukey will be passed to kernel cmdline directly. Moreover, the key-value 23526c9c72fSMasami Hiramatsupairs under ``init`` will be passed to init process via the cmdline. 236e378cb9aSKushagra VermaThe parameters are concatenated with user-given kernel cmdline string 23726c9c72fSMasami Hiramatsuas the following order, so that the command line parameter can override 23826c9c72fSMasami Hiramatsubootconfig parameters (this depends on how the subsystem handles parameters 23926c9c72fSMasami Hiramatsubut in general, earlier parameter will be overwritten by later one.):: 24026c9c72fSMasami Hiramatsu 24126c9c72fSMasami Hiramatsu [bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params] 24226c9c72fSMasami Hiramatsu 24326c9c72fSMasami HiramatsuHere is an example of the bootconfig file for kernel/init parameters.:: 24426c9c72fSMasami Hiramatsu 24526c9c72fSMasami Hiramatsu kernel { 24626c9c72fSMasami Hiramatsu root = 01234567-89ab-cdef-0123-456789abcd 24726c9c72fSMasami Hiramatsu } 24826c9c72fSMasami Hiramatsu init { 24926c9c72fSMasami Hiramatsu splash 25026c9c72fSMasami Hiramatsu } 25126c9c72fSMasami Hiramatsu 25226c9c72fSMasami HiramatsuThis will be copied into the kernel cmdline string as the following:: 25326c9c72fSMasami Hiramatsu 25426c9c72fSMasami Hiramatsu root="01234567-89ab-cdef-0123-456789abcd" -- splash 25526c9c72fSMasami Hiramatsu 25626c9c72fSMasami HiramatsuIf user gives some other command line like,:: 25726c9c72fSMasami Hiramatsu 25826c9c72fSMasami Hiramatsu ro bootconfig -- quiet 25926c9c72fSMasami Hiramatsu 26026c9c72fSMasami HiramatsuThe final kernel cmdline will be the following:: 26126c9c72fSMasami Hiramatsu 26226c9c72fSMasami Hiramatsu root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet 26326c9c72fSMasami Hiramatsu 26426c9c72fSMasami Hiramatsu 2657b9b816fSMasami HiramatsuConfig File Limitation 2667b9b816fSMasami Hiramatsu====================== 2677b9b816fSMasami Hiramatsu 2687b9b816fSMasami HiramatsuCurrently the maximum config size size is 32KB and the total key-words (not 2697b9b816fSMasami Hiramatsukey-value entries) must be under 1024 nodes. 2707b9b816fSMasami HiramatsuNote: this is not the number of entries but nodes, an entry must consume 2717b9b816fSMasami Hiramatsumore than 2 nodes (a key-word and a value). So theoretically, it will be 2727b9b816fSMasami Hiramatsuup to 512 key-value pairs. If keys contains 3 words in average, it can 2737b9b816fSMasami Hiramatsucontain 256 key-value pairs. In most cases, the number of config items 2747b9b816fSMasami Hiramatsuwill be under 100 entries and smaller than 8KB, so it would be enough. 2757b9b816fSMasami HiramatsuIf the node number exceeds 1024, parser returns an error even if the file 276fbc6e1c6SMasami Hiramatsusize is smaller than 32KB. (Note that this maximum size is not including 277fbc6e1c6SMasami Hiramatsuthe padding null characters.) 2787b9b816fSMasami HiramatsuAnyway, since bootconfig command verifies it when appending a boot config 2797b9b816fSMasami Hiramatsuto initrd image, user can notice it before boot. 2807b9b816fSMasami Hiramatsu 2817b9b816fSMasami Hiramatsu 2827b9b816fSMasami HiramatsuBootconfig APIs 2837b9b816fSMasami Hiramatsu=============== 2847b9b816fSMasami Hiramatsu 2857b9b816fSMasami HiramatsuUser can query or loop on key-value pairs, also it is possible to find 2867b9b816fSMasami Hiramatsua root (prefix) key node and find key-values under that node. 2877b9b816fSMasami Hiramatsu 2887b9b816fSMasami HiramatsuIf you have a key string, you can query the value directly with the key 289a4798eb4SMasami Hiramatsuusing xbc_find_value(). If you want to know what keys exist in the boot 290a4798eb4SMasami Hiramatsuconfig, you can use xbc_for_each_key_value() to iterate key-value pairs. 2917b9b816fSMasami HiramatsuNote that you need to use xbc_array_for_each_value() for accessing 292a4798eb4SMasami Hiramatsueach array's value, e.g.:: 2937b9b816fSMasami Hiramatsu 2947b9b816fSMasami Hiramatsu vnode = NULL; 2957b9b816fSMasami Hiramatsu xbc_find_value("key.word", &vnode); 2967b9b816fSMasami Hiramatsu if (vnode && xbc_node_is_array(vnode)) 2977b9b816fSMasami Hiramatsu xbc_array_for_each_value(vnode, value) { 2987b9b816fSMasami Hiramatsu printk("%s ", value); 2997b9b816fSMasami Hiramatsu } 3007b9b816fSMasami Hiramatsu 301a4798eb4SMasami HiramatsuIf you want to focus on keys which have a prefix string, you can use 302a4798eb4SMasami Hiramatsuxbc_find_node() to find a node by the prefix string, and iterate 3037b9b816fSMasami Hiramatsukeys under the prefix node with xbc_node_for_each_key_value(). 3047b9b816fSMasami Hiramatsu 3057b9b816fSMasami HiramatsuBut the most typical usage is to get the named value under prefix 3067b9b816fSMasami Hiramatsuor get the named array under prefix as below:: 3077b9b816fSMasami Hiramatsu 3087b9b816fSMasami Hiramatsu root = xbc_find_node("key.prefix"); 3097b9b816fSMasami Hiramatsu value = xbc_node_find_value(root, "option", &vnode); 3107b9b816fSMasami Hiramatsu ... 3117b9b816fSMasami Hiramatsu xbc_node_for_each_array_value(root, "array-option", value, anode) { 3127b9b816fSMasami Hiramatsu ... 3137b9b816fSMasami Hiramatsu } 3147b9b816fSMasami Hiramatsu 3157b9b816fSMasami HiramatsuThis accesses a value of "key.prefix.option" and an array of 3167b9b816fSMasami Hiramatsu"key.prefix.array-option". 3177b9b816fSMasami Hiramatsu 318a4798eb4SMasami HiramatsuLocking is not needed, since after initialization, the config becomes 319a4798eb4SMasami Hiramatsuread-only. All data and keys must be copied if you need to modify it. 3207b9b816fSMasami Hiramatsu 3217b9b816fSMasami Hiramatsu 3227b9b816fSMasami HiramatsuFunctions and structures 3237b9b816fSMasami Hiramatsu======================== 3247b9b816fSMasami Hiramatsu 3257b9b816fSMasami Hiramatsu.. kernel-doc:: include/linux/bootconfig.h 3267b9b816fSMasami Hiramatsu.. kernel-doc:: lib/bootconfig.c 3277b9b816fSMasami Hiramatsu 328