.. SPDX-License-Identifier: GPL-2.0-or-later

====================
Kexec Handover Usage
====================

Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
regions, which could contain serialized system states, across kexec.

This document expects that you are familiar with the base KHO
:ref:`concepts <kho-concepts>`. If you have not read
them yet, please do so now.

Prerequisites
=============

KHO is available when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER``
set to y. Every KHO producer may have its own config option that you
need to enable if you would like to preserve their respective state across
kexec.

To use KHO, please boot the kernel with the ``kho=on`` command line
parameter. You may use ``kho_scratch`` parameter to define size of the
scratch regions. For example ``kho_scratch=16M,512M,256M`` will reserve a
16 MiB low memory scratch area, a 512 MiB global scratch region, and 256 MiB
per NUMA node scratch regions on boot.

Perform a KHO kexec
===================

To perform a KHO kexec, load the target payload and kexec into it. It
is important that you use the ``-s`` parameter to use the in-kernel
kexec file loader, as user space kexec tooling currently has no
support for KHO with the user space based file loader ::

  # kexec -l /path/to/bzImage --initrd /path/to/initrd -s
  # kexec -e

The new kernel will boot up and contain some of the previous kernel's state.

For example, if you used ``reserve_mem`` command line parameter to create
an early memory reservation, the new kernel will have that memory at the
same physical address as the old kernel.

Kexec Metadata
==============

KHO automatically tracks metadata about the kexec chain, passing information
about the previous kernel to the next kernel. This feature helps diagnose
bugs that only reproduce when kexecing from specific kernel versions.

On each KHO kexec, the kernel logs the previous kernel's version and the
number of kexec reboots since the last cold boot::

    [    0.000000] KHO: exec from: 6.19.0-rc4-next-20260107 (count 1)

The metadata includes:

``previous_release``
    The kernel version string (from ``uname -r``) of the kernel that
    initiated the kexec.

``kexec_count``
    The number of kexec boots since the last cold boot. On cold boot,
    this counter starts at 0 and increments with each kexec. This helps
    identify issues that only manifest after multiple consecutive kexec
    reboots.

Use Cases
---------

This metadata is particularly useful for debugging kexec transition bugs,
where a buggy kernel kexecs into a new kernel and the bug manifests only
in the second kernel. Examples of such bugs include:

- Memory corruption from the previous kernel affecting the new kernel
- Incorrect hardware state left by the previous kernel
- Firmware/ACPI state issues that only appear in kexec scenarios

At scale, correlating crashes to the previous kernel version enables
faster root cause analysis when issues only occur in specific kernel
transition scenarios.

debugfs Interfaces
==================

These debugfs interfaces are available when the kernel is compiled with
``CONFIG_KEXEC_HANDOVER_DEBUGFS`` enabled.

Currently KHO creates the following debugfs interfaces. Notice that these
interfaces may change in the future. They will be moved to sysfs once KHO is
stabilized.

``/sys/kernel/debug/kho/out/fdt``
    The kernel exposes the flattened device tree blob that carries its
    current KHO state in this file. Kexec user space tooling can use this
    as input file for the KHO payload image.

``/sys/kernel/debug/kho/out/scratch_len``
    Lengths of KHO scratch regions, which are physically contiguous
    memory regions that will always stay available for future kexec
    allocations. Kexec user space tools can use this file to determine
    where it should place its payload images.

``/sys/kernel/debug/kho/out/scratch_phys``
    Physical locations of KHO scratch regions. Kexec user space tools
    can use this file in conjunction to scratch_phys to determine where
    it should place its payload images.

``/sys/kernel/debug/kho/out/sub_fdts/``
    KHO producers can register their own FDT or another binary blob under
    this directory.

``/sys/kernel/debug/kho/in/fdt``
    When the kernel was booted with Kexec HandOver (KHO),
    the state tree that carries metadata about the previous
    kernel's state is in this file in the format of flattened
    device tree. This file may disappear when all consumers of
    it finished to interpret their metadata.

``/sys/kernel/debug/kho/in/sub_fdts/``
    Similar to ``kho/out/sub_fdts/``, but contains sub blobs
    of KHO producers passed from the old kernel.