mirror of
https://github.com/torvalds/linux.git
synced 2026-06-04 20:46:48 +02:00
e524feaad5
Add documentation for the kexec-metadata feature that tracks the previous kernel version and kexec boot count across kexec reboots. This helps diagnose bugs that only reproduce when kexecing from specific kernel versions. Link: https://lore.kernel.org/20260316-kho-v9-6-ed6dcd951988@debian.org Signed-off-by: Breno Leitao <leitao@debian.org> Suggested-by: Mike Rapoport <rppt@kernel.org> Reviewed-by: Mike Rapoport (Microsoft) <rppt@kernel.org> Reviewed-by: Pratyush Yadav <pratyush@kernel.org> Cc: Alexander Graf <graf@amazon.com> Cc: David Hildenbrand <david@kernel.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: "Liam R. Howlett" <Liam.Howlett@oracle.com> Cc: Lorenzo Stoakes <ljs@kernel.org> Cc: Michal Hocko <mhocko@suse.com> Cc: Pasha Tatashin <pasha.tatashin@soleen.com> Cc: SeongJae Park <sj@kernel.org> Cc: Shuah Khan <skhan@linuxfoundation.org> Cc: Suren Baghdasaryan <surenb@google.com> Cc: Vlastimil Babka <vbabka@kernel.org> Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
124 lines
4.6 KiB
ReStructuredText
124 lines
4.6 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
====================
|
|
Kexec Handover Usage
|
|
====================
|
|
|
|
Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
|
|
regions, which could contain serialized system states, across kexec.
|
|
|
|
This document expects that you are familiar with the base KHO
|
|
:ref:`concepts <kho-concepts>`. If you have not read
|
|
them yet, please do so now.
|
|
|
|
Prerequisites
|
|
=============
|
|
|
|
KHO is available when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER``
|
|
set to y. Every KHO producer may have its own config option that you
|
|
need to enable if you would like to preserve their respective state across
|
|
kexec.
|
|
|
|
To use KHO, please boot the kernel with the ``kho=on`` command line
|
|
parameter. You may use ``kho_scratch`` parameter to define size of the
|
|
scratch regions. For example ``kho_scratch=16M,512M,256M`` will reserve a
|
|
16 MiB low memory scratch area, a 512 MiB global scratch region, and 256 MiB
|
|
per NUMA node scratch regions on boot.
|
|
|
|
Perform a KHO kexec
|
|
===================
|
|
|
|
To perform a KHO kexec, load the target payload and kexec into it. It
|
|
is important that you use the ``-s`` parameter to use the in-kernel
|
|
kexec file loader, as user space kexec tooling currently has no
|
|
support for KHO with the user space based file loader ::
|
|
|
|
# kexec -l /path/to/bzImage --initrd /path/to/initrd -s
|
|
# kexec -e
|
|
|
|
The new kernel will boot up and contain some of the previous kernel's state.
|
|
|
|
For example, if you used ``reserve_mem`` command line parameter to create
|
|
an early memory reservation, the new kernel will have that memory at the
|
|
same physical address as the old kernel.
|
|
|
|
Kexec Metadata
|
|
==============
|
|
|
|
KHO automatically tracks metadata about the kexec chain, passing information
|
|
about the previous kernel to the next kernel. This feature helps diagnose
|
|
bugs that only reproduce when kexecing from specific kernel versions.
|
|
|
|
On each KHO kexec, the kernel logs the previous kernel's version and the
|
|
number of kexec reboots since the last cold boot::
|
|
|
|
[ 0.000000] KHO: exec from: 6.19.0-rc4-next-20260107 (count 1)
|
|
|
|
The metadata includes:
|
|
|
|
``previous_release``
|
|
The kernel version string (from ``uname -r``) of the kernel that
|
|
initiated the kexec.
|
|
|
|
``kexec_count``
|
|
The number of kexec boots since the last cold boot. On cold boot,
|
|
this counter starts at 0 and increments with each kexec. This helps
|
|
identify issues that only manifest after multiple consecutive kexec
|
|
reboots.
|
|
|
|
Use Cases
|
|
---------
|
|
|
|
This metadata is particularly useful for debugging kexec transition bugs,
|
|
where a buggy kernel kexecs into a new kernel and the bug manifests only
|
|
in the second kernel. Examples of such bugs include:
|
|
|
|
- Memory corruption from the previous kernel affecting the new kernel
|
|
- Incorrect hardware state left by the previous kernel
|
|
- Firmware/ACPI state issues that only appear in kexec scenarios
|
|
|
|
At scale, correlating crashes to the previous kernel version enables
|
|
faster root cause analysis when issues only occur in specific kernel
|
|
transition scenarios.
|
|
|
|
debugfs Interfaces
|
|
==================
|
|
|
|
These debugfs interfaces are available when the kernel is compiled with
|
|
``CONFIG_KEXEC_HANDOVER_DEBUGFS`` enabled.
|
|
|
|
Currently KHO creates the following debugfs interfaces. Notice that these
|
|
interfaces may change in the future. They will be moved to sysfs once KHO is
|
|
stabilized.
|
|
|
|
``/sys/kernel/debug/kho/out/fdt``
|
|
The kernel exposes the flattened device tree blob that carries its
|
|
current KHO state in this file. Kexec user space tooling can use this
|
|
as input file for the KHO payload image.
|
|
|
|
``/sys/kernel/debug/kho/out/scratch_len``
|
|
Lengths of KHO scratch regions, which are physically contiguous
|
|
memory regions that will always stay available for future kexec
|
|
allocations. Kexec user space tools can use this file to determine
|
|
where it should place its payload images.
|
|
|
|
``/sys/kernel/debug/kho/out/scratch_phys``
|
|
Physical locations of KHO scratch regions. Kexec user space tools
|
|
can use this file in conjunction to scratch_phys to determine where
|
|
it should place its payload images.
|
|
|
|
``/sys/kernel/debug/kho/out/sub_fdts/``
|
|
KHO producers can register their own FDT or another binary blob under
|
|
this directory.
|
|
|
|
``/sys/kernel/debug/kho/in/fdt``
|
|
When the kernel was booted with Kexec HandOver (KHO),
|
|
the state tree that carries metadata about the previous
|
|
kernel's state is in this file in the format of flattened
|
|
device tree. This file may disappear when all consumers of
|
|
it finished to interpret their metadata.
|
|
|
|
``/sys/kernel/debug/kho/in/sub_fdts/``
|
|
Similar to ``kho/out/sub_fdts/``, but contains sub blobs
|
|
of KHO producers passed from the old kernel.
|