0001 ======================
0002 (Un)patching Callbacks
0003 ======================
0004
0005 Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
0006 to execute callback functions when a kernel object is (un)patched. They
0007 can be considered a **power feature** that **extends livepatching abilities**
0008 to include:
0009
0010 - Safe updates to global data
0011
0012 - "Patches" to init and probe functions
0013
0014 - Patching otherwise unpatchable code (i.e. assembly)
0015
0016 In most cases, (un)patch callbacks will need to be used in conjunction
0017 with memory barriers and kernel synchronization primitives, like
0018 mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
0019
0020 1. Motivation
0021 =============
0022
0023 Callbacks differ from existing kernel facilities:
0024
0025 - Module init/exit code doesn't run when disabling and re-enabling a
0026 patch.
0027
0028 - A module notifier can't stop a to-be-patched module from loading.
0029
0030 Callbacks are part of the klp_object structure and their implementation
0031 is specific to that klp_object. Other livepatch objects may or may not
0032 be patched, irrespective of the target klp_object's current state.
0033
0034 2. Callback types
0035 =================
0036
0037 Callbacks can be registered for the following livepatch actions:
0038
0039 * Pre-patch
0040 - before a klp_object is patched
0041
0042 * Post-patch
0043 - after a klp_object has been patched and is active
0044 across all tasks
0045
0046 * Pre-unpatch
0047 - before a klp_object is unpatched (ie, patched code is
0048 active), used to clean up post-patch callback
0049 resources
0050
0051 * Post-unpatch
0052 - after a klp_object has been patched, all code has
0053 been restored and no tasks are running patched code,
0054 used to cleanup pre-patch callback resources
0055
0056 3. How it works
0057 ===============
0058
0059 Each callback is optional, omitting one does not preclude specifying any
0060 other. However, the livepatching core executes the handlers in
0061 symmetry: pre-patch callbacks have a post-unpatch counterpart and
0062 post-patch callbacks have a pre-unpatch counterpart. An unpatch
0063 callback will only be executed if its corresponding patch callback was
0064 executed. Typical use cases pair a patch handler that acquires and
0065 configures resources with an unpatch handler tears down and releases
0066 those same resources.
0067
0068 A callback is only executed if its host klp_object is loaded. For
0069 in-kernel vmlinux targets, this means that callbacks will always execute
0070 when a livepatch is enabled/disabled. For patch target kernel modules,
0071 callbacks will only execute if the target module is loaded. When a
0072 module target is (un)loaded, its callbacks will execute only if the
0073 livepatch module is enabled.
0074
0075 The pre-patch callback, if specified, is expected to return a status
0076 code (0 for success, -ERRNO on error). An error status code indicates
0077 to the livepatching core that patching of the current klp_object is not
0078 safe and to stop the current patching request. (When no pre-patch
0079 callback is provided, the transition is assumed to be safe.) If a
0080 pre-patch callback returns failure, the kernel's module loader will:
0081
0082 - Refuse to load a livepatch, if the livepatch is loaded after
0083 targeted code.
0084
0085 or:
0086
0087 - Refuse to load a module, if the livepatch was already successfully
0088 loaded.
0089
0090 No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
0091 for a given klp_object if the object failed to patch, due to a failed
0092 pre_patch callback or for any other reason.
0093
0094 If a patch transition is reversed, no pre-unpatch handlers will be run
0095 (this follows the previously mentioned symmetry -- pre-unpatch callbacks
0096 will only occur if their corresponding post-patch callback executed).
0097
0098 If the object did successfully patch, but the patch transition never
0099 started for some reason (e.g., if another object failed to patch),
0100 only the post-unpatch callback will be called.
0101
0102 4. Use cases
0103 ============
0104
0105 Sample livepatch modules demonstrating the callback API can be found in
0106 samples/livepatch/ directory. These samples were modified for use in
0107 kselftests and can be found in the lib/livepatch directory.
0108
0109 Global data update
0110 ------------------
0111
0112 A pre-patch callback can be useful to update a global variable. For
0113 example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
0114 changes a global sysctl, as well as patches the tcp_send_challenge_ack()
0115 function.
0116
0117 In this case, if we're being super paranoid, it might make sense to
0118 patch the data *after* patching is complete with a post-patch callback,
0119 so that tcp_send_challenge_ack() could first be changed to read
0120 sysctl_tcp_challenge_ack_limit with READ_ONCE.
0121
0122 __init and probe function patches support
0123 -----------------------------------------
0124
0125 Although __init and probe functions are not directly livepatch-able, it
0126 may be possible to implement similar updates via pre/post-patch
0127 callbacks.
0128
0129 The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
0130 virtnet_probe() initialized its driver's net_device features. A
0131 pre/post-patch callback could iterate over all such devices, making a
0132 similar change to their hw_features value. (Client functions of the
0133 value may need to be updated accordingly.)
