Kernel: T9014: document the Kernel configuration flow

The README still described the pre-T8506 flow, where a single
x86_64_vyos_defconfig was copied into arch/x86/configs of the Kernel source
tree. That file and that flow no longer exist, and the text also claimed
the Kernel was 6.6 and that only amd64 was built.

Describe what actually happens: a per architecture base config selected from
dpkg --print-architecture, the config/*.config snippets merged on top in
file name order, and the module signing snippet generated at build time.

1 files changed, 56 insertions, 9 deletions

diff --git a/scripts/package-build/linux-kernel/README.md b/scripts/package-build/linux-kernel/README.md
index cc02262a..56ef649b 100644
--- a/scripts/package-build/linux-kernel/README.md
+++ b/scripts/package-build/linux-kernel/README.md
@@ -5,9 +5,10 @@
 
 # About
 
-VyOS runs on a custom Linux Kernel (which is 6.6) at the time of this writing.
-This repository holds build scripts that are used to build the Custom Kernel
-(x86_64/amd64 at the moment) and all required out-of tree modules.
+VyOS runs on a custom Linux Kernel. The version built is pinned by
+`kernel_version` in [data/defaults.toml](../../../data/defaults.toml). This
+repository holds the build scripts used to build the custom Kernel for
+x86_64/amd64 and arm64, plus all required out-of-tree modules.
 
 VyOS does not utilize the build in Intel Kernel drivers for its NICs as those
 Kernels sometimes lack features e.g. configurable receive-side-scaling queues.
@@ -16,16 +17,62 @@ On the other hand we ship additional not mainlined features as WireGuard VPN.
 ## Kernel
 
 The Kernel is build from the vanilla repositories hosted at https://git.kernel.org.
-VyOS requires two additional patches to work which are stored in the patches/kernel
-folder.
+VyOS requires a few additional patches to work which are stored in the
+patches/kernel folder. They are applied *before* the Kernel configuration is
+generated, as a patch may introduce new Kconfig symbols.
 
 ### Config
 
-The Kernel configuration used is [x86_64_vyos_defconfig](x86_64_vyos_defconfig)
-which will be copied on demand during the Pipeline run into the `arch/x86/configs`
-directory of the Kernel source tree.
+The Kernel configuration is assembled by `build-kernel.sh` using the Kernel's own
+`scripts/kconfig/merge_config.sh`:
 
-Other configurations can be added in the future easily.
+* a per-architecture base configuration, selected from `dpkg --print-architecture`
+  * amd64 -> [config/x86/vyos_defconfig](config/x86/vyos_defconfig)
+  * arm64 -> [config/arm64/vyos_defconfig](config/arm64/vyos_defconfig)
+* all feature snippets in [config/](config/) (`config/*.config`), merged on top of
+  the base in file name order
+* a temporary snippet enabling module signing, generated at build time when
+  `data/certificates/*.pem` are present
+
+`merge_config.sh` concatenates all of the above, runs `make alldefconfig`, and
+then verifies that every requested line appears verbatim in the resulting
+`.config`. Any that does not is reported as:
+
+```
+Value requested for CONFIG_FOO not in final .config
+```
+
+These warnings are deliberately **not** suppressed - they are the only signal we
+get when a snippet silently stops taking effect (symbol removed upstream,
+dependency no longer met, or a value overridden by a `select`). Treat a new
+warning as a bug to be investigated, not as noise.
+
+#### Regenerating a base configuration
+
+The per-architecture base configurations are full `.config` dumps and must be
+regenerated whenever they fall far enough behind the Kernel version that the
+warnings above become unmanageable. Build natively on the target architecture
+and run:
+
+```bash
+cd scripts/package-build/linux-kernel/linux
+scripts/kconfig/merge_config.sh ../config/<arch>/vyos_defconfig ../config/*.config
+cd ..
+cp linux/.config config/<arch>/vyos_defconfig
+# host specific values - these differ per builder and must never be committed
+sed -i -E '/^CONFIG_(CC_VERSION_TEXT|GCC_VERSION|CLANG_VERSION|LLD_VERSION|RUSTC_VERSION|RUSTC_LLVM_VERSION|AS_VERSION|LD_VERSION|PAHOLE_VERSION)=/d' config/<arch>/vyos_defconfig
+# injected at build time from data/certificates - must never be committed
+sed -i -E '/^CONFIG_SYSTEM_TRUSTED_KEYS=/d' config/<arch>/vyos_defconfig
+```
+
+Re-running `merge_config.sh` against the regenerated file must now produce a
+byte identical `.config` - that fixed point is the proof the file is canonical.
+Verify there is no functional change by diffing the produced `.config` from
+before and after, never the `vyos_defconfig` files themselves.
+
+Note that `build-kernel.sh` starts with `git reset --hard` and `git clean -fdx`
+inside `linux/`, so anything you want to keep from a previous run has to be
+copied out of that directory first.
 
 ### Modules