1======================
2(Un)patching Callbacks
3======================
4
5Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
6to execute callback functions when a kernel object is (un)patched.  They
7can be considered a "power feature" that extends livepatching abilities
8to include:
9
10  - Safe updates to global data
11
12  - "Patches" to init and probe functions
13
14  - Patching otherwise unpatchable code (i.e. assembly)
15
16In most cases, (un)patch callbacks will need to be used in conjunction
17with memory barriers and kernel synchronization primitives, like
18mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
19
20Callbacks differ from existing kernel facilities:
21
22  - Module init/exit code doesn't run when disabling and re-enabling a
23    patch.
24
25  - A module notifier can't stop a to-be-patched module from loading.
26
27Callbacks are part of the klp_object structure and their implementation
28is specific to that klp_object.  Other livepatch objects may or may not
29be patched, irrespective of the target klp_object's current state.
30
31Callbacks can be registered for the following livepatch actions:
32
33  * Pre-patch
34                 - before a klp_object is patched
35
36  * Post-patch
37                 - after a klp_object has been patched and is active
38                   across all tasks
39
40  * Pre-unpatch
41                 - before a klp_object is unpatched (ie, patched code is
42                   active), used to clean up post-patch callback
43                   resources
44
45  * Post-unpatch
46                 - after a klp_object has been patched, all code has
47                   been restored and no tasks are running patched code,
48                   used to cleanup pre-patch callback resources
49
50Each callback is optional, omitting one does not preclude specifying any
51other.  However, the livepatching core executes the handlers in
52symmetry: pre-patch callbacks have a post-unpatch counterpart and
53post-patch callbacks have a pre-unpatch counterpart.  An unpatch
54callback will only be executed if its corresponding patch callback was
55executed.  Typical use cases pair a patch handler that acquires and
56configures resources with an unpatch handler tears down and releases
57those same resources.
58
59A callback is only executed if its host klp_object is loaded.  For
60in-kernel vmlinux targets, this means that callbacks will always execute
61when a livepatch is enabled/disabled.  For patch target kernel modules,
62callbacks will only execute if the target module is loaded.  When a
63module target is (un)loaded, its callbacks will execute only if the
64livepatch module is enabled.
65
66The pre-patch callback, if specified, is expected to return a status
67code (0 for success, -ERRNO on error).  An error status code indicates
68to the livepatching core that patching of the current klp_object is not
69safe and to stop the current patching request.  (When no pre-patch
70callback is provided, the transition is assumed to be safe.)  If a
71pre-patch callback returns failure, the kernel's module loader will:
72
73  - Refuse to load a livepatch, if the livepatch is loaded after
74    targeted code.
75
76    or:
77
78  - Refuse to load a module, if the livepatch was already successfully
79    loaded.
80
81No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
82for a given klp_object if the object failed to patch, due to a failed
83pre_patch callback or for any other reason.
84
85If a patch transition is reversed, no pre-unpatch handlers will be run
86(this follows the previously mentioned symmetry -- pre-unpatch callbacks
87will only occur if their corresponding post-patch callback executed).
88
89If the object did successfully patch, but the patch transition never
90started for some reason (e.g., if another object failed to patch),
91only the post-unpatch callback will be called.
92
93
94Example Use-cases
95=================
96
97Update global data
98------------------
99
100A pre-patch callback can be useful to update a global variable.  For
101example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
102changes a global sysctl, as well as patches the tcp_send_challenge_ack()
103function.
104
105In this case, if we're being super paranoid, it might make sense to
106patch the data *after* patching is complete with a post-patch callback,
107so that tcp_send_challenge_ack() could first be changed to read
108sysctl_tcp_challenge_ack_limit with READ_ONCE.
109
110
111Support __init and probe function patches
112-----------------------------------------
113
114Although __init and probe functions are not directly livepatch-able, it
115may be possible to implement similar updates via pre/post-patch
116callbacks.
117
11848900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
119virtnet_probe() initialized its driver's net_device features.  A
120pre/post-patch callback could iterate over all such devices, making a
121similar change to their hw_features value.  (Client functions of the
122value may need to be updated accordingly.)
123
124
125Other Examples
126==============
127
128Sample livepatch modules demonstrating the callback API can be found in
129samples/livepatch/ directory.  These samples were modified for use in
130kselftests and can be found in the lib/livepatch directory.
131