[PATCH v7 17/18] Documentation: add documentation for KHO

[Bagas Sanjaya]

On Wed, May 07, 2025 at 10:38:40AM -0700, Changyuan Lyu wrote:
> From: Changyuan Lyu <changyuanl at google.com>
> Date: Wed, 7 May 2025 10:14:34 -0700
> Subject: [PATCH] fixup! Documentation: add documentation for KHO
> 
> Signed-off-by: Changyuan Lyu <changyuanl at google.com>
> ---
>  Documentation/admin-guide/mm/kho.rst    | 29 ++++++++++---------------
>  Documentation/core-api/kho/concepts.rst |  4 ++--
>  Documentation/core-api/kho/fdt.rst      |  2 +-
>  3 files changed, 15 insertions(+), 20 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/kho.rst b/Documentation/admin-guide/mm/kho.rst
> index c64aa7aadb300..6dc18ed4b8861 100644
> --- a/Documentation/admin-guide/mm/kho.rst
> +++ b/Documentation/admin-guide/mm/kho.rst
> @@ -8,14 +8,14 @@ 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 <concepts>`. If you have not read
> +:ref:`concepts <kho-concepts>`. If you have not read
>  them yet, please do so now.
> 
>  Prerequisites
>  =============
> 
> -KHO is available when the ``CONFIG_KEXEC_HANDOVER`` config option is set to y
> -at compile time. Every KHO producer may have its own config option that you
> +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.
> 
> @@ -29,7 +29,7 @@ Perform a KHO kexec
>  ===================
> 
>  First, before you perform a KHO kexec, you need to move the system into
> -the :ref:`KHO finalization phase <finalization_phase>` ::
> +the :ref:`KHO finalization phase <kho-finalization-phase>` ::
> 
>    $ echo 1 > /sys/kernel/debug/kho/out/finalize
> 
> @@ -43,7 +43,7 @@ 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 Image --initrd=initrd -s
> +  # kexec -l /path/to/Image --initrd /path/to/initrd -s
>    # kexec -e
> 
>  The new kernel will boot up and contain some of the previous kernel's state.
> @@ -89,20 +89,15 @@ stabilized.
>      as input file for the KHO payload image.
> 
>  ``/sys/kernel/debug/kho/out/scratch_len``
> -    To support continuous KHO kexecs, we need to reserve
> -    physically contiguous memory regions that will always stay
> -    available for future kexec allocations. This file describes
> -    the length of these memory regions. Kexec user space tooling
> -    can use this to determine where it should place its payload
> -    images.
> +    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``
> -    To support continuous KHO kexecs, we need to reserve
> -    physically contiguous memory regions that will always stay
> -    available for future kexec allocations. This file describes
> -    the physical location of these memory regions. Kexec user space
> -    tooling can use this to determine where it should place its
> -    payload images.
> +    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/``
>      In the KHO finalization phase, KHO producers register their own
> diff --git a/Documentation/core-api/kho/concepts.rst b/Documentation/core-api/kho/concepts.rst
> index f1826ac10da75..36d5c05cfb307 100644
> --- a/Documentation/core-api/kho/concepts.rst
> +++ b/Documentation/core-api/kho/concepts.rst
> @@ -1,5 +1,5 @@
>  .. SPDX-License-Identifier: GPL-2.0-or-later
> -.. _concepts:
> +.. _kho-concepts:
> 
>  =======================
>  Kexec Handover Concepts
> @@ -56,7 +56,7 @@ for boot memory allocations and as target memory for kexec blobs, some parts
>  of that memory region may be reserved. These reservations are irrelevant for
>  the next KHO, because kexec can overwrite even the original kernel.
> 
> -.. _finalization_phase:
> +.. _kho-finalization-phase:
> 
>  KHO finalization phase
>  ======================
> diff --git a/Documentation/core-api/kho/fdt.rst b/Documentation/core-api/kho/fdt.rst
> index 4a5d53c670d4b..62505285d60d6 100644
> --- a/Documentation/core-api/kho/fdt.rst
> +++ b/Documentation/core-api/kho/fdt.rst
> @@ -32,7 +32,7 @@ KHO process will be bypassed.
>  Property ``fdt``
>  ----------------
> 
> -Generally, A KHO user serialize its state into its own FDT and instructs
> +Generally, a KHO user serialize its state into its own FDT and instructs
>  KHO to preserve the underlying memory, such that after kexec, the new kernel
>  can recover its state from the preserved FDT.
> 

Looks good.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/kexec/attachments/20250508/9ee99705/attachment.sig>