Commit | Line | Data |
---|---|---|
7b9b816f MH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
47781947 MH |
3 | .. _bootconfig: |
4 | ||
7b9b816f MH |
5 | ================== |
6 | Boot Configuration | |
7 | ================== | |
8 | ||
9 | :Author: Masami Hiramatsu <mhiramat@kernel.org> | |
10 | ||
11 | Overview | |
12 | ======== | |
13 | ||
a4798eb4 MH |
14 | The boot configuration expands the current kernel command line to support |
15 | additional key-value data when booting the kernel in an efficient way. | |
16 | This allows administrators to pass a structured-Key config file. | |
7b9b816f MH |
17 | |
18 | Config File Syntax | |
19 | ================== | |
20 | ||
21 | The boot config syntax is a simple structured key-value. Each key consists | |
a4798eb4 | 22 | of dot-connected-words, and key and value are connected by ``=``. The value |
7b9b816f MH |
23 | has to be terminated by semi-colon (``;``) or newline (``\n``). |
24 | For array value, array entries are separated by comma (``,``). :: | |
25 | ||
26 | KEY[.WORD[...]] = VALUE[, VALUE2[...]][;] | |
27 | ||
a4798eb4 MH |
28 | Unlike the kernel command line syntax, spaces are OK around the comma and ``=``. |
29 | ||
7b9b816f MH |
30 | Each key word must contain only alphabets, numbers, dash (``-``) or underscore |
31 | (``_``). And each value only contains printable characters or spaces except | |
32 | for delimiters such as semi-colon (``;``), new-line (``\n``), comma (``,``), | |
33 | hash (``#``) and closing brace (``}``). | |
34 | ||
35 | If you want to use those delimiters in a value, you can use either double- | |
36 | quotes (``"VALUE"``) or single-quotes (``'VALUE'``) to quote it. Note that | |
37 | you can not escape these quotes. | |
38 | ||
39 | There can be a key which doesn't have value or has an empty value. Those keys | |
a4798eb4 | 40 | are used for checking if the key exists or not (like a boolean). |
7b9b816f MH |
41 | |
42 | Key-Value Syntax | |
43 | ---------------- | |
44 | ||
45 | The boot config file syntax allows user to merge partially same word keys | |
46 | by brace. For example:: | |
47 | ||
48 | foo.bar.baz = value1 | |
49 | foo.bar.qux.quux = value2 | |
50 | ||
51 | These can be written also in:: | |
52 | ||
53 | foo.bar { | |
54 | baz = value1 | |
55 | qux.quux = value2 | |
56 | } | |
57 | ||
58 | Or more shorter, written as following:: | |
59 | ||
60 | foo.bar { baz = value1; qux.quux = value2 } | |
61 | ||
62 | In both styles, same key words are automatically merged when parsing it | |
63 | at boot time. So you can append similar trees or key-values. | |
64 | ||
a24d286f MH |
65 | Note that a sub-key and a value can not co-exist under a parent key. |
66 | For example, following config is NOT allowed.:: | |
67 | ||
68 | foo = value1 | |
69 | foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-exist | |
70 | ||
71 | ||
7b9b816f MH |
72 | Comments |
73 | -------- | |
74 | ||
a4798eb4 | 75 | The config syntax accepts shell-script style comments. The comments starting |
7b9b816f MH |
76 | with hash ("#") until newline ("\n") will be ignored. |
77 | ||
78 | :: | |
79 | ||
80 | # comment line | |
81 | foo = value # value is set to foo. | |
82 | bar = 1, # 1st element | |
83 | 2, # 2nd element | |
84 | 3 # 3rd element | |
85 | ||
86 | This is parsed as below:: | |
87 | ||
88 | foo = value | |
89 | bar = 1, 2, 3 | |
90 | ||
91 | Note that you can not put a comment between value and delimiter(``,`` or | |
92 | ``;``). This means following config has a syntax error :: | |
93 | ||
94 | key = 1 # comment | |
95 | ,2 | |
96 | ||
97 | ||
98 | /proc/bootconfig | |
99 | ================ | |
100 | ||
101 | /proc/bootconfig is a user-space interface of the boot config. | |
102 | Unlike /proc/cmdline, this file shows the key-value style list. | |
103 | Each key-value pair is shown in each line with following style:: | |
104 | ||
105 | KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...] | |
106 | ||
107 | ||
108 | Boot Kernel With a Boot Config | |
109 | ============================== | |
110 | ||
111 | Since the boot configuration file is loaded with initrd, it will be added | |
85c46b78 MH |
112 | to the end of the initrd (initramfs) image file with size, checksum and |
113 | 12-byte magic word as below. | |
114 | ||
115 | [initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIG\n] | |
116 | ||
117 | The Linux kernel decodes the last part of the initrd image in memory to | |
118 | get the boot configuration data. | |
7b9b816f MH |
119 | Because of this "piggyback" method, there is no need to change or |
120 | update the boot loader and the kernel image itself. | |
121 | ||
122 | To do this operation, Linux kernel provides "bootconfig" command under | |
123 | tools/bootconfig, which allows admin to apply or delete the config file | |
a4798eb4 | 124 | to/from initrd image. You can build it by the following command:: |
7b9b816f MH |
125 | |
126 | # make -C tools/bootconfig | |
127 | ||
128 | To add your boot config file to initrd image, run bootconfig as below | |
129 | (Old data is removed automatically if exists):: | |
130 | ||
131 | # tools/bootconfig/bootconfig -a your-config /boot/initrd.img-X.Y.Z | |
132 | ||
133 | To remove the config from the image, you can use -d option as below:: | |
134 | ||
135 | # tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z | |
136 | ||
7495e092 SRV |
137 | Then add "bootconfig" on the normal kernel command line to tell the |
138 | kernel to look for the bootconfig at the end of the initrd file. | |
7b9b816f | 139 | |
a4798eb4 | 140 | Config File Limitation |
7b9b816f MH |
141 | ====================== |
142 | ||
143 | Currently the maximum config size size is 32KB and the total key-words (not | |
144 | key-value entries) must be under 1024 nodes. | |
145 | Note: this is not the number of entries but nodes, an entry must consume | |
146 | more than 2 nodes (a key-word and a value). So theoretically, it will be | |
147 | up to 512 key-value pairs. If keys contains 3 words in average, it can | |
148 | contain 256 key-value pairs. In most cases, the number of config items | |
149 | will be under 100 entries and smaller than 8KB, so it would be enough. | |
150 | If the node number exceeds 1024, parser returns an error even if the file | |
151 | size is smaller than 32KB. | |
152 | Anyway, since bootconfig command verifies it when appending a boot config | |
153 | to initrd image, user can notice it before boot. | |
154 | ||
155 | ||
156 | Bootconfig APIs | |
157 | =============== | |
158 | ||
159 | User can query or loop on key-value pairs, also it is possible to find | |
160 | a root (prefix) key node and find key-values under that node. | |
161 | ||
162 | If you have a key string, you can query the value directly with the key | |
a4798eb4 MH |
163 | using xbc_find_value(). If you want to know what keys exist in the boot |
164 | config, you can use xbc_for_each_key_value() to iterate key-value pairs. | |
7b9b816f | 165 | Note that you need to use xbc_array_for_each_value() for accessing |
a4798eb4 | 166 | each array's value, e.g.:: |
7b9b816f MH |
167 | |
168 | vnode = NULL; | |
169 | xbc_find_value("key.word", &vnode); | |
170 | if (vnode && xbc_node_is_array(vnode)) | |
171 | xbc_array_for_each_value(vnode, value) { | |
172 | printk("%s ", value); | |
173 | } | |
174 | ||
a4798eb4 MH |
175 | If you want to focus on keys which have a prefix string, you can use |
176 | xbc_find_node() to find a node by the prefix string, and iterate | |
7b9b816f MH |
177 | keys under the prefix node with xbc_node_for_each_key_value(). |
178 | ||
179 | But the most typical usage is to get the named value under prefix | |
180 | or get the named array under prefix as below:: | |
181 | ||
182 | root = xbc_find_node("key.prefix"); | |
183 | value = xbc_node_find_value(root, "option", &vnode); | |
184 | ... | |
185 | xbc_node_for_each_array_value(root, "array-option", value, anode) { | |
186 | ... | |
187 | } | |
188 | ||
189 | This accesses a value of "key.prefix.option" and an array of | |
190 | "key.prefix.array-option". | |
191 | ||
a4798eb4 MH |
192 | Locking is not needed, since after initialization, the config becomes |
193 | read-only. All data and keys must be copied if you need to modify it. | |
7b9b816f MH |
194 | |
195 | ||
196 | Functions and structures | |
197 | ======================== | |
198 | ||
199 | .. kernel-doc:: include/linux/bootconfig.h | |
200 | .. kernel-doc:: lib/bootconfig.c | |
201 |