123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133 |
- ======================
- (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.
- 1. Motivation
- =============
- 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.
- 2. Callback types
- =================
- 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
- 3. How it works
- ===============
- 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.
- 4. Use cases
- ============
- 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.
- Global data update
- ------------------
- 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.
- __init and probe function patches support
- -----------------------------------------
- Although __init and probe functions are not directly livepatch-able, it
- may be possible to implement similar updates via pre/post-patch
- callbacks.
- The commit ``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.)
|