1.. SPDX-License-Identifier: GPL-2.0-or-later 2.. _kho-concepts: 3 4======================= 5Kexec Handover Concepts 6======================= 7 8Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory 9regions, which could contain serialized system states, across kexec. 10 11It introduces multiple concepts: 12 13KHO FDT 14======= 15 16Every KHO kexec carries a KHO specific flattened device tree (FDT) blob 17that describes preserved memory regions. These regions contain either 18serialized subsystem states, or in-memory data that shall not be touched 19across kexec. After KHO, subsystems can retrieve and restore preserved 20memory regions from KHO FDT. 21 22KHO only uses the FDT container format and libfdt library, but does not 23adhere to the same property semantics that normal device trees do: Properties 24are passed in native endianness and standardized properties like ``regs`` and 25``ranges`` do not exist, hence there are no ``#...-cells`` properties. 26 27KHO is still under development. The FDT schema is unstable and would change 28in the future. 29 30Scratch Regions 31=============== 32 33To boot into kexec, we need to have a physically contiguous memory range that 34contains no handed over memory. Kexec then places the target kernel and initrd 35into that region. The new kernel exclusively uses this region for memory 36allocations before during boot up to the initialization of the page allocator. 37 38We guarantee that we always have such regions through the scratch regions: On 39first boot KHO allocates several physically contiguous memory regions. Since 40after kexec these regions will be used by early memory allocations, there is a 41scratch region per NUMA node plus a scratch region to satisfy allocations 42requests that do not require particular NUMA node assignment. 43By default, size of the scratch region is calculated based on amount of memory 44allocated during boot. The ``kho_scratch`` kernel command line option may be 45used to explicitly define size of the scratch regions. 46The scratch regions are declared as CMA when page allocator is initialized so 47that their memory can be used during system lifetime. CMA gives us the 48guarantee that no handover pages land in that region, because handover pages 49must be at a static physical memory location and CMA enforces that only 50movable pages can be located inside. 51 52After KHO kexec, we ignore the ``kho_scratch`` kernel command line option and 53instead reuse the exact same region that was originally allocated. This allows 54us to recursively execute any amount of KHO kexecs. Because we used this region 55for boot memory allocations and as target memory for kexec blobs, some parts 56of that memory region may be reserved. These reservations are irrelevant for 57the next KHO, because kexec can overwrite even the original kernel. 58 59.. _kho-finalization-phase: 60 61KHO finalization phase 62====================== 63 64To enable user space based kexec file loader, the kernel needs to be able to 65provide the FDT that describes the current kernel's state before 66performing the actual kexec. The process of generating that FDT is 67called serialization. When the FDT is generated, some properties 68of the system may become immutable because they are already written down 69in the FDT. That state is called the KHO finalization phase. 70 71Public API 72========== 73.. kernel-doc:: kernel/kexec_handover.c 74 :export: 75