Documentation/livepatch/livepatch.rst

Source file repositories/reference/linux-study-clean/Documentation/livepatch/livepatch.rst

File Facts

System
Linux kernel
Corpus path
Documentation/livepatch/livepatch.rst
Extension
.rst
Size
19134 bytes
Lines
449
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: exported/initcall integration point
Status
integration implementation candidate

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

in the module_init() callback. There are two main reasons:

First, only the module has an easy access to the related struct klp_patch.

Second, the error code might be used to refuse loading the module when
the patch cannot get enabled.


5.2. Enabling
-------------

The livepatch gets enabled by calling klp_enable_patch() from
the module_init() callback. The system will start using the new
implementation of the patched functions at this stage.

First, the addresses of the patched functions are found according to their
names. The special relocations, mentioned in the section "New functions",
are applied. The relevant entries are created under
/sys/kernel/livepatch/<name>. The patch is rejected when any above
operation fails.

Second, livepatch enters into a transition state where tasks are converging
to the patched state. If an original function is patched for the first
time, a function specific struct klp_ops is created and an universal
ftrace handler is registered\ [#]_. This stage is indicated by a value of '1'
in /sys/kernel/livepatch/<name>/transition. For more information about
this process, see the "Consistency model" section.

Finally, once all tasks have been patched, the 'transition' value changes
to '0'.

.. [#]

    Note that functions might be patched multiple times. The ftrace handler
    is registered only once for a given function. Further patches just add
    an entry to the list (see field `func_stack`) of the struct klp_ops.
    The right implementation is selected by the ftrace handler, see
    the "Consistency model" section.

    That said, it is highly recommended to use cumulative livepatches
    because they help keeping the consistency of all changes. In this case,
    functions might be patched two times only during the transition period.


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.

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


5.4. Disabling
--------------

Enabled patches might get disabled by writing '0' to
/sys/kernel/livepatch/<name>/enabled.

First, livepatch enters into a transition state where tasks are converging
to the unpatched state. The system starts using either the code from
the previously enabled patch or even the original one. This stage is
indicated by a value of '1' in /sys/kernel/livepatch/<name>/transition.

Annotation

Implementation Notes