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 147b9b816fSMasami HiramatsuThe boot configuration is expanding current kernel cmdline to support 157b9b816fSMasami Hiramatsuadditional key-value data when boot the kernel in an efficient way. 167b9b816fSMasami HiramatsuThis allows adoministrators 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 227b9b816fSMasami 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 HiramatsuKEY[.WORD[...]] = VALUE[, VALUE2[...]][;] 277b9b816fSMasami Hiramatsu 287b9b816fSMasami HiramatsuEach key word must contain only alphabets, numbers, dash (``-``) or underscore 297b9b816fSMasami Hiramatsu(``_``). And each value only contains printable characters or spaces except 307b9b816fSMasami Hiramatsufor delimiters such as semi-colon (``;``), new-line (``\n``), comma (``,``), 317b9b816fSMasami Hiramatsuhash (``#``) and closing brace (``}``). 327b9b816fSMasami Hiramatsu 337b9b816fSMasami HiramatsuIf you want to use those delimiters in a value, you can use either double- 347b9b816fSMasami Hiramatsuquotes (``"VALUE"``) or single-quotes (``'VALUE'``) to quote it. Note that 357b9b816fSMasami Hiramatsuyou can not escape these quotes. 367b9b816fSMasami Hiramatsu 377b9b816fSMasami HiramatsuThere can be a key which doesn't have value or has an empty value. Those keys 387b9b816fSMasami Hiramatsuare used for checking the key exists or not (like a boolean). 397b9b816fSMasami Hiramatsu 407b9b816fSMasami HiramatsuKey-Value Syntax 417b9b816fSMasami Hiramatsu---------------- 427b9b816fSMasami Hiramatsu 437b9b816fSMasami HiramatsuThe boot config file syntax allows user to merge partially same word keys 447b9b816fSMasami Hiramatsuby brace. For example:: 457b9b816fSMasami Hiramatsu 467b9b816fSMasami Hiramatsu foo.bar.baz = value1 477b9b816fSMasami Hiramatsu foo.bar.qux.quux = value2 487b9b816fSMasami Hiramatsu 497b9b816fSMasami HiramatsuThese can be written also in:: 507b9b816fSMasami Hiramatsu 517b9b816fSMasami Hiramatsu foo.bar { 527b9b816fSMasami Hiramatsu baz = value1 537b9b816fSMasami Hiramatsu qux.quux = value2 547b9b816fSMasami Hiramatsu } 557b9b816fSMasami Hiramatsu 567b9b816fSMasami HiramatsuOr more shorter, written as following:: 577b9b816fSMasami Hiramatsu 587b9b816fSMasami Hiramatsu foo.bar { baz = value1; qux.quux = value2 } 597b9b816fSMasami Hiramatsu 607b9b816fSMasami HiramatsuIn both styles, same key words are automatically merged when parsing it 617b9b816fSMasami Hiramatsuat boot time. So you can append similar trees or key-values. 627b9b816fSMasami Hiramatsu 637b9b816fSMasami HiramatsuComments 647b9b816fSMasami Hiramatsu-------- 657b9b816fSMasami Hiramatsu 667b9b816fSMasami HiramatsuThe config syntax accepts shell-script style comments. The comments start 677b9b816fSMasami Hiramatsuwith hash ("#") until newline ("\n") will be ignored. 687b9b816fSMasami Hiramatsu 697b9b816fSMasami Hiramatsu:: 707b9b816fSMasami Hiramatsu 717b9b816fSMasami Hiramatsu # comment line 727b9b816fSMasami Hiramatsu foo = value # value is set to foo. 737b9b816fSMasami Hiramatsu bar = 1, # 1st element 747b9b816fSMasami Hiramatsu 2, # 2nd element 757b9b816fSMasami Hiramatsu 3 # 3rd element 767b9b816fSMasami Hiramatsu 777b9b816fSMasami HiramatsuThis is parsed as below:: 787b9b816fSMasami Hiramatsu 797b9b816fSMasami Hiramatsu foo = value 807b9b816fSMasami Hiramatsu bar = 1, 2, 3 817b9b816fSMasami Hiramatsu 827b9b816fSMasami HiramatsuNote that you can not put a comment between value and delimiter(``,`` or 837b9b816fSMasami Hiramatsu``;``). This means following config has a syntax error :: 847b9b816fSMasami Hiramatsu 857b9b816fSMasami Hiramatsu key = 1 # comment 867b9b816fSMasami Hiramatsu ,2 877b9b816fSMasami Hiramatsu 887b9b816fSMasami Hiramatsu 897b9b816fSMasami Hiramatsu/proc/bootconfig 907b9b816fSMasami Hiramatsu================ 917b9b816fSMasami Hiramatsu 927b9b816fSMasami Hiramatsu/proc/bootconfig is a user-space interface of the boot config. 937b9b816fSMasami HiramatsuUnlike /proc/cmdline, this file shows the key-value style list. 947b9b816fSMasami HiramatsuEach key-value pair is shown in each line with following style:: 957b9b816fSMasami Hiramatsu 967b9b816fSMasami Hiramatsu KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] 977b9b816fSMasami Hiramatsu 987b9b816fSMasami Hiramatsu 997b9b816fSMasami HiramatsuBoot Kernel With a Boot Config 1007b9b816fSMasami Hiramatsu============================== 1017b9b816fSMasami Hiramatsu 1027b9b816fSMasami HiramatsuSince the boot configuration file is loaded with initrd, it will be added 1037b9b816fSMasami Hiramatsuto the end of the initrd (initramfs) image file. The Linux kernel decodes 1047b9b816fSMasami Hiramatsuthe last part of the initrd image in memory to get the boot configuration 1057b9b816fSMasami Hiramatsudata. 1067b9b816fSMasami HiramatsuBecause of this "piggyback" method, there is no need to change or 1077b9b816fSMasami Hiramatsuupdate the boot loader and the kernel image itself. 1087b9b816fSMasami Hiramatsu 1097b9b816fSMasami HiramatsuTo do this operation, Linux kernel provides "bootconfig" command under 1107b9b816fSMasami Hiramatsutools/bootconfig, which allows admin to apply or delete the config file 1117b9b816fSMasami Hiramatsuto/from initrd image. You can build it by follwoing command:: 1127b9b816fSMasami Hiramatsu 1137b9b816fSMasami Hiramatsu # make -C tools/bootconfig 1147b9b816fSMasami Hiramatsu 1157b9b816fSMasami HiramatsuTo add your boot config file to initrd image, run bootconfig as below 1167b9b816fSMasami Hiramatsu(Old data is removed automatically if exists):: 1177b9b816fSMasami Hiramatsu 1187b9b816fSMasami Hiramatsu # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z 1197b9b816fSMasami Hiramatsu 1207b9b816fSMasami HiramatsuTo remove the config from the image, you can use -d option as below:: 1217b9b816fSMasami Hiramatsu 1227b9b816fSMasami Hiramatsu # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z 1237b9b816fSMasami Hiramatsu 1247b9b816fSMasami Hiramatsu 1257b9b816fSMasami HiramatsuC onfig File Limitation 1267b9b816fSMasami Hiramatsu====================== 1277b9b816fSMasami Hiramatsu 1287b9b816fSMasami HiramatsuCurrently the maximum config size size is 32KB and the total key-words (not 1297b9b816fSMasami Hiramatsukey-value entries) must be under 1024 nodes. 1307b9b816fSMasami HiramatsuNote: this is not the number of entries but nodes, an entry must consume 1317b9b816fSMasami Hiramatsumore than 2 nodes (a key-word and a value). So theoretically, it will be 1327b9b816fSMasami Hiramatsuup to 512 key-value pairs. If keys contains 3 words in average, it can 1337b9b816fSMasami Hiramatsucontain 256 key-value pairs. In most cases, the number of config items 1347b9b816fSMasami Hiramatsuwill be under 100 entries and smaller than 8KB, so it would be enough. 1357b9b816fSMasami HiramatsuIf the node number exceeds 1024, parser returns an error even if the file 1367b9b816fSMasami Hiramatsusize is smaller than 32KB. 1377b9b816fSMasami HiramatsuAnyway, since bootconfig command verifies it when appending a boot config 1387b9b816fSMasami Hiramatsuto initrd image, user can notice it before boot. 1397b9b816fSMasami Hiramatsu 1407b9b816fSMasami Hiramatsu 1417b9b816fSMasami HiramatsuBootconfig APIs 1427b9b816fSMasami Hiramatsu=============== 1437b9b816fSMasami Hiramatsu 1447b9b816fSMasami HiramatsuUser can query or loop on key-value pairs, also it is possible to find 1457b9b816fSMasami Hiramatsua root (prefix) key node and find key-values under that node. 1467b9b816fSMasami Hiramatsu 1477b9b816fSMasami HiramatsuIf you have a key string, you can query the value directly with the key 1487b9b816fSMasami Hiramatsuusing xbc_find_value(). If you want to know what keys exist in the SKC 1497b9b816fSMasami Hiramatsutree, you can use xbc_for_each_key_value() to iterate key-value pairs. 1507b9b816fSMasami HiramatsuNote that you need to use xbc_array_for_each_value() for accessing 1517b9b816fSMasami Hiramatsueach arraies value, e.g.:: 1527b9b816fSMasami Hiramatsu 1537b9b816fSMasami Hiramatsu vnode = NULL; 1547b9b816fSMasami Hiramatsu xbc_find_value("key.word", &vnode); 1557b9b816fSMasami Hiramatsu if (vnode && xbc_node_is_array(vnode)) 1567b9b816fSMasami Hiramatsu xbc_array_for_each_value(vnode, value) { 1577b9b816fSMasami Hiramatsu printk("%s ", value); 1587b9b816fSMasami Hiramatsu } 1597b9b816fSMasami Hiramatsu 1607b9b816fSMasami HiramatsuIf you want to focus on keys which has a prefix string, you can use 1617b9b816fSMasami Hiramatsuxbc_find_node() to find a node which prefix key words, and iterate 1627b9b816fSMasami Hiramatsukeys under the prefix node with xbc_node_for_each_key_value(). 1637b9b816fSMasami Hiramatsu 1647b9b816fSMasami HiramatsuBut the most typical usage is to get the named value under prefix 1657b9b816fSMasami Hiramatsuor get the named array under prefix as below:: 1667b9b816fSMasami Hiramatsu 1677b9b816fSMasami Hiramatsu root = xbc_find_node("key.prefix"); 1687b9b816fSMasami Hiramatsu value = xbc_node_find_value(root, "option", &vnode); 1697b9b816fSMasami Hiramatsu ... 1707b9b816fSMasami Hiramatsu xbc_node_for_each_array_value(root, "array-option", value, anode) { 1717b9b816fSMasami Hiramatsu ... 1727b9b816fSMasami Hiramatsu } 1737b9b816fSMasami Hiramatsu 1747b9b816fSMasami HiramatsuThis accesses a value of "key.prefix.option" and an array of 1757b9b816fSMasami Hiramatsu"key.prefix.array-option". 1767b9b816fSMasami Hiramatsu 1777b9b816fSMasami HiramatsuLocking is not needed, since after initialized, the config becomes readonly. 1787b9b816fSMasami HiramatsuAll data and keys must be copied if you need to modify it. 1797b9b816fSMasami Hiramatsu 1807b9b816fSMasami Hiramatsu 1817b9b816fSMasami HiramatsuFunctions and structures 1827b9b816fSMasami Hiramatsu======================== 1837b9b816fSMasami Hiramatsu 1847b9b816fSMasami Hiramatsu.. kernel-doc:: include/linux/bootconfig.h 1857b9b816fSMasami Hiramatsu.. kernel-doc:: lib/bootconfig.c 1867b9b816fSMasami Hiramatsu 187