1 ======================
2 (Un)patching Callbacks
3 ======================
4
5 Livepatch (un)patch-callbacks provide a mechan
6 to execute callback functions when a kernel ob
7 can be considered a **power feature** that **e
8 to include:
9
10 - Safe updates to global data
11
12 - "Patches" to init and probe functions
13
14 - Patching otherwise unpatchable code (i.e.
15
16 In most cases, (un)patch callbacks will need t
17 with memory barriers and kernel synchronizatio
18 mutexes/spinlocks, or even stop_machine(), to
19
20 1. Motivation
21 =============
22
23 Callbacks differ from existing kernel faciliti
24
25 - Module init/exit code doesn't run when dis
26 patch.
27
28 - A module notifier can't stop a to-be-patch
29
30 Callbacks are part of the klp_object structure
31 is specific to that klp_object. Other livepat
32 be patched, irrespective of the target klp_obj
33
34 2. Callback types
35 =================
36
37 Callbacks can be registered for the following
38
39 * Pre-patch
40 - before a klp_object is patc
41
42 * Post-patch
43 - after a klp_object has been
44 across all tasks
45
46 * Pre-unpatch
47 - before a klp_object is unpa
48 active), used to clean up p
49 resources
50
51 * Post-unpatch
52 - after a klp_object has been
53 been restored and no tasks
54 used to cleanup pre-patch c
55
56 3. How it works
57 ===============
58
59 Each callback is optional, omitting one does n
60 other. However, the livepatching core execute
61 symmetry: pre-patch callbacks have a post-unpa
62 post-patch callbacks have a pre-unpatch counte
63 callback will only be executed if its correspo
64 executed. Typical use cases pair a patch hand
65 configures resources with an unpatch handler t
66 those same resources.
67
68 A callback is only executed if its host klp_ob
69 in-kernel vmlinux targets, this means that cal
70 when a livepatch is enabled/disabled. For pat
71 callbacks will only execute if the target modu
72 module target is (un)loaded, its callbacks wil
73 livepatch module is enabled.
74
75 The pre-patch callback, if specified, is expec
76 code (0 for success, -ERRNO on error). An err
77 to the livepatching core that patching of the
78 safe and to stop the current patching request.
79 callback is provided, the transition is assume
80 pre-patch callback returns failure, the kernel
81
82 - Refuse to load a livepatch, if the livepat
83 targeted code.
84
85 or:
86
87 - Refuse to load a module, if the livepatch
88 loaded.
89
90 No post-patch, pre-unpatch, or post-unpatch ca
91 for a given klp_object if the object failed to
92 pre_patch callback or for any other reason.
93
94 If a patch transition is reversed, no pre-unpa
95 (this follows the previously mentioned symmetr
96 will only occur if their corresponding post-pa
97
98 If the object did successfully patch, but the
99 started for some reason (e.g., if another obje
100 only the post-unpatch callback will be called.
101
102 4. Use cases
103 ============
104
105 Sample livepatch modules demonstrating the cal
106 samples/livepatch/ directory. These samples w
107 kselftests and can be found in the lib/livepat
108
109 Global data update
110 ------------------
111
112 A pre-patch callback can be useful to update a
113 example, commit 75ff39ccc1bd ("tcp: make chall
114 changes a global sysctl, as well as patches th
115 function.
116
117 In this case, if we're being super paranoid, i
118 patch the data *after* patching is complete wi
119 so that tcp_send_challenge_ack() could first b
120 sysctl_tcp_challenge_ack_limit with READ_ONCE.
121
122 __init and probe function patches support
123 -----------------------------------------
124
125 Although __init and probe functions are not di
126 may be possible to implement similar updates v
127 callbacks.
128
129 The commit 48900cb6af42 ("virtio-net: drop NET
130 virtnet_probe() initialized its driver's net_d
131 pre/post-patch callback could iterate over all
132 similar change to their hw_features value. (C
133 value may need to be updated accordingly.)
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.