Add a section describing CONFIG_BOOT_CONFIG_EMBED_CMDLINE: what it does (renders the embedded "kernel" subtree to a flat cmdline at build time so early_param() handlers see the values), what it requires (BOOT_CONFIG_EMBED, a non-empty BOOT_CONFIG_EMBED_FILE, and ARCH_SUPPORTS_CMDLINE_FROM_BOOTCONFIG -- currently x86 only), the bootconfig opt-in semantics, the initrd-vs-embedded precedence, and the soft-error overflow behavior.
Signed-off-by: Breno Leitao <[email protected]> --- Documentation/admin-guide/bootconfig.rst | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Documentation/admin-guide/bootconfig.rst b/Documentation/admin-guide/bootconfig.rst index f712758472d5..f371e5cdc974 100644 --- a/Documentation/admin-guide/bootconfig.rst +++ b/Documentation/admin-guide/bootconfig.rst @@ -234,6 +234,52 @@ Kconfig option selected. Note that even if you set this option, you can override the embedded bootconfig by another bootconfig which attached to the initrd. +Rendering Embedded kernel.* Keys at Build Time +---------------------------------------------- + +By default, the embedded bootconfig (``CONFIG_BOOT_CONFIG_EMBED=y``) is +parsed at runtime, after ``parse_early_param()`` has already run. Early +parameter handlers (``mem=``, ``earlycon=``, ``loglevel=``, ...) therefore +cannot see values supplied via the embedded ``kernel`` subtree. + +``CONFIG_BOOT_CONFIG_EMBED_CMDLINE`` resolves this by rendering the +``kernel`` subtree of ``CONFIG_BOOT_CONFIG_EMBED_FILE`` into a flat cmdline +string at kernel build time (via ``tools/bootconfig -C``) and prepending +it to ``boot_command_line`` during early architecture setup, so the keys +are visible to ``parse_early_param()``. + +The option requires ``CONFIG_BOOT_CONFIG_EMBED=y``, a non-empty +``CONFIG_BOOT_CONFIG_EMBED_FILE``, and an architecture that selects +``CONFIG_ARCH_SUPPORTS_CMDLINE_FROM_BOOTCONFIG``. Currently only x86 +selects it; on other architectures the embedded bootconfig still works, +but only through the late runtime parser. + +The same ``bootconfig`` opt-in applies as elsewhere: the rendered keys +are prepended only when ``bootconfig`` (in any form) appears on the +kernel command line, or when ``CONFIG_BOOT_CONFIG_FORCE`` is set, which +defaults to ``y`` when ``CONFIG_BOOT_CONFIG_EMBED`` is set. + +For example, given:: + + kernel { + loglevel = 7 + mem = 4G + } + +the kernel boots as if ``loglevel=7 mem=4G`` had been prepended to the +bootloader command line, with the values visible to early-parsed +handlers. Comma-separated values are still expanded into multiple +cmdline entries per the bootconfig array convention -- the embedded +``kernel.earlycon = "uart8250,io,0x3f8"`` must be quoted to land as a +single ``earlycon=`` entry, exactly as for the runtime parser. + +If an initrd carries its own bootconfig, the runtime parser still +processes it; ``parse_args()`` last-wins means the initrd's ``kernel`` +keys override the build-time-rendered ones. If the rendered string +would not fit in ``COMMAND_LINE_SIZE`` together with the existing +command line, the prepend is skipped and an error is logged, so an +oversized embedded bootconfig cannot brick a boot. + Kernel parameters via Boot Config ================================= -- 2.53.0-Meta
