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