Re: [PATCH v8 12/12] Documentation: PCI: Add documentation for Live Update

[Bjorn Helgaas <helgaas@kernel.org>]

On Tue, Jul 28, 2026 at 10:10:06PM +0000, David Matlack wrote:
> Add documentation files for the PCI subsystem's participation in Live
> Update.
> 
> These documentation files are generated from the kernel-doc comments
> in the PCI Live Update source code. They describe the File-Lifecycle
> Bound (FLB) API, the device tracking API, and the specific policies

Most uses fully hyphenate this: "File-Lifecycle-Bound" data, object,
etc.

> applied to preserved devices (such as bus number inheritance and bus
> mastering preservation).
> 
> Reviewed-by: Pranjal Shrivastava <praan@google.com>
> Signed-off-by: David Matlack <dmatlack@google.com>

Reviewed-by: Bjorn Helgaas <bhelgaas@google.com>

> ---
>  Documentation/PCI/index.rst           |  1 +
>  Documentation/PCI/liveupdate.rst      | 35 +++++++++++++++++++++++++++
>  Documentation/core-api/liveupdate.rst |  1 +
>  MAINTAINERS                           |  1 +
>  4 files changed, 38 insertions(+)
>  create mode 100644 Documentation/PCI/liveupdate.rst
> 
> diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
> index 5d720d2a415e..23fb737ac969 100644
> --- a/Documentation/PCI/index.rst
> +++ b/Documentation/PCI/index.rst
> @@ -20,3 +20,4 @@ PCI Bus Subsystem
>     controller/index
>     boot-interrupts
>     tph
> +   liveupdate
> diff --git a/Documentation/PCI/liveupdate.rst b/Documentation/PCI/liveupdate.rst
> new file mode 100644
> index 000000000000..96b1d7f5df3a
> --- /dev/null
> +++ b/Documentation/PCI/liveupdate.rst
> @@ -0,0 +1,35 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +===========================
> +PCI Support for Live Update
> +===========================
> +
> +.. kernel-doc:: drivers/pci/liveupdate.c
> +   :doc: PCI Live Update
> +
> +Driver API
> +==========
> +
> +.. kernel-doc:: drivers/pci/liveupdate.c
> +   :export:
> +
> +Internal API
> +============
> +
> +.. kernel-doc:: drivers/pci/liveupdate.c
> +   :internal:
> +
> +Live Update ABI
> +===============
> +
> +.. kernel-doc:: include/linux/kho/abi/pci.h
> +   :doc: PCI File-Lifecycle Bound (FLB) Live Update ABI

Ditto (and in include/linux/kho/abi/pci.h itself).

Trying to understand the FLB concept, I found
kernel/liveupdate/luo_flb.c.  I know that's already merged so this
isn't really the place to ask about it.  But FWIW here are some
questions from this naive reader:

   File-Lifecycle-Bound (FLB) objects provide a mechanism for managing
   global state that is shared across multiple live-updatable files.
   The lifecycle of this shared state is tied to the preservation of
   the files that depend on it.

I understand "global state", but I don't know whether "global" is
relevant here.

I don't know what "shared across live-updatable files" means.  Is the
sharing a fundamental aspect or just a typical use case reflecting the
level the data is for (e.g., bus vs device)?

I'm imagining a *kernel* being "live-updated", i.e., a kernel being
updated while things around it (devices, some user-space things) stay
alive, so I guess "live-updatable files" would be preserved across a
kexec?  I don't think of devices as being "live-updated" since they
themselves aren't being updated; in fact, the whole point is that they
*aren't* updated.

Do these FLB objects appear in a filesystem?  Or are they merely blobs
of data that are preserved across kexec?  I suppose there must be a
mechanism for the new kernel to identify and request one of the
several FLB objects saved by the pre-kexec kernel?

What does "lifecycle is tied to preservation of files" mean?  I
expected to learn about the beginning and end of the object lifetime.

   An FLB represents a global resource, such as the IOMMU core state,
   that is required by multiple file descriptors (e.g., all VFIO fds).

I have the impression that the important thing about FLB is the
lifetime of some data, e.g., something that lasts longer than the
kernel that produced it.

   The preservation of the FLB's state is triggered when the *first*
   file depending on it is preserved. The cleanup of this state
   (unpreserve or finish) is triggered when the *last* file depending
   on it is unpreserved or finished.

Maybe this means .unpreserve() (in pre-kexec kernel) or .finish() (in
new post-kexec kernel) is the end of an FLB object lifetime?

> +.. kernel-doc:: include/linux/kho/abi/pci.h
> +   :internal:
> +
> +See Also
> +========
> +
> + * :doc:`/core-api/liveupdate`
> + * :doc:`/core-api/kho/index`
> diff --git a/Documentation/core-api/liveupdate.rst b/Documentation/core-api/liveupdate.rst
> index b3c689e633c1..2bce2644eba2 100644
> --- a/Documentation/core-api/liveupdate.rst
> +++ b/Documentation/core-api/liveupdate.rst
> @@ -74,3 +74,4 @@ See Also
>  
>  - :doc:`Live Update uAPI </userspace-api/liveupdate>`
>  - :doc:`/core-api/kho/index`
> +- :doc:`PCI </PCI/liveupdate>`
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 08a724b860dc..347c435ca404 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -20833,6 +20833,7 @@ L:	kexec@lists.infradead.org
>  L:	linux-pci@vger.kernel.org
>  S:	Maintained
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/liveupdate/linux.git
> +F:	Documentation/PCI/liveupdate.rst
>  F:	drivers/pci/liveupdate.c
>  F:	drivers/pci/liveupdate.h
>  F:	include/linux/kho/abi/pci.h
> -- 
> 2.55.0.487.gaf234c4eb3-goog
>