+++ /dev/null
-======================
-(Un)patching Callbacks
-======================
-
-Livepatch (un)patch-callbacks provide a mechanism for livepatch modules
-to execute callback functions when a kernel object is (un)patched. They
-can be considered a "power feature" that extends livepatching abilities
-to include:
-
- - Safe updates to global data
-
- - "Patches" to init and probe functions
-
- - Patching otherwise unpatchable code (i.e. assembly)
-
-In most cases, (un)patch callbacks will need to be used in conjunction
-with memory barriers and kernel synchronization primitives, like
-mutexes/spinlocks, or even stop_machine(), to avoid concurrency issues.
-
-Callbacks differ from existing kernel facilities:
-
- - Module init/exit code doesn't run when disabling and re-enabling a
- patch.
-
- - A module notifier can't stop a to-be-patched module from loading.
-
-Callbacks are part of the klp_object structure and their implementation
-is specific to that klp_object. Other livepatch objects may or may not
-be patched, irrespective of the target klp_object's current state.
-
-Callbacks can be registered for the following livepatch actions:
-
- * Pre-patch - before a klp_object is patched
-
- * Post-patch - after a klp_object has been patched and is active
- across all tasks
-
- * Pre-unpatch - before a klp_object is unpatched (ie, patched code is
- active), used to clean up post-patch callback
- resources
-
- * Post-unpatch - after a klp_object has been patched, all code has
- been restored and no tasks are running patched code,
- used to cleanup pre-patch callback resources
-
-Each callback is optional, omitting one does not preclude specifying any
-other. However, the livepatching core executes the handlers in
-symmetry: pre-patch callbacks have a post-unpatch counterpart and
-post-patch callbacks have a pre-unpatch counterpart. An unpatch
-callback will only be executed if its corresponding patch callback was
-executed. Typical use cases pair a patch handler that acquires and
-configures resources with an unpatch handler tears down and releases
-those same resources.
-
-A callback is only executed if its host klp_object is loaded. For
-in-kernel vmlinux targets, this means that callbacks will always execute
-when a livepatch is enabled/disabled. For patch target kernel modules,
-callbacks will only execute if the target module is loaded. When a
-module target is (un)loaded, its callbacks will execute only if the
-livepatch module is enabled.
-
-The pre-patch callback, if specified, is expected to return a status
-code (0 for success, -ERRNO on error). An error status code indicates
-to the livepatching core that patching of the current klp_object is not
-safe and to stop the current patching request. (When no pre-patch
-callback is provided, the transition is assumed to be safe.) If a
-pre-patch callback returns failure, the kernel's module loader will:
-
- - Refuse to load a livepatch, if the livepatch is loaded after
- targeted code.
-
- or:
-
- - Refuse to load a module, if the livepatch was already successfully
- loaded.
-
-No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
-for a given klp_object if the object failed to patch, due to a failed
-pre_patch callback or for any other reason.
-
-If a patch transition is reversed, no pre-unpatch handlers will be run
-(this follows the previously mentioned symmetry -- pre-unpatch callbacks
-will only occur if their corresponding post-patch callback executed).
-
-If the object did successfully patch, but the patch transition never
-started for some reason (e.g., if another object failed to patch),
-only the post-unpatch callback will be called.
-
-
-Example Use-cases
-=================
-
-Update global data
-------------------
-
-A pre-patch callback can be useful to update a global variable. For
-example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
-changes a global sysctl, as well as patches the tcp_send_challenge_ack()
-function.
-
-In this case, if we're being super paranoid, it might make sense to
-patch the data *after* patching is complete with a post-patch callback,
-so that tcp_send_challenge_ack() could first be changed to read
-sysctl_tcp_challenge_ack_limit with READ_ONCE.
-
-
-Support __init and probe function patches
------------------------------------------
-
-Although __init and probe functions are not directly livepatch-able, it
-may be possible to implement similar updates via pre/post-patch
-callbacks.
-
-48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
-virtnet_probe() initialized its driver's net_device features. A
-pre/post-patch callback could iterate over all such devices, making a
-similar change to their hw_features value. (Client functions of the
-value may need to be updated accordingly.)
-
-
-Other Examples
-==============
-
-Sample livepatch modules demonstrating the callback API can be found in
-samples/livepatch/ directory. These samples were modified for use in
-kselftests and can be found in the lib/livepatch directory.
projects / linux-2.6-block.git / blobdiff