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

[Bagas Sanjaya]

On Thu, May 01, 2025 at 03:54:24PM -0700, Changyuan Lyu wrote:
> +This document expects that you are familiar with the base KHO
> +:ref:`concepts <concepts>`. If you have not read
The reference label is generic and can collide with future patches.
It should've been disambiguated as kho_concepts instead.
> +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
when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER`` set to y.
> +need to enable if you would like to preserve their respective state across
> +kexec.
> +
> <snipped>...
> +First, before you perform a KHO kexec, you need to move the system into
> +the :ref:`KHO finalization phase <finalization_phase>` ::

kho_finalization_phase to disambiguate label.

> +Next, 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 Image --initrd=initrd -s
> +  # kexec -e

Use full paths to kernel and initramfs 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.

"Length of KHO scratch region, which is a physically contiguous memory regions
that will always 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 location of KHO scratch region. Kexec user space tools can use this
file in conjunction to scratch_phys to determine where it should place its
payload images."

> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +.. _concepts:

The label can be ambiguous. It should've been _kho_concepts instead.

> +.. _finalization_phase:

The label should be _kho_finalization_phase.

> +Generally, A KHO user serialize its state into its own FDT and instructs
"Generally, a KHO user ..."
> +KHO to preserve the underlying memory, such that after kexec, the new kernel
> +can recover its state from the preserved FDT.
> +

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/linux-arm-kernel/attachments/20250506/859653f1/attachment.sig>