documentation: was: Re: [PATCH v7 for-next 3/8] livepatch: Implement replace set for scoped atomic replace

[Petr Mladek <pmladek@suse.com>]

On Tue 2026-08-25 19:46:36, Yafang Shao wrote:
> The current bool replace flag is too coarse: it is either all or
> nothing. A livepatch with .replace=true replaces ALL existing
> livepatches, which is safe but inflexible. There is no way to have
> multiple independent livepatch sets coexist on the same system.
> 
> Replace it with a more flexible model using two new fields in
> struct klp_patch:
> 
> - provides: an unsigned int id identifying the patch replace set.
>   By default (provides=0), any livepatch replaces any other livepatch.

What is the "replace set"? The term is used few times in
the commit message, documentation, comments but it is not
defined anywhere.

IMHO, the term is a bit misleding, both "replace" and "set" parts.

1. My understanding is that "provides" is an "id" which is connected
   by a set of objects, and functions which are modified (replaced?)
   by the livepatch? Here the "replace" would mean "replaced
   functionality".

   But the provides id also covers the related callbacks, shadow
   variables and livepatch states. Here the word "replace" does
   not fit.


2. We are talking about "atomic replace". Here one livepatch replaces
   one or more other livepatches. Here the word "replace" would mean
   "replace livepatch(es)". But does the livepach replace one or more
   livepatch sets?

Do we need this term at all?

IMHO, we could live better without it, for example:

<proposal>
Subject: livepatch: Implement provides and obsoletes for scoped atomic
replace

- provides: an usinged int id identifying the changes made by
  the related livepatch. Where the changes are a set
  of modified objects, functions, and used callbacks,
  shadow variable ids, and state ids.
</proposal>

> - obsoletes: an optional array of unsigned int ids specifying
>   additional provides ids to be replaced. This allows a new patch
>   to explicitly obsolete patches from different replace sets.

We should mention here the special meanting of the "0" id.
It enforces the most secure mode when only one livepatch
can be enabled at any time.

Also it is important to explain here also the compatibility
rules. They are important part of the design.

This approach allows to have more livepatches installed in parallel
but only when they are not conflicting. They would conflict if
they attempt to livepatch the same function or use livepatch states
with the same ID.

> A new livepatch atomically replaces any existing livepatch whose
> provides id matches either:
>   1. The new patch provides id (same replace set), or
>   2. Any id in the new patch obsoletes list
> 
> The klp-build script is updated with -p/--provides and -r/--obsoletes
> options. The obsoletes list automatically includes the provides id
> and deduplicates entries. Input validation rejects malformed values
> at build time.
> 
> Two helper functions are introduced:
> - klp_patch_replaceable(): checks if an new patch will replace the old
>   patch
> - klp_has_function_conflict(): rejects loading a livepatch that would
>   modify a function already patched by a livepatch with a different
>   provides id.

I agree with Josh. There is no need to mention these two new
functions in the commit message.

> Suggested-by: Song Liu <song@kernel.org>
> Suggested-by: Joe Lawrence <joe.lawrence@redhat.com>
> Suggested-by: Petr Mladek <pmladek@suse.com>
> Co-developed-by: Petr Mladek <pmladek@suse.com>
> Signed-off-by: Petr Mladek <pmladek@suse.com>
> Signed-off-by: Yafang Shao <laoar.shao@gmail.com>
> Acked-by: Song Liu <song@kernel.org>
> ---
>  .../ABI/testing/sysfs-kernel-livepatch        | 22 ++++-
>  .../livepatch/cumulative-patches.rst          | 93 +++++++++++++------
>  Documentation/livepatch/livepatch.rst         | 23 +++--
>  include/linux/livepatch.h                     |  7 +-
>  kernel/livepatch/core.c                       | 69 ++++++++++++--
>  kernel/livepatch/core.h                       |  1 +
>  kernel/livepatch/state.c                      | 57 ++++++++++--
>  kernel/livepatch/transition.c                 | 11 ++-
>  scripts/livepatch/init.c                      | 71 +++++++++++++-
>  scripts/livepatch/klp-build                   | 78 ++++++++++++++--
>  10 files changed, 351 insertions(+), 81 deletions(-)
> 
> diff --git a/Documentation/ABI/testing/sysfs-kernel-livepatch b/Documentation/ABI/testing/sysfs-kernel-livepatch
> index 3c3f36b32b57..2588f676deb1 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-livepatch
> +++ b/Documentation/ABI/testing/sysfs-kernel-livepatch
> @@ -47,13 +47,25 @@ Description:
>  		disabled when the feature is used. See
>  		Documentation/livepatch/livepatch.rst for more information.
>  
> -What:		/sys/kernel/livepatch/<patch>/replace
> -Date:		Jun 2024
> -KernelVersion:	6.11.0
> +What:		/sys/kernel/livepatch/<patch>/provides
> +Date:		Jun 2026
> +KernelVersion:	7.4.0
>  Contact:	live-patching@vger.kernel.org
>  Description:
> -		An attribute which indicates whether the patch supports
> -		atomic-replace.
> +		An attribute to show the provides id of this livepatch.
> +		Only one active livepatch per provides id is allowed.

This sounds like you could not load another livepatch with the same
id. But you actually could. We should make it clear that it would
replace the existing one. I suggest something like:

<proposal>
		An attribute to show the provides id of this livepatch.
		Livepatches with the same provides id replace each other.
</proposal

> +
> +What:		/sys/kernel/livepatch/<patch>/obsoletes
> +Date:		Jun 2026
> +KernelVersion:	7.4.0
> +Contact:	live-patching@vger.kernel.org
> +Description:
> +		An attribute to show the obsoletes ids of this livepatch.
> +		The obsoletes ids are a comma-separated list of provides
> +		ids that this patch obsoletes. When this livepatch is
> +		loaded, any existing livepatch whose provides id matches
> +		either this patch's provides id or any id in the obsoletes
> +		list will be atomically replaced.
>  
>  What:		/sys/kernel/livepatch/<patch>/stack_order
>  Date:		Jan 2025
> diff --git a/Documentation/livepatch/cumulative-patches.rst b/Documentation/livepatch/cumulative-patches.rst
> index 1931f318976a..04352ae3f0d0 100644
> --- a/Documentation/livepatch/cumulative-patches.rst
> +++ b/Documentation/livepatch/cumulative-patches.rst
> @@ -2,33 +2,66 @@
>  Atomic Replace & Cumulative Patches
>  ===================================
>  
> -There might be dependencies between livepatches. If multiple patches need
> -to do different changes to the same function(s) then we need to define
> -an order in which the patches will be installed. And function implementations
> -from any newer livepatch must be done on top of the older ones.
> -
> -This might become a maintenance nightmare. Especially when more patches
> -modified the same function in different ways.
> -
> -An elegant solution comes with the feature called "Atomic Replace". It allows
> -creation of so called "Cumulative Patches". They include all wanted changes
> -from all older livepatches and completely replace them in one transition.
> -
> -Usage
> ------
> -
> -The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
> -for example::
> -
> -	static struct klp_patch patch = {
> -		.mod = THIS_MODULE,
> -		.objs = objs,
> -		.replace = true,
> -	};
> -
> -All processes are then migrated to use the code only from the new patch.
> -Once the transition is finished, all older patches are automatically
> -disabled.
> +Livepatches are used to fix kernel bugs. New fixes need to be added over time.
> +The fixes might be independent, but they might also depend on each other. This
> +brings a challenge of how to keep the livepatched system safe and consistent.
> +
> +Part of the solution is the "Atomic Replace" feature, which allows the kernel to
> +atomically replace an existing livepatch with another one. These newer
> +livepatches are designed as "Cumulative Patches". They include all wanted
> +changes from all older livepatches and completely replace them in one
> +transition.
> +
> +The second part of the solution is the newly introduced ``provides`` and

s/is the newly introduced/are/

"the newly introduced" would fit into the commit message but not into
the documentation. The fields are new _now_. But the documentation
should make sense as long as the feature is there.

> +``obsoletes`` fields in ``struct klp_patch``, which allow the installation of
> +multiple livepatches in parallel. A livepatch will atomically replace any
> +already installed livepatch whose ``provides`` id matches either the new
> +patch's ``provides`` id or any id in the new patch's ``obsoletes`` list.
> +This might be used to fix independent problems separately, for example, the
> +livepatches might be prepared by separate teams focusing on particular
> +functionality or a subsystem.
> +
> +It should be emphasized that the preferred and most secure way is to always use
> +the default ``provides = 0``. In this mode, any livepatch replaces any other
> +livepatch, preventing any unexpected interactions between incompatible
> +livepatches.

We should make it clear here that '0' is really special. It basically
provides and obsoletes livepatches with any other IDs.

> +Provides and Obsoletes
> +-----------------------
> +
> +The ``provides`` field in ``struct klp_patch`` is an unsigned integer that
> +identifies the livepatch's replace set. By default, it is 0.

I would get rid of the "replace set" term.

> +The ``obsoletes`` field is an optional array of unsigned integers that
> +specifies additional ``provides`` ids to be replaced when this patch is
> +loaded.

The above part is good.

> By default, it includes the patch's own ``provides`` id, ensuring
> +that a new patch always replaces any existing patch with the same
> +``provides`` id.

This sentence is confusing. My undestanding is that we do not need
to mention patch's own provides id in the obsoletes array. I would
just omit this sentence.

> +
> +For example::
> +
> +        static struct klp_patch patch = {
> +                .mod = THIS_MODULE,
> +                .objs = objs,
> +                .provides = 0,
> +        };
> +
> +Any ``provides`` value might be associated with a set of livepatched symbols,
> +callbacks, shadow variables, and state IDs. By definition, there can only ever
> +be one active livepatch for a given ``provides`` id.
> +
> +On the contrary, livepatches with a different ``provides`` id must not
> +modify the same function, or use the state with the same ID. Any attempt to
> +load an incompatible livepatch will be rejected by the kernel.
> +
> +Atomic Replace
> +--------------
> +
> +A livepatch with a given ``provides`` id is replaced by another livepatch
> +with the same ``provides`` id, or whose ``obsoletes`` list includes that id.
> +All processes are migrated to use the code only from the new patch. Once
> +the transition is finished, the older patch is disabled. Patches with a
> +different ``provides`` id are not affected and remain active.
>  
>  Ftrace handlers are transparently removed from functions that are no
>  longer modified by the new cumulative patch.
> @@ -64,7 +97,11 @@ Limitations:
>    - Once the operation finishes, there is no straightforward way
>      to reverse it and restore the replaced patches atomically.
>  
> -    A good practice is to set .replace flag in any released livepatch.
> +    A good practice is to use only one (default) ``provides`` id. It
> +    makes sure that there always will be only one enabled livepatch
> +    on the system. The consistency model will ensure a safe update
> +    between two versions. It prevents potential problems with installing
> +    two livepatches doing incompatible functional changes.
>      Then re-adding an older livepatch is equivalent to downgrading
>      to that patch. This is safe as long as the livepatches do _not_ do
>      extra modifications in (un)patching callbacks or in the module_init()
> diff --git a/Documentation/livepatch/livepatch.rst b/Documentation/livepatch/livepatch.rst
> index acb90164929e..73635f9ddd91 100644
> --- a/Documentation/livepatch/livepatch.rst
> +++ b/Documentation/livepatch/livepatch.rst
> @@ -347,15 +347,20 @@ to '0'.
>  5.3. Replacing
>  --------------
>  
> -All enabled patches might get replaced by a cumulative patch that
> -has the .replace flag set.
> -
> -Once the new patch is enabled and the 'transition' finishes then
> -all the functions (struct klp_func) associated with the replaced
> -patches are removed from the corresponding struct klp_ops. Also
> -the ftrace handler is unregistered and the struct klp_ops is
> -freed when the related function is not modified by the new patch
> -and func_stack list becomes empty.
> +There can be only one active livepatch for a given ``provides`` id.
> +A new livepatch atomically replaces any existing livepatch whose
> +``provides`` id matches either the new patch's ``provides`` id or
> +any id in the new patch's ``obsoletes`` list.
> +
> +Once the transition is complete, all functions (``struct klp_func``)
> +associated with the matching replaced patches are removed from the
> +corresponding ``struct klp_ops``. If a function is no longer modified by
> +the new patch and its ``func_stack`` list becomes empty, the ftrace
> +handler is unregistered and the ``struct klp_ops`` is freed.
> +
> +Patches with a different ``provides`` id are not affected by this
> +process and remain active. This allows for the independent management
> +and stacking of multiple, non-conflicting livepatch sets.

I would avoid the word "stacking". The livepatch code has this term
connected with func->stack_node and ops->func_stack. It allows to
associate more struct klp_func entries with the same ftrace handler.
The last or the last-but-one entry is then used depending on
the state of the transition.

By other words, the stacking is used in the livepatching code when
two livepatches modify the same function. But such livepatches are
_conflicting_.

By other words, the  sentence: "allows independent.*stacking of multiple,
non-conflicting livepatch sets" does not make sense.

>  See Documentation/livepatch/cumulative-patches.rst for more details.

Best Regards,
Petr