Documentation/admin-guide/mm/kho.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/mm/kho.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/mm/kho.rst
Extension
.rst
Size
4703 bytes
Lines
124
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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
---------

Annotation

Implementation Notes