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