| 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 | 1. Motivation
|
| 21 | =============
|
| 22 |
|
| 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 |
|
| 34 | 2. Callback types
|
| 35 | =================
|
| 36 |
|
| 37 | Callbacks 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 |
|
| 56 | 3. How it works
|
| 57 | ===============
|
| 58 |
|
| 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 |
|
| 102 | 4. Use cases
|
| 103 | ============
|
| 104 |
|
| 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.
|
| 108 |
|
| 109 | Global data update
|
| 110 | ------------------
|
| 111 |
|
| 112 | A pre-patch callback can be useful to update a global variable. For
|
| 113 | example, commit 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 |
|
| 122 | __init and probe function patches support
|
| 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 |
|
| 129 | The commit 48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
|
| 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.)
|