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, 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.) 134