Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
kho: docs: combine concepts and FDT documentation
Currently index.rst in KHO documentation looks empty and sad as it only
contains links to "Kexec Handover Concepts" and "KHO FDT" chapters.
Inline contents of these chapters into index.rst to provide a single
coherent chapter describing KHO.
While on it, drop parts of the KHO FDT description that will be superseded
by addition of KHO ABI documentation.
[rppt@kernel.org: fix Documentation/core-api/kho/index.rst]
Link: https://lkml.kernel.org/r/aV4bnHlBXGpT_FMc@kernel.org
Link: https://lkml.kernel.org/r/20260105165839.285270-4-rppt@kernel.org
Signed-off-by: Mike Rapoport (Microsoft) <rppt@kernel.org>
Reviewed-by: Pratyush Yadav <pratyush@kernel.org>
Cc: Alexander Graf <graf@amazon.com>
Cc: Jason Miu <jasonmiu@google.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Pratyush Yadav <pratyush@kernel.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
authored by
Mike Rapoport (Microsoft)
and committed by
Andrew Morton
a6f4e568
32cb2729
+75
-163
-74
Documentation/core-api/kho/concepts.rst
-74
Documentation/core-api/kho/concepts.rst
···
1
-
.. SPDX-License-Identifier: GPL-2.0-or-later
2
-
.. _kho-concepts:
3
-
4
-
=======================
5
-
Kexec Handover Concepts
6
-
=======================
7
-
8
-
Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
9
-
regions, which could contain serialized system states, across kexec.
10
-
11
-
It introduces multiple concepts:
12
-
13
-
KHO FDT
14
-
=======
15
-
16
-
Every KHO kexec carries a KHO specific flattened device tree (FDT) blob
17
-
that describes preserved memory regions. These regions contain either
18
-
serialized subsystem states, or in-memory data that shall not be touched
19
-
across kexec. After KHO, subsystems can retrieve and restore preserved
20
-
memory regions from KHO FDT.
21
-
22
-
KHO only uses the FDT container format and libfdt library, but does not
23
-
adhere to the same property semantics that normal device trees do: Properties
24
-
are passed in native endianness and standardized properties like ``regs`` and
25
-
``ranges`` do not exist, hence there are no ``#...-cells`` properties.
26
-
27
-
KHO is still under development. The FDT schema is unstable and would change
28
-
in the future.
29
-
30
-
Scratch Regions
31
-
===============
32
-
33
-
To boot into kexec, we need to have a physically contiguous memory range that
34
-
contains no handed over memory. Kexec then places the target kernel and initrd
35
-
into that region. The new kernel exclusively uses this region for memory
36
-
allocations before during boot up to the initialization of the page allocator.
37
-
38
-
We guarantee that we always have such regions through the scratch regions: On
39
-
first boot KHO allocates several physically contiguous memory regions. Since
40
-
after kexec these regions will be used by early memory allocations, there is a
41
-
scratch region per NUMA node plus a scratch region to satisfy allocations
42
-
requests that do not require particular NUMA node assignment.
43
-
By default, size of the scratch region is calculated based on amount of memory
44
-
allocated during boot. The ``kho_scratch`` kernel command line option may be
45
-
used to explicitly define size of the scratch regions.
46
-
The scratch regions are declared as CMA when page allocator is initialized so
47
-
that their memory can be used during system lifetime. CMA gives us the
48
-
guarantee that no handover pages land in that region, because handover pages
49
-
must be at a static physical memory location and CMA enforces that only
50
-
movable pages can be located inside.
51
-
52
-
After KHO kexec, we ignore the ``kho_scratch`` kernel command line option and
53
-
instead reuse the exact same region that was originally allocated. This allows
54
-
us to recursively execute any amount of KHO kexecs. Because we used this region
55
-
for boot memory allocations and as target memory for kexec blobs, some parts
56
-
of that memory region may be reserved. These reservations are irrelevant for
57
-
the next KHO, because kexec can overwrite even the original kernel.
58
-
59
-
.. _kho-finalization-phase:
60
-
61
-
KHO finalization phase
62
-
======================
63
-
64
-
To enable user space based kexec file loader, the kernel needs to be able to
65
-
provide the FDT that describes the current kernel's state before
66
-
performing the actual kexec. The process of generating that FDT is
67
-
called serialization. When the FDT is generated, some properties
68
-
of the system may become immutable because they are already written down
69
-
in the FDT. That state is called the KHO finalization phase.
70
-
71
-
Public API
72
-
==========
73
-
.. kernel-doc:: kernel/liveupdate/kexec_handover.c
74
-
:export:
-80
Documentation/core-api/kho/fdt.rst
-80
Documentation/core-api/kho/fdt.rst
···
1
-
.. SPDX-License-Identifier: GPL-2.0-or-later
2
-
3
-
=======
4
-
KHO FDT
5
-
=======
6
-
7
-
KHO uses the flattened device tree (FDT) container format and libfdt
8
-
library to create and parse the data that is passed between the
9
-
kernels. The properties in KHO FDT are stored in native format.
10
-
It includes the physical address of an in-memory structure describing
11
-
all preserved memory regions, as well as physical addresses of KHO users'
12
-
own FDTs. Interpreting those sub FDTs is the responsibility of KHO users.
13
-
14
-
KHO nodes and properties
15
-
========================
16
-
17
-
Property ``preserved-memory-map``
18
-
---------------------------------
19
-
20
-
KHO saves a special property named ``preserved-memory-map`` under the root node.
21
-
This node contains the physical address of an in-memory structure for KHO to
22
-
preserve memory regions across kexec.
23
-
24
-
Property ``compatible``
25
-
-----------------------
26
-
27
-
The ``compatible`` property determines compatibility between the kernel
28
-
that created the KHO FDT and the kernel that attempts to load it.
29
-
If the kernel that loads the KHO FDT is not compatible with it, the entire
30
-
KHO process will be bypassed.
31
-
32
-
Property ``fdt``
33
-
----------------
34
-
35
-
Generally, a KHO user serialize its state into its own FDT and instructs
36
-
KHO to preserve the underlying memory, such that after kexec, the new kernel
37
-
can recover its state from the preserved FDT.
38
-
39
-
A KHO user thus can create a node in KHO root tree and save the physical address
40
-
of its own FDT in that node's property ``fdt`` .
41
-
42
-
Examples
43
-
========
44
-
45
-
The following example demonstrates KHO FDT that preserves two memory
46
-
regions created with ``reserve_mem`` kernel command line parameter::
47
-
48
-
/dts-v1/;
49
-
50
-
/ {
51
-
compatible = "kho-v1";
52
-
53
-
preserved-memory-map = <0x40be16 0x1000000>;
54
-
55
-
memblock {
56
-
fdt = <0x1517 0x1000000>;
57
-
};
58
-
};
59
-
60
-
where the ``memblock`` node contains an FDT that is requested by the
61
-
subsystem memblock for preservation. The FDT contains the following
62
-
serialized data::
63
-
64
-
/dts-v1/;
65
-
66
-
/ {
67
-
compatible = "memblock-v1";
68
-
69
-
n1 {
70
-
compatible = "reserve-mem-v1";
71
-
start = <0xc06b 0x4000000>;
72
-
size = <0x04 0x00>;
73
-
};
74
-
75
-
n2 {
76
-
compatible = "reserve-mem-v1";
77
-
start = <0xc067 0x4000000>;
78
-
size = <0x04 0x00>;
79
-
};
80
-
};
+72
-5
Documentation/core-api/kho/index.rst
+72
-5
Documentation/core-api/kho/index.rst
···
1
1
.. SPDX-License-Identifier: GPL-2.0-or-later
2
2
3
+
.. _kho-concepts:
4
+
3
5
========================
4
6
Kexec Handover Subsystem
5
7
========================
6
8
7
-
.. toctree::
8
-
:maxdepth: 1
9
+
Overview
10
+
========
9
11
10
-
concepts
11
-
fdt
12
+
Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
13
+
regions, which could contain serialized system states, across kexec.
12
14
13
-
.. only:: subproject and html
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_scratch:
35
+
36
+
Scratch Regions
37
+
===============
38
+
39
+
To boot into kexec, we need to have a physically contiguous memory range that
40
+
contains no handed over memory. Kexec then places the target kernel and initrd
41
+
into that region. The new kernel exclusively uses this region for memory
42
+
allocations before during boot up to the initialization of the page allocator.
43
+
44
+
We guarantee that we always have such regions through the scratch regions: On
45
+
first boot KHO allocates several physically contiguous memory regions. Since
46
+
after kexec these regions will be used by early memory allocations, there is a
47
+
scratch region per NUMA node plus a scratch region to satisfy allocations
48
+
requests that do not require particular NUMA node assignment.
49
+
By default, size of the scratch region is calculated based on amount of memory
50
+
allocated during boot. The ``kho_scratch`` kernel command line option may be
51
+
used to explicitly define size of the scratch regions.
52
+
The scratch regions are declared as CMA when page allocator is initialized so
53
+
that their memory can be used during system lifetime. CMA gives us the
54
+
guarantee that no handover pages land in that region, because handover pages
55
+
must be at a static physical memory location and CMA enforces that only
56
+
movable pages can be located inside.
57
+
58
+
After KHO kexec, we ignore the ``kho_scratch`` kernel command line option and
59
+
instead reuse the exact same region that was originally allocated. This allows
60
+
us to recursively execute any amount of KHO kexecs. Because we used this region
61
+
for boot memory allocations and as target memory for kexec blobs, some parts
62
+
of that memory region may be reserved. These reservations are irrelevant for
63
+
the next KHO, because kexec can overwrite even the original kernel.
64
+
65
+
.. _kho-finalization-phase:
66
+
67
+
KHO finalization phase
68
+
======================
69
+
70
+
To enable user space based kexec file loader, the kernel needs to be able to
71
+
provide the FDT that describes the current kernel's state before
72
+
performing the actual kexec. The process of generating that FDT is
73
+
called serialization. When the FDT is generated, some properties
74
+
of the system may become immutable because they are already written down
75
+
in the FDT. That state is called the KHO finalization phase.
76
+
77
+
See Also
78
+
========
79
+
80
+
- :doc:`/admin-guide/mm/kho`
+1
-1
Documentation/core-api/liveupdate.rst
+1
-1
Documentation/core-api/liveupdate.rst
+1
-1
Documentation/mm/memfd_preservation.rst
+1
-1
Documentation/mm/memfd_preservation.rst
+1
-2
kernel/liveupdate/luo_core.c
+1
-2
kernel/liveupdate/luo_core.c
···
35
35
* iommu, interrupts, vfio, participating filesystems, and memory management.
36
36
*
37
37
* LUO uses Kexec Handover to transfer memory state from the current kernel to
38
-
* the next kernel. For more details see
39
-
* Documentation/core-api/kho/concepts.rst.
38
+
* the next kernel. For more details see Documentation/core-api/kho/index.rst.
40
39
*/
41
40
42
41
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt