Boot Configuration

개요와 기본 config syntax

이 GPL-2.0 문서의 저자는 Masami Hiramatsu `<mhiramat@kernel.org>`입니다. Boot configuration은 kernel boot 때 추가 key-value data를 효율적으로 전달할 수 있도록 기존 kernel command line을 확장하며, administrator가 structured-key config file을 넘길 수 있게 합니다.

Boot config는 단순한 structured key-value syntax를 사용합니다. Key는 dot으로 연결한 word로 이루어지고 key와 value는 `=`로 연결합니다. Value는 semicolon(`;`) 또는 newline(`\n`)으로 끝내며 array entry는 comma(`,`)로 구분합니다.

The boot config syntax is a simple structured key-value. Each key consists
of dot-connected-words, and key and value are connected by ``=``. The value
has 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 ``=``.

Key word에는 alphabet, number, dash(`-`), underscore(`_`)만 사용할 수 있습니다. Value에는 printable character와 space를 쓸 수 있지만 semicolon, newline, comma, hash(`#`), closing brace(`}`) 같은 delimiter는 그대로 쓸 수 없습니다.

Delimiter를 value에 넣으려면 double quote(`"VALUE"`)나 single quote(`'VALUE'`)로 감쌉니다. Quote 자체는 escape할 수 없습니다. Value가 없거나 empty value인 key도 허용하며, 이런 key는 boolean처럼 존재 여부를 검사하는 데 사용합니다.

Structured key와 same-key value 규칙

Brace를 사용하면 앞부분 word가 같은 key를 묶을 수 있습니다. Dot으로 모두 쓴 표현, 여러 줄 brace 표현, 한 줄 brace 표현은 같은 tree로 parse됩니다. Boot-time parser는 같은 key word를 자동 merge하므로 비슷한 tree나 key-value를 뒤에 추가할 수 있습니다.

The boot config file syntax allows user to merge partially same word keys
by brace. For example::

 foo.bar.baz = value1
 foo.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 it
at boot time. So you can append similar trees or key-values.

같은 key를 두 개 이상의 value 또는 array가 공유하도록 재정의하는 것은 금지됩니다. 값을 바꾸려면 override operator `:=`를 명시적으로 사용합니다. 이 방식은 default bootconfig를 다시 parse하지 않고 partial custom bootconfig를 추가해 default 값을 덮을 때 유용합니다.

Same-key Values
---------------

It is prohibited that two or more values or arrays share a same-key.
For example,::

 foo = bar, baz
 foo = 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, baz
 foo := qux

then, the ``qux`` is assigned to ``foo`` key. This is useful for
overriding the default value by adding (partial) custom bootconfigs
without parsing the default bootconfig.

기존 key의 array 끝에 member를 추가하려면 `+=`를 사용합니다. `foo = bar, baz` 뒤 `foo += qux`를 적용하면 `foo`에는 `bar`, `baz`, `qux`가 들어갑니다.

If you want to append the value to existing key as an array member,
you can use ``+=`` operator. For example::

 foo = bar, baz
 foo += qux

In this case, the key ``foo`` has ``bar``, ``baz`` and ``qux``.

Parent key 아래에는 value와 sub-key가 함께 존재할 수 있습니다. `foo`, `foo.bar`를 같이 정의하고 `foo := value3`으로 parent value만 update할 수 있습니다.

Moreover, sub-keys and a value can coexist under a parent key.
For example, following config is allowed.::

 foo = value1
 foo.bar = value2
 foo := value3 # This will update foo's value.

Structured key의 brace 안에 raw value를 직접 넣는 syntax는 없으므로 parent value는 brace 바깥에서 정의해야 합니다. Key에 value와 sub-key가 모두 있으면 value node는 언제나 첫 child node입니다. User가 sub-key를 먼저 썼더라도 program과 `/proc/bootconfig` 출력에서는 parent value가 먼저 나타납니다.

Note, since there is no syntax to put a raw value directly under a
structured 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 there
are a value and subkeys, the value is always the first child node
of the key. Thus if user specifies subkeys first, e.g.::

 foo.bar = value1
 foo = value2

In the program (and /proc/bootconfig), it will be shown as below::

 foo = value2
 foo.bar = value1

Comment와 /proc/bootconfig

Config syntax는 shell-script 방식 comment를 허용합니다. Hash(`#`)부터 newline(`\n`)까지를 무시합니다. Array entry마다 comment를 둘 수 있으며, 예제는 comment를 제거해 `bar = 1, 2, 3`으로 parse됩니다.

The config syntax accepts shell-script style comments. The comments starting
with hash ("#") until newline ("\n") will be ignored.

::

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

This is parsed as below::

 foo = value
 bar = 1, 2, 3

Value와 delimiter(`,` 또는 `;`) 사이에는 comment를 넣을 수 없습니다. 따라서 value 뒤 comment가 줄을 끝내고 다음 줄에서 comma가 나타나는 예제는 syntax error입니다.

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`는 boot config의 user-space interface입니다. `/proc/cmdline`과 달리 key-value 형식 목록을 표시하며 각 pair를 한 줄씩 출력합니다.

/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"...]

Initrd에 boot config 연결

Kernel을 bootconfig와 함께 boot하는 방법은 두 가지입니다. Bootconfig를 initrd image에 붙이거나 kernel 자체에 embed할 수 있습니다. 기본 방식은 config file을 initrd(initramfs) image 끝에 padding, size, checksum, 12-byte magic word와 함께 추가하는 것입니다.

Since the boot configuration file is loaded with initrd by default,
it will be added to the end of the initrd (initramfs) image file with
padding, size, checksum and 12-byte magic word as below.

[initrd][bootconfig][padding][size(le32)][checksum(le32)][#BOOTCONFIG\n]

The size and checksum fields are unsigned 32bit little endian value.

Size와 checksum field는 unsigned 32-bit little-endian value입니다. Bootconfig를 추가한 전체 file size는 4 byte에 align하며 gap에는 NUL(`\0`)을 넣습니다. 따라서 `size`는 bootconfig file 길이와 padding byte 수의 합입니다.

Kernel은 memory의 initrd image 끝부분을 decode해 boot configuration을 얻습니다. 이 piggyback 방식은 boot loader가 정확한 initrd file size를 넘기는 한 boot loader나 kernel image를 바꿀 필요가 없습니다. Boot loader가 실제보다 긴 size를 넘기면 kernel은 bootconfig data를 찾지 못합니다.

Linux kernel은 `tools/bootconfig` 아래 `bootconfig` command를 제공합니다. Administrator는 이 tool로 initrd image에 config file을 적용하거나 제거할 수 있습니다.

To do this operation, Linux kernel provides ``bootconfig`` command under
tools/bootconfig, which allows admin to apply or delete the config file
to/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

`-a`로 추가할 때 기존 data가 있으면 자동 제거합니다. Kernel이 initrd 끝의 bootconfig를 찾도록 일반 kernel command line에 `bootconfig`를 추가해야 합니다. 또는 kernel을 `CONFIG_BOOT_CONFIG_FORCE` Kconfig option과 함께 build합니다.

Kernel에 boot config embed

Initrd를 사용할 수 없으면 Kconfig option으로 bootconfig file을 kernel에 embed할 수 있습니다. 다음 설정으로 kernel을 다시 compile합니다.

If you can not use initrd, you can also embed the bootconfig file in the
kernel by Kconfig options. In this case, you need to recompile the kernel
with the following configs::

 CONFIG_BOOT_CONFIG_EMBED=y
 CONFIG_BOOT_CONFIG_EMBED_FILE="/PATH/TO/BOOTCONFIG/FILE"

`CONFIG_BOOT_CONFIG_EMBED_FILE`에는 absolute path 또는 source tree/object tree 기준 relative path를 지정합니다. Kernel은 이 file을 default bootconfig로 embed합니다.

Initrd에 연결할 때와 마찬가지로 embedded bootconfig를 enable하려면 kernel command line의 `bootconfig` option 또는 `CONFIG_BOOT_CONFIG_FORCE`가 필요합니다. Initrd에 다른 bootconfig를 붙이면 embedded bootconfig를 override할 수 있습니다.

Boot config로 kernel·init parameter 전달

Boot config는 kernel command line 외에도 kernel parameter 전달에 사용할 수 있습니다. `kernel` key 아래 모든 key-value pair는 kernel cmdline에 직접 전달하고, `init` 아래 pair는 command line을 통해 init process에 전달합니다.

Parameter는 bootconfig 쪽이 먼저, user가 준 command line이 나중인 순서로 이어 붙입니다. 일반적으로 subsystem은 앞 parameter를 뒤 parameter로 덮으므로 command-line parameter가 bootconfig parameter를 override할 수 있지만 실제 동작은 subsystem의 parameter 처리 방식에 달려 있습니다.

In addition to the kernel command line, the boot config can be used for
passing the kernel parameters. All the key-value pairs under ``kernel``
key will be passed to kernel cmdline directly. Moreover, the key-value
pairs under ``init`` will be passed to init process via the cmdline.
The parameters are concatenated with user-given kernel cmdline string
as the following order, so that the command line parameter can override
bootconfig parameters (this depends on how the subsystem handles parameters
but 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 제한

현재 config 최대 크기는 32 KiB이고 전체 key-word 수는 1,024 node 미만이어야 합니다. 이는 entry 수가 아니라 node 수입니다. Entry 하나는 key-word와 value 등 두 node 이상을 소비하므로 이론상 key-value pair는 최대 약 512개입니다.

Key가 평균 세 word를 포함하면 약 256 pair를 담을 수 있습니다. 보통 config item은 100개 미만이고 8 KiB보다 작으므로 충분합니다. File이 32 KiB보다 작아도 node가 1,024개를 넘으면 parser가 error를 반환합니다. 최대 크기에는 padding NUL character를 포함하지 않습니다.

`bootconfig` command는 boot config를 initrd에 append할 때 이 제한을 검증하므로 user는 boot 전에 문제를 발견할 수 있습니다.

Bootconfig query와 iterator API

User는 key-value pair를 query하거나 순회할 수 있고, root(prefix) key node를 찾아 그 아래 pair를 탐색할 수도 있습니다. Key string이 있으면 `xbc_find_value()`로 value를 직접 찾습니다. 존재하는 key 전체를 보려면 `xbc_for_each_key_value()`를 사용합니다.

Array의 각 value에는 `xbc_array_for_each_value()`를 사용해야 합니다. `xbc_find_value()`가 돌려준 node가 array인지 `xbc_node_is_array()`로 확인한 뒤 value를 순회합니다.

If you have a key string, you can query the value directly with the key
using xbc_find_value(). If you want to know what keys exist in the boot
config, you can use xbc_for_each_key_value() to iterate key-value pairs.
Note that you need to use xbc_array_for_each_value() for accessing
each 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);
    }

특정 prefix를 가진 key에 집중하려면 `xbc_find_node()`로 prefix node를 찾고 `xbc_node_for_each_key_value()`로 그 아래 key를 순회합니다. 가장 흔한 용도는 prefix 아래 named value 또는 named array를 얻는 것입니다.

If you want to focus on keys which have a prefix string, you can use
xbc_find_node() to find a node by the prefix string, and iterate
keys under the prefix node with xbc_node_for_each_key_value().

But the most typical usage is to get the named value under prefix
or 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".

예제는 `key.prefix.option` value와 `key.prefix.array-option` array에 접근합니다. Initialization 뒤 config는 read-only가 되므로 locking은 필요하지 않습니다. 내용을 수정해야 하면 모든 data와 key를 복사해야 합니다.

Function과 structure reference

Bootconfig function과 structure의 kernel-doc reference는 `include/linux/bootconfig.h`와 `lib/bootconfig.c`에서 생성합니다.