Re: documentation: was: Re: [PATCH v7 for-next 3/8] livepatch: Implement replace set for scoped atomic replace
flat view
From: Yafang Shao <hidden>
Date: 2026-09-02 09:51:06
On Wed, Sep 2, 2026 at 3:34 PM Petr Mladek [off-list ref] wrote:
On Tue 2026-08-25 19:46:36, Yafang Shao wrote:quoted
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>
Thanks for your suggestion. I will update it.
quoted
- 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.
Ah, if you prefer to make '0' a special case, I will implement it that way. This brings up the question you mentioned in another email: should we allow loading another ID when livepatch ID 0 is already enabled? It seems the answer is to reject the other ID.
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.quoted
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.
I will update it.
quoted
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 <redacted> 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
Thanks for your suggestion. I will update it.
quoted
+ +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 2025diff --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`` ands/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.
I will update it.
quoted
+``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.quoted
+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.
I will update it.
quoted
+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.quoted
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.
I will update it.
quoted
+ +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.
Thanks for your detailed explanation. I will update it. -- Regards Yafang