kernel: configs: update README
Embellish the README a bit, and add some details about the
new fragment method.
-## How to use config files
+* [Kata Containers kernel config files](#kata-containers-kernel-config-files)
+ * [Types of config files](#types-of-config-files)
+ * [How to use config files](#how-to-use-config-files)
+ * [How to modify config files](#how-to-modify-config-files)
-config files must be copied in the kernel source code directory and renamed to `.config`
+# Kata Containers kernel config files
-For example:
+This directory contains Linux Kernel config files used to configure Kata
+Containers VM kernels.
+## Types of config files
+
+This directory holds config files for the Kata Linux Kernel in two forms:
+
+- A tree of config file 'fragments' in the `fragments` sub-folder, that are
+ constructed into a complete config file using the kernel
+ `scripts/kconfig/merge_config.sh` script.
+- As complete config files that can be used as-is.
+
+Kernel config fragments are the preferred method of constructing `.config` files
+to build Kata Containers kernels, due to their improved clarity and ease of maintenance
+over single file monolithic `.config`s.
+
+## How to use config files
+
+The recommended way to set up a kernel tree, populate it with a relevant `.config` file,
+and build a kernel, is to use the [`build_kernel.sh`](../build-kernel.sh) script. For
+example:
+
+```bash
+$ ./build-kernel.sh setup
```
-cp x86_kata_kvm_4.14.x linux-4.14.22/.config
-pushd linux-4.14.22
-make ARCH=x86_64 -j4
-```
+
+The `build-kernel.sh` script understands both full and fragment based config files.
+
+Run `./build-kernel.sh help` for more information.
## How to modify config files
+Complete config files can be modified either with an editor, or preferably
+using the kernel `Kconfig` configuration tools, for example:
+
```
-cp x86_kata_kvm_4.14.x linux-4.14.22/.config
-pushd linux-4.14.22
-make menuconfig
-popd
-cp linux-4.14.22/.config x86_kata_kvm_4.14.x
+$ cp x86_kata_kvm_4.14.x linux-4.14.22/.config
+$ pushd linux-4.14.22
+$ make menuconfig
+$ popd
+$ cp linux-4.14.22/.config x86_kata_kvm_4.14.x
```
+
+Kernel fragments are best constructed using an editor. Tools such as `grep` and
+`diff` can help find the differences between two config files to be placed
+into a fragment.
+
+If adding config entries for a new subsystem or feature, consider making a new
+fragment with an appropriately descriptive name.
+
+The fragment gathering tool perfoms some basic sanity checks, and the `build-kernel.sh` will
+fail and report the error in the cases of:
+
+- A duplicate `CONFIG` symbol appearing.
+- A `CONFIG` symbol being in a fragment, but not appearing in the final .config
+ - which indicates that `CONFIG` variable is not a part of the kernel `Kconfig` setup, which
+ can indicate a typing mistake in the name of the symbol.
+- A `CONFIG` symbol appearing in the fragments with multiple different values.
