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).

foo.bar.baz = value1foo.bar.qux.quux = value2

foo.bar {   baz = value1   qux.quux = value2}

foo.bar { baz = value1; qux.quux = value2 }

foo = bar, bazfoo = qux  # !ERROR! we can not re-define same key

foo = bar, bazfoo := qux

foo = bar, bazfoo += qux

foo = value1foo.bar = value2 # !ERROR! subkey "bar" and value "value1" can NOT co-existfoo.bar := value2 # !ERROR! even with the override operator, this is NOT allowed.

# comment linefoo = value # value is set to foo.bar = 1, # 1st element      2, # 2nd element      3  # 3rd element

foo = valuebar = 1, 2, 3

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¶

Since the boot configuration file is loaded with initrd, it will be addedto the end of the initrd (initramfs) image file with size, checksum and12-byte magic word as below.

[initrd][bootconfig][size(u32)][checksum(u32)][#BOOTCONFIGn]

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.

To do this operation, Linux kernel provides “bootconfig” 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.

Config File Limitation¶

Currently the maximum config size 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.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¶

boolxbc_node_is_value(struct xbc_node * node)¶

Test the node is a value node

Parameters

structxbc_node*node

An XBC node.

Description

Test thenode is a value node and return true if a value node, false if not.

boolxbc_node_is_key(struct xbc_node * node)¶

Test the node is a key node

Parameters

structxbc_node*node

An XBC node.

Description

Test thenode is a key node and return true if a key node, false if not.

boolxbc_node_is_array(struct xbc_node * node)¶

Test the node is an arraied value node

Parameters

structxbc_node*node

An XBC node.

Description

Test thenode is an arraied value node.

boolxbc_node_is_leaf(struct xbc_node * node)¶

Test the node is a leaf key node

Parameters

structxbc_node*node

An 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.

const char *xbc_find_value(const char * key, struct xbc_node ** vnode)¶

Find a value which matches the key

Parameters

constchar*key

Search key

structxbc_node**vnode

A 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.

struct xbc_node *xbc_find_node(const char * key)¶

Find a node which matches the key

Parameters

constchar*key

Search key

Description

Search a (key) node whose key matcheskey from whole of XBC tree andreturn the node if found. If not found, returns NULL.

xbc_array_for_each_value(anode,value)¶

Iterate value nodes on an array

Parameters

anode

An XBC arraied value node

value

A 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(parent,child)¶

Iterate child nodes

Parameters

parent

An XBC node.

child

Iterated XBC node.

Description

Iterate child nodes ofparent. Each child nodes are stored tochild.

xbc_node_for_each_array_value(node,key,anode,value)¶

Iterate array entries of geven key

Parameters

node

An XBC node.

key

A key string searched undernode

anode

Iterated XBC node of array entry.

value

Iterated value of array entry.

Description

Iterate array entries of givenkey undernode. Each array entry nodeis stroed 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. Hoever, 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(node,knode,value)¶

Iterate key-value pairs under a node

Parameters

node

An XBC node.

knode

Iterated key node

value

Iterated value string

Description

Iterate key-value pairs undernode. Each key node and value string arestored inknode andvalue respectively.

xbc_for_each_key_value(knode,value)¶

Iterate key-value pairs

Parameters

knode

Iterated key node

value

Iterated 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(struct xbc_node * node, char * buf, size_t size)¶

Compose full key string of the XBC node

Parameters

structxbc_node*node

An XBC node.

char*buf

A buffer to store the key.

size_tsize

The 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.

struct xbc_node *xbc_root_node(void)¶

Get the root node of extended boot config

Parameters

void

no arguments

Description

Return the address of root node of extended boot config. If theextended boot config is not initiized, return NULL.

intxbc_node_index(struct xbc_node * node)¶

Get the index of XBC node

Parameters

structxbc_node*node

A target node of getting index.

Description

Return the index number ofnode in XBC node list.

struct xbc_node *xbc_node_get_parent(struct xbc_node * node)¶

Get the parent XBC node

Parameters

structxbc_node*node

An XBC node.

Description

Return the parent node ofnode. If the node is top node of the tree,return NULL.

struct xbc_node *xbc_node_get_child(struct xbc_node * node)¶

Get the child XBC node

Parameters

structxbc_node*node

An XBC node.

Description

Return the first child node ofnode. If the node has no child, returnNULL.

struct xbc_node *xbc_node_get_next(struct xbc_node * node)¶

Get the next sibling XBC node

Parameters

structxbc_node*node

An 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.)

const char *xbc_node_get_data(struct xbc_node * node)¶

Get the data of XBC node

Parameters

structxbc_node*node

An XBC node.

Description

Return the data (which is always a null terminated string) ofnode.If the node has invalid data, warn and return NULL.

struct xbc_node *xbc_node_find_child(struct xbc_node * parent, const char * key)¶

Find a child node which matches given key

Parameters

structxbc_node*parent

An XBC node.

constchar*key

A key string.

Description

Search a 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.

const char *xbc_node_find_value(struct xbc_node * parent, const char * key, struct xbc_node ** vnode)¶

Find a value node which matches given key

Parameters

structxbc_node*parent

An XBC node.

constchar*key

A key string.

structxbc_node**vnode

A 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(struct xbc_node * root, struct xbc_node * node, char * buf, size_t size)¶

Compose partial key string of the XBC node

Parameters

structxbc_node*root

Root XBC node

structxbc_node*node

Target XBC node.

char*buf

A buffer to store the key.

size_tsize

The 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.

struct xbc_node *xbc_node_find_next_leaf(struct xbc_node * root, struct xbc_node * node)¶

Find the next leaf node under given node

Parameters

structxbc_node*root

An XBC root node

structxbc_node*node

An 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.

const char *xbc_node_find_next_key_value(struct xbc_node * root, struct xbc_node ** leaf)¶

Find the next key-value pair nodes

Parameters

structxbc_node*root

An XBC root node

structxbc_node**leaf

A 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.

voidxbc_destroy_all(void)¶

Clean up all parsed bootconfig

Parameters

void

no arguments

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(char * buf, const char ** emsg, int * epos)¶

Parse given XBC file and build XBC internal tree

Parameters

char*buf

boot config text

constchar**emsg

A pointer of const char * to store the error message

int*epos

A pointer of int to store the error position

Description

This parses the boot config text inbuf.buf must be anull terminated string and smaller than 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.

voidxbc_debug_dump(void)¶

Dump current XBC node list

Parameters

void

no arguments

Description

Dump the current XBC node list on printk buffer for debug.