1 .. SPDX-License-Identifier: GPL-2.0
2
3 .. _bootconfig:
4
5 ==================
6 Boot Configuration
7 ==================
8
9 :Author: Masami Hiramatsu <mhiramat@kernel.org>
10
11 Overview
12 ========
13
14 The boot configuration expands the current ker
15 additional key-value data when booting the ker
16 This allows administrators to pass a structure
17
18 Config File Syntax
19 ==================
20
21 The boot config syntax is a simple structured
22 of dot-connected-words, and key and value are
23 has to be terminated by semi-colon (``;``) or
24 For array value, array entries are separated b
25
26 KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
27
28 Unlike the kernel command line syntax, spaces
29
30 Each key word must contain only alphabets, num
31 (``_``). And each value only contains printabl
32 for delimiters such as semi-colon (``;``), new
33 hash (``#``) and closing brace (``}``).
34
35 If you want to use those delimiters in a value
36 quotes (``"VALUE"``) or single-quotes (``'VALU
37 you can not escape these quotes.
38
39 There can be a key which doesn't have value or
40 are used for checking if the key exists or not
41
42 Key-Value Syntax
43 ----------------
44
45 The boot config file syntax allows user to mer
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 automatical
63 at boot time. So you can append similar trees
64
65 Same-key Values
66 ---------------
67
68 It is prohibited that two or more values or ar
69 For example,::
70
71 foo = bar, baz
72 foo = qux # !ERROR! we can not re-define sam
73
74 If you want to update the value, you must use
75 ``:=`` explicitly. For example::
76
77 foo = bar, baz
78 foo := qux
79
80 then, the ``qux`` is assigned to ``foo`` key.
81 overriding the default value by adding (partia
82 without parsing the default bootconfig.
83
84 If you want to append the value to existing ke
85 you can use ``+=`` operator. For example::
86
87 foo = bar, baz
88 foo += qux
89
90 In this case, the key ``foo`` has ``bar``, ``b
91
92 Moreover, sub-keys and a value can coexist und
93 For example, following config is allowed.::
94
95 foo = value1
96 foo.bar = value2
97 foo := value3 # This will update foo's value.
98
99 Note, since there is no syntax to put a raw va
100 structured key, you have to define it outside
101
102 foo {
103 bar = value1
104 bar {
105 baz = value2
106 qux = value3
107 }
108 }
109
110 Also, the order of the value node under a key
111 are a value and subkeys, the value is always t
112 of the key. Thus if user specifies subkeys fir
113
114 foo.bar = value1
115 foo = value2
116
117 In the program (and /proc/bootconfig), it will
118
119 foo = value2
120 foo.bar = value1
121
122 Comments
123 --------
124
125 The config syntax accepts shell-script style c
126 with hash ("#") until newline ("\n") will be i
127
128 ::
129
130 # comment line
131 foo = value # value is set to foo.
132 bar = 1, # 1st element
133 2, # 2nd element
134 3 # 3rd element
135
136 This is parsed as below::
137
138 foo = value
139 bar = 1, 2, 3
140
141 Note that you can not put a comment between va
142 ``;``). This means following config has a synt
143
144 key = 1 # comment
145 ,2
146
147
148 /proc/bootconfig
149 ================
150
151 /proc/bootconfig is a user-space interface of
152 Unlike /proc/cmdline, this file shows the key-
153 Each key-value pair is shown in each line with
154
155 KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...]
156
157
158 Boot Kernel With a Boot Config
159 ==============================
160
161 There are two options to boot the kernel with
162 bootconfig to the initrd image or embedding it
163
164 Attaching a Boot Config to Initrd
165 ---------------------------------
166
167 Since the boot configuration file is loaded wi
168 it will be added to the end of the initrd (ini
169 padding, size, checksum and 12-byte magic word
170
171 [initrd][bootconfig][padding][size(le32)][chec
172
173 The size and checksum fields are unsigned 32bi
174
175 When the boot configuration is added to the in
176 file size is aligned to 4 bytes. To fill the g
177 (``\0``) will be added. Thus the ``size`` is t
178 file + padding bytes.
179
180 The Linux kernel decodes the last part of the
181 get the boot configuration data.
182 Because of this "piggyback" method, there is n
183 update the boot loader and the kernel image it
184 loader passes the correct initrd file size. If
185 loader passes a longer size, the kernel fails
186
187 To do this operation, Linux kernel provides ``
188 tools/bootconfig, which allows admin to apply
189 to/from initrd image. You can build it by the
190
191 # make -C tools/bootconfig
192
193 To add your boot config file to initrd image,
194 (Old data is removed automatically if exists):
195
196 # tools/bootconfig/bootconfig -a your-config
197
198 To remove the config from the image, you can u
199
200 # tools/bootconfig/bootconfig -d /boot/initrd
201
202 Then add "bootconfig" on the normal kernel com
203 kernel to look for the bootconfig at the end o
204 Alternatively, build your kernel with the ``CO
205 Kconfig option selected.
206
207 Embedding a Boot Config into Kernel
208 -----------------------------------
209
210 If you can not use initrd, you can also embed
211 kernel by Kconfig options. In this case, you n
212 with the following configs::
213
214 CONFIG_BOOT_CONFIG_EMBED=y
215 CONFIG_BOOT_CONFIG_EMBED_FILE="/PATH/TO/BOOTC
216
217 ``CONFIG_BOOT_CONFIG_EMBED_FILE`` requires an
218 path to the bootconfig file from source tree o
219 The kernel will embed it as the default bootco
220
221 Just as when attaching the bootconfig to the i
222 option on the kernel command line to enable th
223 alternatively, build your kernel with the ``CO
224 Kconfig option selected.
225
226 Note that even if you set this option, you can
227 bootconfig by another bootconfig which attache
228
229 Kernel parameters via Boot Config
230 =================================
231
232 In addition to the kernel command line, the bo
233 passing the kernel parameters. All the key-val
234 key will be passed to kernel cmdline directly.
235 pairs under ``init`` will be passed to init pr
236 The parameters are concatenated with user-give
237 as the following order, so that the command li
238 bootconfig parameters (this depends on how the
239 but in general, earlier parameter will be over
240
241 [bootconfig params][cmdline params] -- [bootc
242
243 Here is an example of the bootconfig file for
244
245 kernel {
246 root = 01234567-89ab-cdef-0123-456789abcd
247 }
248 init {
249 splash
250 }
251
252 This will be copied into the kernel cmdline st
253
254 root="01234567-89ab-cdef-0123-456789abcd" --
255
256 If user gives some other command line like,::
257
258 ro bootconfig -- quiet
259
260 The final kernel cmdline will be the following
261
262 root="01234567-89ab-cdef-0123-456789abcd" ro
263
264
265 Config File Limitation
266 ======================
267
268 Currently the maximum config size size is 32KB
269 key-value entries) must be under 1024 nodes.
270 Note: this is not the number of entries but no
271 more than 2 nodes (a key-word and a value). So
272 up to 512 key-value pairs. If keys contains 3
273 contain 256 key-value pairs. In most cases, th
274 will be under 100 entries and smaller than 8KB
275 If the node number exceeds 1024, parser return
276 size is smaller than 32KB. (Note that this max
277 the padding null characters.)
278 Anyway, since bootconfig command verifies it w
279 to initrd image, user can notice it before boo
280
281
282 Bootconfig APIs
283 ===============
284
285 User can query or loop on key-value pairs, als
286 a root (prefix) key node and find key-values u
287
288 If you have a key string, you can query the va
289 using xbc_find_value(). If you want to know wh
290 config, you can use xbc_for_each_key_value() t
291 Note that you need to use xbc_array_for_each_v
292 each array's value, e.g.::
293
294 vnode = NULL;
295 xbc_find_value("key.word", &vnode);
296 if (vnode && xbc_node_is_array(vnode))
297 xbc_array_for_each_value(vnode, value) {
298 printk("%s ", value);
299 }
300
301 If you want to focus on keys which have a pref
302 xbc_find_node() to find a node by the prefix s
303 keys under the prefix node with xbc_node_for_e
304
305 But the most typical usage is to get the named
306 or get the named array under prefix as below::
307
308 root = xbc_find_node("key.prefix");
309 value = xbc_node_find_value(root, "option", &
310 ...
311 xbc_node_for_each_array_value(root, "array-op
312 ...
313 }
314
315 This accesses a value of "key.prefix.option" a
316 "key.prefix.array-option".
317
318 Locking is not needed, since after initializat
319 read-only. All data and keys must be copied if
320
321
322 Functions and structures
323 ========================
324
325 .. kernel-doc:: include/linux/bootconfig.h
326 .. kernel-doc:: lib/bootconfig.c
327
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.