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)" <[email protected]> > > > > 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) <[email protected]> > [...] > > 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.
