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