Documentation/livepatch/livepatch.rst

17 heavy load during peak usage. In addition to keeping systems up and running,
20 functions without a system reboot.
26 There are multiple mechanisms in the Linux kernel that are directly related
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
39     are in any way modified.
53 Functions are there for a reason. They take some input parameters, acquire or
54 release locks, read, process, and even write some data in a defined way,
55 have return values. In other words, each function has a defined semantic.
57 Many fixes do not change the semantic of the modified functions. For
61 the same way to the rest of the system. In this case, the functions might
65 ordering of locking in multiple functions at the same time. Or a patch
67 all the relevant functions. In this case, the affected unit
69 the functions at the same time. Also the switch must happen only
71 or no data are stored in the modified structures at the moment.
73 The theory about how to apply functions a safe way is rather complex.
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
86 Usually this transition state can complete in a few seconds.  The same
98    tasks.  If no affected functions are on the stack of a given task,
99    the task is patched.  In most cases this will patch most or all of
106    user space IRQ, or a signal.  It's useful in the following cases:
108    a) Patching I/O-bound user tasks which are sleeping on an affected
109       function.  In this case you have to send SIGSTOP and SIGCONT to
111    b) Patching CPU-bound user tasks.  If the task is highly CPU-bound
116    instead have a klp_update_patch_state() call in the idle loop which
124 returns. In this case you would have to signal the tasks. This
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.
139 the transition is in progress.  Then all the tasks will attempt to
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
150 actually delivered (there is no data in signal pending structures). Tasks are
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
165 guaranteed there is no task sleeping in such module. It implies unbounded
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
184    klp_update_patch_state() in a safe location.  Kthreads are typically
185    in an infinite loop which does some action repeatedly.  The safe
187    point in the loop where there are no locks taken and all data
188    structures are in a well-defined state.
191    API.  These kthreads process independent actions in a generic loop.
194    There the safe location must be carefully selected on a case-by-case
197    In that case, arches without HAVE_RELIABLE_STACKTRACE would still be
198    able to use the non-stack-checking parts of the consistency model:
215 samples/livepatch/livepatch-sample.c.
217 The module includes a new implementation of functions that we want
218 to replace. In addition, it defines some structures describing the
222 livepatch module is removed. All this is explained in more details in
226 4.1. New functions
227 ------------------
229 New versions of functions are typically just copied from the original
231 can be distinguished from the original ones, e.g. in a backtrace. Also
235 The patch contains only functions that are really modified. But they
236 might want to access functions or data from the original source file
238 relocation section in the generated livepatch module, see
239 Documentation/livepatch/module-elf-format.rst for more details.
243 -------------
248   - struct klp_func is defined for each patched function. It describes
257     function is typically defined in the same source file.
259     As an optional parameter, the symbol position in the kallsyms database can
260     be used to disambiguate functions of the same name. This is not the
261     absolute position in the database, but rather the order it has been found
265   - struct klp_object defines an array of patched functions (struct
266     klp_func) in the same object. Where the object is either vmlinux
269     The structure helps to group and handle functions for each object
271     the patch itself and the relevant functions might be patched
275   - struct klp_patch defines an array of patched objects (struct
278     This structure handles all patched functions consistently and eventually,
283     For more details on how the patch is applied on a per-task basis,
287 5. Livepatch life-cycle
299 ------------
303 in the module_init() callback. There are two main reasons:
312 -------------
316 implementation of the patched functions at this stage.
318 First, the addresses of the patched functions are found according to their
319 names. The special relocations, mentioned in the section "New functions",
328 in /sys/kernel/livepatch/<name>/transition. For more information about
336     Note that functions might be patched multiple times. The ftrace handler
343     because they help keeping the consistency of all changes. In this case,
344     functions might be patched two times only during the transition period.
348 --------------
354 all the functions (struct klp_func) associated with the replaced
360 See Documentation/livepatch/cumulative-patches.rst for more details.
364 --------------
372 indicated by a value of '1' in /sys/kernel/livepatch/<name>/transition.
377 to '0'. All the functions (struct klp_func) associated with the to-be-disabled
386 -------------
388 Module removal is only safe when there are no users of functions provided
392 guaranteed that no task sleeps or runs in the old code.
405 See Documentation/ABI/testing/sysfs-kernel-livepatch for more details.
413   - Only functions that can be traced could be patched.
415     Livepatch is based on the dynamic ftrace. In particular, functions
417     patched. Otherwise, the code would end up in an infinite loop. A
418     potential mistake is prevented by marking the problematic functions
423   - Livepatch works reliably only when the dynamic ftrace is located at
427     parameters are modified in any way. For example, livepatch requires
428     using -fentry gcc compiler option on x86_64.
437   - Kretprobes using the ftrace framework conflict with the patched
438     functions.
442     is rejected when the handler is already in use by the other.
445   - Kprobes in the original function are ignored when the code is
448     There is a work in progress to add warnings about this situation.