Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
kho: introduce KHO FDT ABI header
Introduce the `include/linux/kho/abi/kexec_handover.h` header file, which
defines the stable ABI for the KHO mechanism. This header specifies how
preserved data is passed between kernels using an FDT.
The ABI contract includes the FDT structure, node properties, and the
"kho-v1" compatible string. By centralizing these definitions, this
header serves as the foundational agreement for inter-kernel communication
of preserved states, ensuring forward compatibility and preventing
misinterpretation of data across kexec transitions.
Since the ABI definitions are now centralized in the header files, the
YAML files that previously described the FDT interfaces are redundant.
These redundant files have therefore been removed.
Link: https://lkml.kernel.org/r/20260105165839.285270-5-rppt@kernel.org
Signed-off-by: Jason Miu <jasonmiu@google.com>
Co-developed-by: Mike Rapoport (Microsoft) <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: Jonathan Corbet <corbet@lwn.net>
Cc: Pasha Tatashin <pasha.tatashin@soleen.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
authored by
Jason Miu
and committed by
Andrew Morton
5e1ea1e2
a6f4e568
+120
-80
+16
Documentation/core-api/kho/abi.rst
+16
Documentation/core-api/kho/abi.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+
==================
4
+
Kexec Handover ABI
5
+
==================
6
+
7
+
Core Kexec Handover ABI
8
+
========================
9
+
10
+
.. kernel-doc:: include/linux/kho/abi/kexec_handover.h
11
+
:doc: Kexec Handover ABI
12
+
13
+
See Also
14
+
========
15
+
16
+
- :doc:`/admin-guide/mm/kho`
-43
Documentation/core-api/kho/bindings/kho.yaml
-43
Documentation/core-api/kho/bindings/kho.yaml
···
1
-
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
-
%YAML 1.2
3
-
---
4
-
title: Kexec HandOver (KHO) root tree
5
-
6
-
maintainers:
7
-
- Mike Rapoport <rppt@kernel.org>
8
-
- Changyuan Lyu <changyuanl@google.com>
9
-
10
-
description: |
11
-
System memory preserved by KHO across kexec.
12
-
13
-
properties:
14
-
compatible:
15
-
enum:
16
-
- kho-v1
17
-
18
-
preserved-memory-map:
19
-
description: |
20
-
physical address (u64) of an in-memory structure describing all preserved
21
-
folios and memory ranges.
22
-
23
-
patternProperties:
24
-
"$[0-9a-f_]+^":
25
-
$ref: sub-fdt.yaml#
26
-
description: physical address of a KHO user's own FDT.
27
-
28
-
required:
29
-
- compatible
30
-
- preserved-memory-map
31
-
32
-
additionalProperties: false
33
-
34
-
examples:
35
-
- |
36
-
kho {
37
-
compatible = "kho-v1";
38
-
preserved-memory-map = <0xf0be16 0x1000000>;
39
-
40
-
memblock {
41
-
fdt = <0x80cc16 0x1000000>;
42
-
};
43
-
};
-27
Documentation/core-api/kho/bindings/sub-fdt.yaml
-27
Documentation/core-api/kho/bindings/sub-fdt.yaml
···
1
-
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2
-
%YAML 1.2
3
-
---
4
-
title: KHO users' FDT address
5
-
6
-
maintainers:
7
-
- Mike Rapoport <rppt@kernel.org>
8
-
- Changyuan Lyu <changyuanl@google.com>
9
-
10
-
description: |
11
-
Physical address of an FDT blob registered by a KHO user.
12
-
13
-
properties:
14
-
fdt:
15
-
description: |
16
-
physical address (u64) of an FDT blob.
17
-
18
-
required:
19
-
- fdt
20
-
21
-
additionalProperties: false
22
-
23
-
examples:
24
-
- |
25
-
memblock {
26
-
fdt = <0x80cc16 0x1000000>;
27
-
};
+9
Documentation/core-api/kho/index.rst
+9
Documentation/core-api/kho/index.rst
···
31
31
Subsystems participating in KHO can define their own format for state
32
32
serialization and preservation.
33
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
+
34
43
.. _kho_scratch:
35
44
36
45
Scratch Regions
+1
MAINTAINERS
+1
MAINTAINERS
+85
include/linux/kho/abi/kexec_handover.h
+85
include/linux/kho/abi/kexec_handover.h
···
1
+
/* SPDX-License-Identifier: GPL-2.0-only */
2
+
3
+
/*
4
+
* Copyright (C) 2023 Alexander Graf <graf@amazon.com>
5
+
* Copyright (C) 2025 Microsoft Corporation, Mike Rapoport <rppt@kernel.org>
6
+
* Copyright (C) 2025 Google LLC, Changyuan Lyu <changyuanl@google.com>
7
+
* Copyright (C) 2025 Google LLC, Jason Miu <jasonmiu@google.com>
8
+
*/
9
+
10
+
#ifndef _LINUX_KHO_ABI_KEXEC_HANDOVER_H
11
+
#define _LINUX_KHO_ABI_KEXEC_HANDOVER_H
12
+
13
+
/**
14
+
* DOC: Kexec Handover ABI
15
+
*
16
+
* Kexec Handover uses the ABI defined below for passing preserved data from
17
+
* one kernel to the next.
18
+
* The ABI uses Flattened Device Tree (FDT) format. The first kernel creates an
19
+
* FDT which is then passed to the next kernel during a kexec handover.
20
+
*
21
+
* This interface is a contract. Any modification to the FDT structure, node
22
+
* properties, compatible string, or the layout of the data structures
23
+
* referenced here constitutes a breaking change. Such changes require
24
+
* incrementing the version number in KHO_FDT_COMPATIBLE to prevent a new kernel
25
+
* from misinterpreting data from an older kernel. Changes are allowed provided
26
+
* the compatibility version is incremented. However, backward/forward
27
+
* compatibility is only guaranteed for kernels supporting the same ABI version.
28
+
*
29
+
* FDT Structure Overview:
30
+
* The FDT serves as a central registry for physical
31
+
* addresses of preserved data structures and sub-FDTs. The first kernel
32
+
* populates this FDT with references to memory regions and other FDTs that
33
+
* need to persist across the kexec transition. The subsequent kernel then
34
+
* parses this FDT to locate and restore the preserved data.::
35
+
*
36
+
* / {
37
+
* compatible = "kho-v1";
38
+
*
39
+
* preserved-memory-map = <0x...>;
40
+
*
41
+
* <subnode-name-1> {
42
+
* fdt = <0x...>;
43
+
* };
44
+
*
45
+
* <subnode-name-2> {
46
+
* fdt = <0x...>;
47
+
* };
48
+
* ... ...
49
+
* <subnode-name-N> {
50
+
* fdt = <0x...>;
51
+
* };
52
+
* };
53
+
*
54
+
* Root KHO Node (/):
55
+
* - compatible: "kho-v1"
56
+
*
57
+
* Indentifies the overall KHO ABI version.
58
+
*
59
+
* - preserved-memory-map: u64
60
+
*
61
+
* Physical memory address pointing to the root of the
62
+
* preserved memory map data structure.
63
+
*
64
+
* Subnodes (<subnode-name-N>):
65
+
* Subnodes can also be added to the root node to
66
+
* describe other preserved data blobs. The <subnode-name-N>
67
+
* is provided by the subsystem that uses KHO for preserving its
68
+
* data.
69
+
*
70
+
* - fdt: u64
71
+
*
72
+
* Physical address pointing to a subnode FDT blob that is also
73
+
* being preserved.
74
+
*/
75
+
76
+
/* The compatible string for the KHO FDT root node. */
77
+
#define KHO_FDT_COMPATIBLE "kho-v1"
78
+
79
+
/* The FDT property for the preserved memory map. */
80
+
#define KHO_FDT_MEMORY_MAP_PROP_NAME "preserved-memory-map"
81
+
82
+
/* The FDT property for sub-FDTs. */
83
+
#define KHO_FDT_SUB_TREE_PROP_NAME "fdt"
84
+
85
+
#endif /* _LINUX_KHO_ABI_KEXEC_HANDOVER_H */
+9
-10
kernel/liveupdate/kexec_handover.c
+9
-10
kernel/liveupdate/kexec_handover.c
···
15
15
#include <linux/count_zeros.h>
16
16
#include <linux/kexec.h>
17
17
#include <linux/kexec_handover.h>
18
+
#include <linux/kho/abi/kexec_handover.h>
18
19
#include <linux/libfdt.h>
19
20
#include <linux/list.h>
20
21
#include <linux/memblock.h>
···
34
33
#include "../kexec_internal.h"
35
34
#include "kexec_handover_internal.h"
36
35
37
-
#define KHO_FDT_COMPATIBLE "kho-v1"
38
-
#define PROP_PRESERVED_MEMORY_MAP "preserved-memory-map"
39
-
#define PROP_SUB_FDT "fdt"
40
-
36
+
/* The magic token for preserved pages */
41
37
#define KHO_PAGE_MAGIC 0x4b484f50U /* ASCII for 'KHOP' */
42
38
43
39
/*
···
376
378
void *ptr;
377
379
u64 phys;
378
380
379
-
ptr = fdt_getprop_w(kho_out.fdt, 0, PROP_PRESERVED_MEMORY_MAP, NULL);
381
+
ptr = fdt_getprop_w(kho_out.fdt, 0, KHO_FDT_MEMORY_MAP_PROP_NAME, NULL);
380
382
381
383
/* Check and discard previous memory map */
382
384
phys = get_unaligned((u64 *)ptr);
···
464
466
const void *mem_ptr;
465
467
int len;
466
468
467
-
mem_ptr = fdt_getprop(fdt, 0, PROP_PRESERVED_MEMORY_MAP, &len);
469
+
mem_ptr = fdt_getprop(fdt, 0, KHO_FDT_MEMORY_MAP_PROP_NAME, &len);
468
470
if (!mem_ptr || len != sizeof(u64)) {
469
471
pr_err("failed to get preserved memory bitmaps\n");
470
472
return 0;
···
725
727
goto out_pack;
726
728
}
727
729
728
-
err = fdt_setprop(root_fdt, off, PROP_SUB_FDT, &phys, sizeof(phys));
730
+
err = fdt_setprop(root_fdt, off, KHO_FDT_SUB_TREE_PROP_NAME,
731
+
&phys, sizeof(phys));
729
732
if (err < 0)
730
733
goto out_pack;
731
734
···
757
758
const u64 *val;
758
759
int len;
759
760
760
-
val = fdt_getprop(root_fdt, off, PROP_SUB_FDT, &len);
761
+
val = fdt_getprop(root_fdt, off, KHO_FDT_SUB_TREE_PROP_NAME, &len);
761
762
if (!val || len != sizeof(phys_addr_t))
762
763
continue;
763
764
···
1304
1305
if (offset < 0)
1305
1306
return -ENOENT;
1306
1307
1307
-
val = fdt_getprop(fdt, offset, PROP_SUB_FDT, &len);
1308
+
val = fdt_getprop(fdt, offset, KHO_FDT_SUB_TREE_PROP_NAME, &len);
1308
1309
if (!val || len != sizeof(*val))
1309
1310
return -EINVAL;
1310
1311
···
1324
1325
err |= fdt_finish_reservemap(root);
1325
1326
err |= fdt_begin_node(root, "");
1326
1327
err |= fdt_property_string(root, "compatible", KHO_FDT_COMPATIBLE);
1327
-
err |= fdt_property(root, PROP_PRESERVED_MEMORY_MAP, &empty_mem_map,
1328
+
err |= fdt_property(root, KHO_FDT_MEMORY_MAP_PROP_NAME, &empty_mem_map,
1328
1329
sizeof(empty_mem_map));
1329
1330
err |= fdt_end_node(root);
1330
1331
err |= fdt_finish(root);