Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3====================
4Kexec Handover Usage
5====================
6
7Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
8regions, which could contain serialized system states, across kexec.
9
10This document expects that you are familiar with the base KHO
11:ref:`concepts <kho-concepts>`. If you have not read
12them yet, please do so now.
13
14Prerequisites
15=============
16
17KHO is available when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER``
18set to y. Every KHO producer may have its own config option that you
19need to enable if you would like to preserve their respective state across
20kexec.
21
22To use KHO, please boot the kernel with the ``kho=on`` command line
23parameter. You may use ``kho_scratch`` parameter to define size of the
24scratch regions. For example ``kho_scratch=16M,512M,256M`` will reserve a
2516 MiB low memory scratch area, a 512 MiB global scratch region, and 256 MiB
26per NUMA node scratch regions on boot.
27
28Perform a KHO kexec
29===================
30
31To perform a KHO kexec, load the target payload and kexec into it. It
32is important that you use the ``-s`` parameter to use the in-kernel
33kexec file loader, as user space kexec tooling currently has no
34support for KHO with the user space based file loader ::
35
36 # kexec -l /path/to/bzImage --initrd /path/to/initrd -s
37 # kexec -e
38
39The new kernel will boot up and contain some of the previous kernel's state.
40
41For example, if you used ``reserve_mem`` command line parameter to create
42an early memory reservation, the new kernel will have that memory at the
43same physical address as the old kernel.
44
45Kexec Metadata
46==============
47
48KHO automatically tracks metadata about the kexec chain, passing information
49about the previous kernel to the next kernel. This feature helps diagnose
50bugs that only reproduce when kexecing from specific kernel versions.
51
52On each KHO kexec, the kernel logs the previous kernel's version and the
53number of kexec reboots since the last cold boot::
54
55 [ 0.000000] KHO: exec from: 6.19.0-rc4-next-20260107 (count 1)
56
57The metadata includes:
58
59``previous_release``
60 The kernel version string (from ``uname -r``) of the kernel that
61 initiated the kexec.
62
63``kexec_count``
64 The number of kexec boots since the last cold boot. On cold boot,
65 this counter starts at 0 and increments with each kexec. This helps
66 identify issues that only manifest after multiple consecutive kexec
67 reboots.
68
69Use Cases
70---------
71
72This metadata is particularly useful for debugging kexec transition bugs,
73where a buggy kernel kexecs into a new kernel and the bug manifests only
74in the second kernel. Examples of such bugs include:
75
76- Memory corruption from the previous kernel affecting the new kernel
77- Incorrect hardware state left by the previous kernel
78- Firmware/ACPI state issues that only appear in kexec scenarios
79
80At scale, correlating crashes to the previous kernel version enables
81faster root cause analysis when issues only occur in specific kernel
82transition scenarios.
83
84debugfs Interfaces
85==================
86
87These debugfs interfaces are available when the kernel is compiled with
88``CONFIG_KEXEC_HANDOVER_DEBUGFS`` enabled.
89
90Currently KHO creates the following debugfs interfaces. Notice that these
91interfaces may change in the future. They will be moved to sysfs once KHO is
92stabilized.
93
94``/sys/kernel/debug/kho/out/fdt``
95 The kernel exposes the flattened device tree blob that carries its
96 current KHO state in this file. Kexec user space tooling can use this
97 as input file for the KHO payload image.
98
99``/sys/kernel/debug/kho/out/scratch_len``
100 Lengths of KHO scratch regions, which are physically contiguous
101 memory regions that will always stay available for future kexec
102 allocations. Kexec user space tools can use this file to determine
103 where it should place its payload images.
104
105``/sys/kernel/debug/kho/out/scratch_phys``
106 Physical locations of KHO scratch regions. Kexec user space tools
107 can use this file in conjunction to scratch_phys to determine where
108 it should place its payload images.
109
110``/sys/kernel/debug/kho/out/sub_fdts/``
111 KHO producers can register their own FDT or another binary blob under
112 this directory.
113
114``/sys/kernel/debug/kho/in/fdt``
115 When the kernel was booted with Kexec HandOver (KHO),
116 the state tree that carries metadata about the previous
117 kernel's state is in this file in the format of flattened
118 device tree. This file may disappear when all consumers of
119 it finished to interpret their metadata.
120
121``/sys/kernel/debug/kho/in/sub_fdts/``
122 Similar to ``kho/out/sub_fdts/``, but contains sub blobs
123 of KHO producers passed from the old kernel.