1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3=======
4KHO FDT
5=======
6
7KHO uses the flattened device tree (FDT) container format and libfdt
8library to create and parse the data that is passed between the
9kernels. The properties in KHO FDT are stored in native format.
10It includes the physical address of an in-memory structure describing
11all preserved memory regions, as well as physical addresses of KHO users'
12own FDTs. Interpreting those sub FDTs is the responsibility of KHO users.
13
14KHO nodes and properties
15========================
16
17Property ``preserved-memory-map``
18---------------------------------
19
20KHO saves a special property named ``preserved-memory-map`` under the root node.
21This node contains the physical address of an in-memory structure for KHO to
22preserve memory regions across kexec.
23
24Property ``compatible``
25-----------------------
26
27The ``compatible`` property determines compatibility between the kernel
28that created the KHO FDT and the kernel that attempts to load it.
29If the kernel that loads the KHO FDT is not compatible with it, the entire
30KHO process will be bypassed.
31
32Property ``fdt``
33----------------
34
35Generally, a KHO user serialize its state into its own FDT and instructs
36KHO to preserve the underlying memory, such that after kexec, the new kernel
37can recover its state from the preserved FDT.
38
39A KHO user thus can create a node in KHO root tree and save the physical address
40of its own FDT in that node's property ``fdt`` .
41
42Examples
43========
44
45The following example demonstrates KHO FDT that preserves two memory
46regions 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
60where the ``memblock`` node contains an FDT that is requested by the
61subsystem memblock for preservation. The FDT contains the following
62serialized 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  };
81