Documentation/livepatch/livepatch.rst

30   - The kernel probes are the most generic. The code can be redirected by
33   - The function tracer calls the code from a predefined location that is
35     compiler using the '-pg' gcc option.
37   - Livepatching typically needs to redirect the code at the very beginning
46 a live patch is called with the help of a custom ftrace handler. But there are
64 But there are more complex fixes. For example, a patch might change
65 ordering of locking in multiple functions at the same time. Or a patch
74 The aim is to define a so-called consistency model. It attempts to define
79 kpatch:  it uses kGraft's per-task consistency and syscall barrier
83 Patches are applied on a per-task basis, when the task is deemed safe to
84 switch over.  When a patch is enabled, livepatch enters into a
87 sequence occurs when a patch is disabled, except the tasks converge from
95 safe to patch tasks:
99    the task is patched.  In most cases this will patch most or all of
108    a) Patching I/O-bound user tasks which are sleeping on an affected
111    b) Patching CPU-bound user tasks.  If the task is highly CPU-bound
128 Unless we can come up with another way to patch kthreads, architectures
132 The /sys/kernel/livepatch/<patch>/transition file shows whether a patch
133 is in transition.  Only a single patch can be in transition at a given
134 time.  A patch can remain in transition indefinitely, if any of the tasks
135 are stuck in the initial patch state.
138 opposite value to the /sys/kernel/livepatch/<patch>/enabled file while
140 converge back to the original patch state.
144 If a patch is in transition, this file shows 0 to indicate the task is
145 unpatched and 1 to indicate it's patched.  Otherwise, if no patch is in
146 transition, it shows -1.  Any tasks which are blocking the transition
155 /sys/kernel/livepatch/<patch>/force attribute. Writing 1 there clears
160 tasks) and request a clearance from a patch distributor to force the transition.
162 patch, which functions are (un)patched, and which functions the blocking tasks
163 are sleeping in (/proc/<pid>/stack may help here). Removal (rmmod) of patch
166 reference count if a patch module is disabled and enabled in a loop.
174 ---------------------------------------------------------
180    for non-DWARF unwinders, also making sure there's a way for the stack
186    location to switch the kthread's patch state would be at a designated
188    structures are in a well-defined state.
194    There the safe location must be carefully selected on a case-by-case
198    able to use the non-stack-checking parts of the consistency model:
203    b) patching kthreads and idle tasks at their designated patch points.
206    user tasks and waking kthreads to patch them.  But it could still be
215 samples/livepatch/livepatch-sample.c.
227 ------------------
235 The patch contains only functions that are really modified. But they
239 Documentation/livepatch/module-elf-format.rst for more details.
243 -------------
245 The patch is described by several structures that split the information
248   - struct klp_func is defined for each patched function. It describes
253     The function address is found via kallsyms at runtime.
255     Then it includes the address of the new function. It is defined
265   - struct klp_object defines an array of patched functions (struct
271     the patch itself and the relevant functions might be patched
275   - struct klp_patch defines an array of patched objects (struct
279     synchronously. The whole patch is applied only when all patched
283     For more details on how the patch is applied on a per-task basis,
287 5. Livepatch life-cycle
294 exclusive. They have the same result for the given patch but
299 ------------
301 The only reasonable way is to enable the patch when the livepatch kernel
308 the patch cannot get enabled.
312 -------------
321 /sys/kernel/livepatch/<name>. The patch is rejected when any above
348 --------------
350 All enabled patches might get replaced by a cumulative patch that
353 Once the new patch is enabled and the 'transition' finishes then
357 freed when the related function is not modified by the new patch
360 See Documentation/livepatch/cumulative-patches.rst for more details.
364 --------------
371 the previously enabled patch or even the original one. This stage is
377 to '0'. All the functions (struct klp_func) associated with the to-be-disabled
378 patch are removed from the corresponding struct klp_ops. The ftrace handler
386 -------------
391 to a new patch state (patched/unpatched) without being forced it is
402 /sys/kernel/livepatch/<patch>/force attributes allow administrator to affect a
405 See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
413   - Only functions that can be traced could be patched.
423   - Livepatch works reliably only when the dynamic ftrace is located at
428     using -fentry gcc compiler option on x86_64.
437   - Kretprobes using the ftrace framework conflict with the patched
441     the return address. The first user wins. Either the probe or the patch
445   - Kprobes in the original function are ignored when the code is