Boot Configuration¶
- Author:
Masami Hiramatsu <mhiramat@kernel.org>
Overview¶
The boot configuration expands the current kernel command line to supportadditional key-value data when booting the kernel in an efficient way.This allows administrators to pass a structured-Key config file.
Config File Syntax¶
The boot config syntax is a simple structured key-value. Each key consistsof dot-connected-words, and key and value are connected by=. The valuehas to be terminated by semi-colon (;) or newline (\n).For array value, array entries are separated by comma (,).
KEY[.WORD[...]] = VALUE[, VALUE2[...]][;]
Unlike the kernel command line syntax, spaces are OK around the comma and=.
Each key word must contain only alphabets, numbers, dash (-) or underscore(_). And each value only contains printable characters or spaces exceptfor delimiters such as semi-colon (;), new-line (\n), comma (,),hash (#) and closing brace (}).
If you want to use those delimiters in a value, you can use either double-quotes ("VALUE") or single-quotes ('VALUE') to quote it. Note thatyou can not escape these quotes.
There can be a key which doesn’t have value or has an empty value. Those keysare used for checking if the key exists or not (like a boolean).
Key-Value Syntax¶
The boot config file syntax allows user to merge partially same word keysby brace. For example:
foo.bar.baz = value1foo.bar.qux.quux = value2
These can be written also in:
foo.bar { baz = value1 qux.quux = value2}Or more shorter, written as following:
foo.bar { baz = value1; qux.quux = value2 }In both styles, same key words are automatically merged when parsing itat boot time. So you can append similar trees or key-values.
Same-key Values¶
It is prohibited that two or more values or arrays share a same-key.For example,:
foo = bar, bazfoo = qux # !ERROR! we can not re-define same key
If you want to update the value, you must use the override operator:= explicitly. For example:
foo = bar, bazfoo := qux
then, thequx is assigned tofoo key. This is useful foroverriding the default value by adding (partial) custom bootconfigswithout parsing the default bootconfig.
If you want to append the value to existing key as an array member,you can use+= operator. For example:
foo = bar, bazfoo += qux
In this case, the keyfoo hasbar,baz andqux.
Moreover, sub-keys and a value can coexist under a parent key.For example, following config is allowed.:
foo = value1foo.bar = value2foo := value3 # This will update foo's value.
Note, since there is no syntax to put a raw value directly under astructured key, you have to define it outside of the brace. For example:
foo { bar = value1 bar { baz = value2 qux = value3 }}Also, the order of the value node under a key is fixed. If thereare a value and subkeys, the value is always the first child nodeof the key. Thus if user specifies subkeys first, e.g.:
foo.bar = value1foo = value2
In the program (and /proc/bootconfig), it will be shown as below:
foo = value2foo.bar = value1
Comments¶
The config syntax accepts shell-script style comments. The comments startingwith hash (“#”) until newline (”n”) will be ignored.
# comment linefoo = value # value is set to foo.bar = 1, # 1st element 2, # 2nd element 3 # 3rd element
This is parsed as below:
foo = valuebar = 1, 2, 3
Note that you can not put a comment between value and delimiter(, or;). This means following config has a syntax error
key = 1 # comment ,2
/proc/bootconfig¶
/proc/bootconfig is a user-space interface of the boot config.Unlike /proc/cmdline, this file shows the key-value style list.Each key-value pair is shown in each line with following style:
KEY[.WORDS...] = "[VALUE]"[,"VALUE2"...]
Boot Kernel With a Boot Config¶
There are two options to boot the kernel with bootconfig: attaching thebootconfig to the initrd image or embedding it in the kernel itself.
Attaching a Boot Config to Initrd¶
Since the boot configuration file is loaded with initrd by default,it will be added to the end of the initrd (initramfs) image file withpadding, size, checksum and 12-byte magic word as below.
[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIGn]
The size and checksum fields are unsigned 32bit little endian value.
When the boot configuration is added to the initrd image, the totalfile size is aligned to 4 bytes. To fill the gap, null characters(\0) will be added. Thus thesize is the length of the bootconfigfile + padding bytes.
The Linux kernel decodes the last part of the initrd image in memory toget the boot configuration data.Because of this “piggyback” method, there is no need to change orupdate the boot loader and the kernel image itself as long as the bootloader passes the correct initrd file size. If by any chance, the bootloader passes a longer size, the kernel fails to find the bootconfig data.
To do this operation, Linux kernel providesbootconfig command undertools/bootconfig, which allows admin to apply or delete the config fileto/from initrd image. You can build it by the following command:
# make -C tools/bootconfig
To add your boot config 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
To remove the config from the image, you can use -d option as below:
# tools/bootconfig/bootconfig -d /boot/initrd.img-X.Y.Z
Then add “bootconfig” on the normal kernel command line to tell thekernel to look for the bootconfig at the end of the initrd file.Alternatively, build your kernel with theCONFIG_BOOT_CONFIG_FORCEKconfig option selected.
Embedding a Boot Config into Kernel¶
If you can not use initrd, you can also embed the bootconfig file in thekernel by Kconfig options. In this case, you need to recompile the kernelwith the following configs:
CONFIG_BOOT_CONFIG_EMBED=yCONFIG_BOOT_CONFIG_EMBED_FILE="/PATH/TO/BOOTCONFIG/FILE"
CONFIG_BOOT_CONFIG_EMBED_FILE requires an absolute path or a relativepath to the bootconfig file from source tree or object tree.The kernel will embed it as the default bootconfig.
Just as when attaching the bootconfig to the initrd, you needbootconfigoption on the kernel command line to enable the embedded bootconfig, or,alternatively, build your kernel with theCONFIG_BOOT_CONFIG_FORCEKconfig option selected.
Note that even if you set this option, you can override the embeddedbootconfig by another bootconfig which attached to the initrd.
Kernel parameters via Boot Config¶
In addition to the kernel command line, the boot config can be used forpassing the kernel parameters. All the key-value pairs underkernelkey will be passed to kernel cmdline directly. Moreover, the key-valuepairs underinit will be passed to init process via the cmdline.The parameters are concatenated with user-given kernel cmdline stringas the following order, so that the command line parameter can overridebootconfig parameters (this depends on how the subsystem handles parametersbut in general, earlier parameter will be overwritten by later one.):
[bootconfig params][cmdline params] -- [bootconfig init params][cmdline init params]
Here is an example of the bootconfig file for kernel/init parameters.:
kernel { root = 01234567-89ab-cdef-0123-456789abcd}init { splash}This will be copied into the kernel cmdline string as the following:
root="01234567-89ab-cdef-0123-456789abcd" -- splash
If user gives some other command line like,:
ro bootconfig -- quiet
The final kernel cmdline will be the following:
root="01234567-89ab-cdef-0123-456789abcd" ro bootconfig -- splash quiet
Config File Limitation¶
Currently the maximum config size is 32KB and the total key-words (notkey-value entries) must be under 1024 nodes.Note: this is not the number of entries but nodes, an entry must consumemore than 2 nodes (a key-word and a value). So theoretically, it will beup to 512 key-value pairs. If keys contains 3 words in average, it cancontain 256 key-value pairs. In most cases, the number of config itemswill be under 100 entries and smaller than 8KB, so it would be enough.If the node number exceeds 1024, parser returns an error even if the filesize is smaller than 32KB. (Note that this maximum size is not includingthe padding null characters.)Anyway, since bootconfig command verifies it when appending a boot configto initrd image, user can notice it before boot.
Bootconfig APIs¶
User can query or loop on key-value pairs, also it is possible to finda root (prefix) key node and find key-values under that node.
If you have a key string, you can query the value directly with the keyusingxbc_find_value(). If you want to know what keys exist in the bootconfig, you can usexbc_for_each_key_value() to iterate key-value pairs.Note that you need to usexbc_array_for_each_value() for accessingeach array’s value, e.g.:
vnode = NULL;xbc_find_value("key.word", &vnode);if (vnode && xbc_node_is_array(vnode)) xbc_array_for_each_value(vnode, value) { printk("%s ", value); }If you want to focus on keys which have a prefix string, you can usexbc_find_node() to find a node by the prefix string, and iteratekeys under the prefix node withxbc_node_for_each_key_value().
But the most typical usage is to get the named value under prefixor get the named array under prefix as below:
root = xbc_find_node("key.prefix");value = xbc_node_find_value(root, "option", &vnode);...xbc_node_for_each_array_value(root, "array-option", value, anode) { ...}This accesses a value of “key.prefix.option” and an array of“key.prefix.array-option”.
Locking is not needed, since after initialization, the config becomesread-only. All data and keys must be copied if you need to modify it.
Functions and structures¶
- uint32_txbc_calc_checksum(void*data,uint32_tsize)¶
Calculate checksum of bootconfig
Parameters
void*dataBootconfig data.
uint32_tsizeThe size of the bootconfig data.
Description
Calculate the checksum value of the bootconfig data.The checksum will be used with the BOOTCONFIG_MAGIC and the size forembedding the bootconfig in the initrd image.
- boolxbc_node_is_value(structxbc_node*node)¶
Test the node is a value node
Parameters
structxbc_node*nodeAn XBC node.
Description
Test thenode is a value node and return true if a value node, false if not.
- boolxbc_node_is_key(structxbc_node*node)¶
Test the node is a key node
Parameters
structxbc_node*nodeAn XBC node.
Description
Test thenode is a key node and return true if a key node, false if not.
- boolxbc_node_is_array(structxbc_node*node)¶
Test the node is an arraied value node
Parameters
structxbc_node*nodeAn XBC node.
Description
Test thenode is an arraied value node.
- boolxbc_node_is_leaf(structxbc_node*node)¶
Test the node is a leaf key node
Parameters
structxbc_node*nodeAn XBC node.
Description
Test thenode is a leaf key node which is a key node and has a value nodeor no child. Returns true if it is a leaf node, or false if not.Note that the leaf node can have subkey nodes in addition to thevalue node.
- constchar*xbc_find_value(constchar*key,structxbc_node**vnode)¶
Find a value which matches the key
Parameters
constchar*keySearch key
structxbc_node**vnodeA container pointer of XBC value node.
Description
Search a value whose key matcheskey from whole of XBC tree and returnthe value if found. Found value node is stored in*vnode.Note that this can return 0-length string and store NULL in*vnode forkey-only (non-value) entry.
- structxbc_node*xbc_find_node(constchar*key)¶
Find a node which matches the key
Parameters
constchar*keySearch key
Description
Search a (key) node whose key matcheskey from whole of XBC tree andreturn the node if found. If not found, returns NULL.
- structxbc_node*xbc_node_get_subkey(structxbc_node*node)¶
Return the first subkey node if exists
Parameters
structxbc_node*nodeParent node
Description
Return the first subkey node of thenode. If thenode has no childor only value node, this will return NULL.
- xbc_array_for_each_value¶
xbc_array_for_each_value(anode,value)
Iterate value nodes on an array
Parameters
anodeAn XBC arraied value node
valueA value
Description
Iterate array value nodes and values starts fromanode. This is expected tobe used withxbc_find_value() andxbc_node_find_value(), so that user canprocess each array entry node.
- xbc_node_for_each_child¶
xbc_node_for_each_child(parent,child)
Iterate child nodes
Parameters
parentAn XBC node.
childIterated XBC node.
Description
Iterate child nodes ofparent. Each child nodes are stored tochild.Thechild can be mixture of a value node and subkey nodes.
- xbc_node_for_each_subkey¶
xbc_node_for_each_subkey(parent,child)
Iterate child subkey nodes
Parameters
parentAn XBC node.
childIterated XBC node.
Description
Iterate subkey nodes ofparent. Each child nodes are stored tochild.Thechild is only the subkey node.
- xbc_node_for_each_array_value¶
xbc_node_for_each_array_value(node,key,anode,value)
Iterate array entries of geven key
Parameters
nodeAn XBC node.
keyA key string searched undernode
anodeIterated XBC node of array entry.
valueIterated value of array entry.
Description
Iterate array entries of givenkey undernode. Each array entry nodeis stored toanode andvalue. If thenode doesn’t havekey node,it does nothing.Note that even if the found key node has only one value (not array)this executes block once. However, if the found key node has no value(key-only node), this does nothing. So don’t use this for testing thekey-value pair existence.
- xbc_node_for_each_key_value¶
xbc_node_for_each_key_value(node,knode,value)
Iterate key-value pairs under a node
Parameters
nodeAn XBC node.
knodeIterated key node
valueIterated value string
Description
Iterate key-value pairs undernode. Each key node and value string arestored inknode andvalue respectively.
- xbc_for_each_key_value¶
xbc_for_each_key_value(knode,value)
Iterate key-value pairs
Parameters
knodeIterated key node
valueIterated value string
Description
Iterate key-value pairs in whole XBC tree. Each key node and value stringare stored inknode andvalue respectively.
- intxbc_node_compose_key(structxbc_node*node,char*buf,size_tsize)¶
Compose full key string of the XBC node
Parameters
structxbc_node*nodeAn XBC node.
char*bufA buffer to store the key.
size_tsizeThe size of thebuf.
Description
Compose the full-length key of thenode intobuf. Returns the totallength of the key stored inbuf. Or returns -EINVAL ifnode is NULL,and -ERANGE if the key depth is deeper than max depth.
- intxbc_get_info(int*node_size,size_t*data_size)¶
Get the information of loaded boot config
Parameters
int*node_sizeA pointer to store the number of nodes.
size_t*data_sizeA pointer to store the size of bootconfig data.
Description
Get the number of used nodes innode_size if it is not NULL,and the size of bootconfig data indata_size if it is not NULL.Return 0 if the boot config is initialized, or return -ENODEV.
- structxbc_node*xbc_root_node(void)¶
Get the root node of extended boot config
Parameters
voidno arguments
Description
Return the address of root node of extended boot config. If theextended boot config is not initiized, return NULL.
- intxbc_node_index(structxbc_node*node)¶
Get the index of XBC node
Parameters
structxbc_node*nodeA target node of getting index.
Description
Return the index number ofnode in XBC node list.
- structxbc_node*xbc_node_get_parent(structxbc_node*node)¶
Get the parent XBC node
Parameters
structxbc_node*nodeAn XBC node.
Description
Return the parent node ofnode. If the node is top node of the tree,return NULL.
- structxbc_node*xbc_node_get_child(structxbc_node*node)¶
Get the child XBC node
Parameters
structxbc_node*nodeAn XBC node.
Description
Return the first child node ofnode. If the node has no child, returnNULL.
- structxbc_node*xbc_node_get_next(structxbc_node*node)¶
Get the next sibling XBC node
Parameters
structxbc_node*nodeAn XBC node.
Description
Return the NEXT sibling node ofnode. If the node has no next sibling,return NULL. Note that even if this returns NULL, it doesn’t meannodehas no siblings. (You also has to check whether the parent’s child nodeisnode or not.)
- constchar*xbc_node_get_data(structxbc_node*node)¶
Get the data of XBC node
Parameters
structxbc_node*nodeAn XBC node.
Description
Return the data (which is always a null terminated string) ofnode.If the node has invalid data, warn and return NULL.
- structxbc_node*xbc_node_find_subkey(structxbc_node*parent,constchar*key)¶
Find a subkey node which matches given key
Parameters
structxbc_node*parentAn XBC node.
constchar*keyA key string.
Description
Search a key node underparent which matcheskey. Thekey can containseveral words jointed with ‘.’. Ifparent is NULL, this searches thenode from whole tree. Return NULL if no node is matched.
- constchar*xbc_node_find_value(structxbc_node*parent,constchar*key,structxbc_node**vnode)¶
Find a value node which matches given key
Parameters
structxbc_node*parentAn XBC node.
constchar*keyA key string.
structxbc_node**vnodeA container pointer of found XBC node.
Description
Search a value node underparent whose (parent) key node matcheskey,store it in*vnode, and returns the value string.Thekey can contain several words jointed with ‘.’. Ifparent is NULL,this searches the node from whole tree. Return the value string if amatched key found, return NULL if no node is matched.Note that this returns 0-length string and stores NULL in*vnode if thekey has no value. And also it will return the value of the first entry ifthe value is an array.
- intxbc_node_compose_key_after(structxbc_node*root,structxbc_node*node,char*buf,size_tsize)¶
Compose partial key string of the XBC node
Parameters
structxbc_node*rootRoot XBC node
structxbc_node*nodeTarget XBC node.
char*bufA buffer to store the key.
size_tsizeThe size of thebuf.
Description
Compose the partial key of thenode intobuf, which is starting rightafterroot (root is not included.) Ifroot is NULL, this returns fullkey words ofnode.Returns the total length of the key stored inbuf. Returns -EINVALifnode is NULL orroot is not the ancestor ofnode orroot isnode,or returns -ERANGE if the key depth is deeper than max depth.This is expected to be used withxbc_find_node() to list up all (child)keys under given key.
- structxbc_node*xbc_node_find_next_leaf(structxbc_node*root,structxbc_node*node)¶
Find the next leaf node under given node
Parameters
structxbc_node*rootAn XBC root node
structxbc_node*nodeAn XBC node which starts from.
Description
Search the next leaf node (which means the terminal key node) ofnodeunderroot node (includingroot node itself).Return the next node or NULL if next leaf node is not found.
- constchar*xbc_node_find_next_key_value(structxbc_node*root,structxbc_node**leaf)¶
Find the next key-value pair nodes
Parameters
structxbc_node*rootAn XBC root node
structxbc_node**leafA container pointer of XBC node which starts from.
Description
Search the next leaf node (which means the terminal key node) of*leafunderroot node. Returns the value and update*leaf if next leaf nodeis found, or NULL if no next leaf node is found.Note that this returns 0-length string if the key has no value, orthe value of the first entry if the value is an array.
- void_xbc_exit(boolearly)¶
Clean up all parsed bootconfig
Parameters
boolearlySet true if this is called before budy system is initialized.
Description
This clears all data structures of parsed bootconfig on memory.If you need to reusexbc_init() with new boot config, you canuse this.
- intxbc_init(constchar*data,size_tsize,constchar**emsg,int*epos)¶
Parse given XBC file and build XBC internal tree
Parameters
constchar*dataThe boot config text original data
size_tsizeThe size ofdata
constchar**emsgA pointer of const char * to store the error message
int*eposA pointer of int to store the error position
Description
This parses the boot config text indata.size must be smallerthan XBC_DATA_MAX.Return the number of stored nodes (>0) if succeeded, or -errnoif there is any error.In error cases,emsg will be updated with an error message andepos will be updated with the error position which is the byte offsetofbuf. If the error is not a parser error,epos will be -1.