1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3==================== 4Kexec Handover Usage 5==================== 6 7Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory 8regions, which could contain serialized system states, across kexec. 9 10This document expects that you are familiar with the base KHO 11:ref:`concepts <kho-concepts>`. If you have not read 12them yet, please do so now. 13 14Prerequisites 15============= 16 17KHO is available when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER`` 18set to y. Every KHO producer may have its own config option that you 19need to enable if you would like to preserve their respective state across 20kexec. 21 22To use KHO, please boot the kernel with the ``kho=on`` command line 23parameter. You may use ``kho_scratch`` parameter to define size of the 24scratch regions. For example ``kho_scratch=16M,512M,256M`` will reserve a 2516 MiB low memory scratch area, a 512 MiB global scratch region, and 256 MiB 26per NUMA node scratch regions on boot. 27 28Perform a KHO kexec 29=================== 30 31To perform a KHO kexec, load the target payload and kexec into it. It 32is important that you use the ``-s`` parameter to use the in-kernel 33kexec file loader, as user space kexec tooling currently has no 34support for KHO with the user space based file loader :: 35 36 # kexec -l /path/to/bzImage --initrd /path/to/initrd -s 37 # kexec -e 38 39The new kernel will boot up and contain some of the previous kernel's state. 40 41For example, if you used ``reserve_mem`` command line parameter to create 42an early memory reservation, the new kernel will have that memory at the 43same physical address as the old kernel. 44 45debugfs Interfaces 46================== 47 48These debugfs interfaces are available when the kernel is compiled with 49``CONFIG_KEXEC_HANDOVER_DEBUGFS`` enabled. 50 51Currently KHO creates the following debugfs interfaces. Notice that these 52interfaces may change in the future. They will be moved to sysfs once KHO is 53stabilized. 54 55``/sys/kernel/debug/kho/out/fdt`` 56 The kernel exposes the flattened device tree blob that carries its 57 current KHO state in this file. Kexec user space tooling can use this 58 as input file for the KHO payload image. 59 60``/sys/kernel/debug/kho/out/scratch_len`` 61 Lengths of KHO scratch regions, which are physically contiguous 62 memory regions that will always stay available for future kexec 63 allocations. Kexec user space tools can use this file to determine 64 where it should place its payload images. 65 66``/sys/kernel/debug/kho/out/scratch_phys`` 67 Physical locations of KHO scratch regions. Kexec user space tools 68 can use this file in conjunction to scratch_phys to determine where 69 it should place its payload images. 70 71``/sys/kernel/debug/kho/out/sub_fdts/`` 72 KHO producers can register their own FDT or another binary blob under 73 this directory. 74 75``/sys/kernel/debug/kho/in/fdt`` 76 When the kernel was booted with Kexec HandOver (KHO), 77 the state tree that carries metadata about the previous 78 kernel's state is in this file in the format of flattened 79 device tree. This file may disappear when all consumers of 80 it finished to interpret their metadata. 81 82``/sys/kernel/debug/kho/in/sub_fdts/`` 83 Similar to ``kho/out/sub_fdts/``, but contains sub FDT blobs 84 of KHO producers passed from the old kernel. 85