diff options
| author | Petr Mladek <pmladek@suse.com> | 2019-05-03 16:30:24 +0200 |
|---|---|---|
| committer | Jonathan Corbet <corbet@lwn.net> | 2019-05-08 00:06:28 +0200 |
| commit | d9defe448f4c7b88ca2ae636a321ef8970fa718d (patch) | |
| tree | 7de5bc4dd12f5d1544f1985f96c3717a2be22ee9 /Documentation/livepatch/callbacks.rst | |
| parent | docs: livepatch: convert docs to ReST and rename to *.rst (diff) | |
| download | linux-d9defe448f4c7b88ca2ae636a321ef8970fa718d.tar.xz linux-d9defe448f4c7b88ca2ae636a321ef8970fa718d.zip | |
docs/livepatch: Unify style of livepatch documentation in the ReST format
Make the structure of "Livepatch module Elf format" document similar
to the main "Livepatch" document.
Also make the structure of "(Un)patching Callbacks" document similar
to the "Shadow Variables" document.
It fixes the most visible inconsistencies of the documentation
generated from the ReST format.
Signed-off-by: Petr Mladek <pmladek@suse.com>
Acked-by: Joe Lawrence <joe.lawrence@redhat.com>
Acked-by: Josh Poimboeuf <jpoimboe@redhat.com>
Acked-by: Miroslav Benes <mbenes@suse.cz>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Kamalesh Babulal <kamalesh@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'Documentation/livepatch/callbacks.rst')
| -rw-r--r-- | Documentation/livepatch/callbacks.rst | 33 |
1 files changed, 18 insertions, 15 deletions
diff --git a/Documentation/livepatch/callbacks.rst b/Documentation/livepatch/callbacks.rst index d76d1f0d9fcf..470944aa8658 100644 --- a/Documentation/livepatch/callbacks.rst +++ b/Documentation/livepatch/callbacks.rst @@ -4,7 +4,7 @@ Livepatch (un)patch-callbacks provide a mechanism for livepatch modules to execute callback functions when a kernel object is (un)patched. They -can be considered a "power feature" that extends livepatching abilities +can be considered a **power feature** that **extends livepatching abilities** to include: - Safe updates to global data @@ -17,6 +17,9 @@ In most cases, (un)patch callbacks will need to be used in conjunction with memory barriers and kernel synchronization primitives, like mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues. +1. Motivation +============= + Callbacks differ from existing kernel facilities: - Module init/exit code doesn't run when disabling and re-enabling a @@ -28,6 +31,9 @@ Callbacks are part of the klp_object structure and their implementation is specific to that klp_object. Other livepatch objects may or may not be patched, irrespective of the target klp_object's current state. +2. Callback types +================= + Callbacks can be registered for the following livepatch actions: * Pre-patch @@ -47,6 +53,9 @@ Callbacks can be registered for the following livepatch actions: been restored and no tasks are running patched code, used to cleanup pre-patch callback resources +3. How it works +=============== + Each callback is optional, omitting one does not preclude specifying any other. However, the livepatching core executes the handlers in symmetry: pre-patch callbacks have a post-unpatch counterpart and @@ -90,11 +99,14 @@ If the object did successfully patch, but the patch transition never started for some reason (e.g., if another object failed to patch), only the post-unpatch callback will be called. +4. Use cases +============ -Example Use-cases -================= +Sample livepatch modules demonstrating the callback API can be found in +samples/livepatch/ directory. These samples were modified for use in +kselftests and can be found in the lib/livepatch directory. -Update global data +Global data update ------------------ A pre-patch callback can be useful to update a global variable. For @@ -107,24 +119,15 @@ patch the data *after* patching is complete with a post-patch callback, so that tcp_send_challenge_ack() could first be changed to read sysctl_tcp_challenge_ack_limit with READ_ONCE. - -Support __init and probe function patches +__init and probe function patches support ----------------------------------------- Although __init and probe functions are not directly livepatch-able, it may be possible to implement similar updates via pre/post-patch callbacks. -48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that +The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that virtnet_probe() initialized its driver's net_device features. A pre/post-patch callback could iterate over all such devices, making a similar change to their hw_features value. (Client functions of the value may need to be updated accordingly.) - - -Other Examples -============== - -Sample livepatch modules demonstrating the callback API can be found in -samples/livepatch/ directory. These samples were modified for use in -kselftests and can be found in the lib/livepatch directory. |