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