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