Debian Codegraph @

Documentation/core-api/kho/index.rst

raw
1 .. SPDX-License-Identifier: GPL-2.0-or-later
2
3 .. _kho-concepts:
4
5 ========================
6 Kexec Handover Subsystem
7 ========================
8
9 Overview
10 ========
11
12 Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
13 regions, which could contain serialized system states, across kexec.
14
15 KHO uses :ref:`flattened device tree (FDT) <kho_fdt>` to pass information about
16 the preserved state from pre-exec kernel to post-kexec kernel and :ref:`scratch
17 memory regions <kho_scratch>` to ensure integrity of the preserved memory.
18
19 .. _kho_fdt:
20
21 KHO FDT
22 =======
23 Every KHO kexec carries a KHO specific flattened device tree (FDT) blob that
24 describes the preserved state. The FDT includes properties describing preserved
25 memory regions and nodes that hold subsystem specific state.
26
27 The preserved memory regions contain either serialized subsystem states, or
28 in-memory data that shall not be touched across kexec. After KHO, subsystems
29 can retrieve and restore the preserved state from KHO FDT.
30
31 Subsystems participating in KHO can define their own format for state
32 serialization and preservation.
33
34 KHO FDT and structures defined by the subsystems form an ABI between pre-kexec
35 and post-kexec kernels. This ABI is defined by header files in
36 ``include/linux/kho/abi`` directory.
37
38 .. toctree::
39 :maxdepth: 1
40
41 abi.rst
42
43 .. _kho_scratch:
44
45 Scratch Regions
46 ===============
47
48 To boot into kexec, we need to have a physically contiguous memory range that
49 contains no handed over memory. Kexec then places the target kernel and initrd
50 into that region. The new kernel exclusively uses this region for memory
51 allocations before during boot up to the initialization of the page allocator.
52
53 We guarantee that we always have such regions through the scratch regions: On
54 first boot KHO allocates several physically contiguous memory regions. Since
55 after kexec these regions will be used by early memory allocations, there is a
56 scratch region per NUMA node plus a scratch region to satisfy allocations
57 requests that do not require particular NUMA node assignment.
58 By default, size of the scratch region is calculated based on amount of memory
59 allocated during boot. The ``kho_scratch`` kernel command line option may be
60 used to explicitly define size of the scratch regions.
61 The scratch regions are declared as CMA when page allocator is initialized so
62 that their memory can be used during system lifetime. CMA gives us the
63 guarantee that no handover pages land in that region, because handover pages
64 must be at a static physical memory location and CMA enforces that only
65 movable pages can be located inside.
66
67 After KHO kexec, we ignore the ``kho_scratch`` kernel command line option and
68 instead reuse the exact same region that was originally allocated. This allows
69 us to recursively execute any amount of KHO kexecs. Because we used this region
70 for boot memory allocations and as target memory for kexec blobs, some parts
71 of that memory region may be reserved. These reservations are irrelevant for
72 the next KHO, because kexec can overwrite even the original kernel.
73
74 .. _kho-finalization-phase:
75
76 KHO finalization phase
77 ======================
78
79 To enable user space based kexec file loader, the kernel needs to be able to
80 provide the FDT that describes the current kernel's state before
81 performing the actual kexec. The process of generating that FDT is
82 called serialization. When the FDT is generated, some properties
83 of the system may become immutable because they are already written down
84 in the FDT. That state is called the KHO finalization phase.
85
86 See Also
87 ========
88
89 - :doc:`/admin-guide/mm/kho`