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

Bagas Sanjaya
2025-05-07T23:54:36Z

[-- Attachment #1: Type: text/plain, Size: 5278 bytes --]

On Wed, May 07, 2025 at 10:38:40AM -0700, Changyuan Lyu wrote:
> From: Changyuan Lyu <changyuanl@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@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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]