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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [day] [month] [year] [list]
Message-ID: <aBvyuKI3i4z_3xSG@archie.me>
Date: Thu, 8 May 2025 06:54:32 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Changyuan Lyu <changyuanl@...gle.com>, akpm@...ux-foundation.org
Cc: anthony.yznaga@...cle.com, arnd@...db.de, ashish.kalra@....com,
	benh@...nel.crashing.org, bp@...en8.de, catalin.marinas@....com,
	corbet@....net, dave.hansen@...ux.intel.com,
	devicetree@...r.kernel.org, dwmw2@...radead.org,
	ebiederm@...ssion.com, graf@...zon.com, hpa@...or.com,
	jgowans@...zon.com, kexec@...ts.infradead.org, krzk@...nel.org,
	linux-arm-kernel@...ts.infradead.org, linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org, linux-mm@...ck.org, luto@...nel.org,
	mark.rutland@....com, mingo@...hat.com, pasha.tatashin@...een.com,
	pbonzini@...hat.com, peterz@...radead.org, ptyadav@...zon.de,
	robh@...nel.org, rostedt@...dmis.org, rppt@...nel.org,
	saravanak@...gle.com, skinsburskii@...ux.microsoft.com,
	tglx@...utronix.de, thomas.lendacky@....com, will@...nel.org,
	x86@...nel.org
Subject: Re: [PATCH v7 17/18] Documentation: add documentation for KHO

On Wed, May 07, 2025 at 10:38:40AM -0700, Changyuan Lyu wrote:
> From: Changyuan Lyu <changyuanl@...gle.com>
> Date: Wed, 7 May 2025 10:14:34 -0700
> Subject: [PATCH] fixup! Documentation: add documentation for KHO
> 
> Signed-off-by: Changyuan Lyu <changyuanl@...gle.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

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)