diff options
Diffstat (limited to 'scripts/package-build/linux-kernel/README.md')
| -rw-r--r-- | scripts/package-build/linux-kernel/README.md | 65 |
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 |