[PATCH 3/6] kho: docs: combine concepts and FDT documentation

[Mike Rapoport]

On Tue, Jan 20, 2026 at 04:08:56PM +0000, Pratyush Yadav wrote:
> On Mon, Jan 05 2026, Mike Rapoport wrote:
> 
> > From: "Mike Rapoport (Microsoft)" <rppt at kernel.org>
> >
> > Currently index.rst in KHO documentation looks empty and sad as it only
> > contains links to "Kexec Handover Concepts" and "KHO FDT" chapters.
> >
> > Inline contents of these chapters into index.rst to provide a single
> > coherent chapter describing KHO.
> >
> > While on it, drop parts of the KHO FDT description that will be superseded
> > by addition of KHO ABI documentation.
> >
> > Signed-off-by: Mike Rapoport (Microsoft) <rppt at kernel.org>
> [...]
> > diff --git a/Documentation/core-api/kho/index.rst b/Documentation/core-api/kho/index.rst
> > index 0c63b0c5c143..03cd9afbdb2e 100644
> > --- a/Documentation/core-api/kho/index.rst
> > +++ b/Documentation/core-api/kho/index.rst
> > @@ -4,10 +4,73 @@
> >  Kexec Handover Subsystem
> >  ========================
> >  
> > -.. toctree::
> > -   :maxdepth: 1
> > +Overview
> > +========
> 
> I ran a test build and Sphinx complains about:
> 
>     Documentation/admin-guide/mm/kho.rst:10: WARNING: undefined label: 'kho-concepts' [ref.ref]
>     Documentation/admin-guide/mm/kho.rst:31: WARNING: undefined label: 'kho-finalization-phase' [ref.ref]
> 
> I suppose you should add these labels here.

It's already in Andrew's tree:
https://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm.git/commit/?h=mm-nonmm-unstable&id=bc1a060da2a76161ba65f1badc551de15056e398
 
> Otherwise LGTM.
> 
> >  
> > -   concepts
> > -   fdt
> > +Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
> > +regions, which could contain serialized system states, across kexec.
> >  
> > -.. only::  subproject and html
> > +KHO uses :ref:`flattened device tree (FDT) <kho_fdt>` to pass information about
> > +the preserved state from pre-exec kernel to post-kexec kernel and :ref:`scratch
> > +memory regions <kho_scratch>` to ensure integrity of the preserved memory.
> > +
> > +.. _kho_fdt:
> > +
> > +KHO FDT
> > +=======
> > +Every KHO kexec carries a KHO specific flattened device tree (FDT) blob that
> > +describes the preserved state. The FDT includes properties describing preserved
> > +memory regions and nodes that hold subsystem specific state.
> > +
> > +The preserved memory regions contain either serialized subsystem states, or
> > +in-memory data that shall not be touched across kexec. After KHO, subsystems
> > +can retrieve and restore the preserved state from KHO FDT.
> > +
> > +Subsystems participating in KHO can define their own format for state
> > +serialization and preservation.
> > +
> > +.. _kho_scratch:
> > +
> > +Scratch Regions
> > +===============
> > +
> > +To boot into kexec, we need to have a physically contiguous memory range that
> > +contains no handed over memory. Kexec then places the target kernel and initrd
> > +into that region. The new kernel exclusively uses this region for memory
> > +allocations before during boot up to the initialization of the page allocator.
> > +
> > +We guarantee that we always have such regions through the scratch regions: On
> > +first boot KHO allocates several physically contiguous memory regions. Since
> > +after kexec these regions will be used by early memory allocations, there is a
> > +scratch region per NUMA node plus a scratch region to satisfy allocations
> > +requests that do not require particular NUMA node assignment.
> > +By default, size of the scratch region is calculated based on amount of memory
> > +allocated during boot. The ``kho_scratch`` kernel command line option may be
> > +used to explicitly define size of the scratch regions.
> > +The scratch regions are declared as CMA when page allocator is initialized so
> > +that their memory can be used during system lifetime. CMA gives us the
> > +guarantee that no handover pages land in that region, because handover pages
> > +must be at a static physical memory location and CMA enforces that only
> > +movable pages can be located inside.
> > +
> > +After KHO kexec, we ignore the ``kho_scratch`` kernel command line option and
> > +instead reuse the exact same region that was originally allocated. This allows
> > +us to recursively execute any amount of KHO kexecs. Because we used this region
> > +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.
> > +
> > +KHO finalization phase
> > +======================
> > +
> > +To enable user space based kexec file loader, the kernel needs to be able to
> > +provide the FDT that describes the current kernel's state before
> > +performing the actual kexec. The process of generating that FDT is
> > +called serialization. When the FDT is generated, some properties
> > +of the system may become immutable because they are already written down
> > +in the FDT. That state is called the KHO finalization phase.
> > +
> > +See Also
> > +========
> > +
> > +- :doc:`/admin-guide/mm/kho`
> > diff --git a/Documentation/core-api/liveupdate.rst b/Documentation/core-api/liveupdate.rst
> > index 7960eb15a81f..e2aba13494cf 100644
> > --- a/Documentation/core-api/liveupdate.rst
> > +++ b/Documentation/core-api/liveupdate.rst
> > @@ -58,4 +58,4 @@ See Also
> >  ========
> >  
> >  - :doc:`Live Update uAPI </userspace-api/liveupdate>`
> > -- :doc:`/core-api/kho/concepts`
> >
> > +- :doc:`/core-api/kho/index`
> >
> > diff --git a/Documentation/mm/memfd_preservation.rst b/Documentation/mm/memfd_preservation.rst
> > index 66e0fb6d5ef0..a8a5b476afd3 100644
> > --- a/Documentation/mm/memfd_preservation.rst
> > +++ b/Documentation/mm/memfd_preservation.rst
> > @@ -20,4 +20,4 @@ See Also
> >  ========
> >  
> >  - :doc:`/core-api/liveupdate`
> > -- :doc:`/core-api/kho/concepts`
> >
> > +- :doc:`/core-api/kho/index`
> 
> -- 
> Regards,
> Pratyush Yadav

-- 
Sincerely yours,
Mike.