1. Motivation¶

Callbacks differ from existing kernel facilities:

• Module init/exit code doesn’t run when disabling and re-enabling apatch.

• A module notifier can’t stop a to-be-patched module from loading.

Callbacks are part of the klp_object structure and their implementationis specific to that klp_object. Other livepatch objects may or may notbe 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 activeacross all tasks

• Pre-unpatch

  • before a klp_object is unpatched (ie, patched code isactive), used to clean up post-patch callbackresources

• Post-unpatch

  • after a klp_object has been patched, all code hasbeen 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 anyother. However, the livepatching core executes the handlers insymmetry: pre-patch callbacks have a post-unpatch counterpart andpost-patch callbacks have a pre-unpatch counterpart. An unpatchcallback will only be executed if its corresponding patch callback wasexecuted. Typical use cases pair a patch handler that acquires andconfigures resources with an unpatch handler tears down and releasesthose same resources.

A callback is only executed if its host klp_object is loaded. Forin-kernel vmlinux targets, this means that callbacks will always executewhen a livepatch is enabled/disabled. For patch target kernel modules,callbacks will only execute if the target module is loaded. When amodule target is (un)loaded, its callbacks will execute only if thelivepatch module is enabled.

The pre-patch callback, if specified, is expected to return a statuscode (0 for success, -ERRNO on error). An error status code indicatesto the livepatching core that patching of the current klp_object is notsafe and to stop the current patching request. (When no pre-patchcallback is provided, the transition is assumed to be safe.) If apre-patch callback returns failure, the kernel’s module loader will:

• Refuse to load a livepatch, if the livepatch is loaded aftertargeted code.

  or:

• Refuse to load a module, if the livepatch was already successfullyloaded.

No post-patch, pre-unpatch, or post-unpatch callbacks will be executedfor a given klp_object if the object failed to patch, due to a failedpre_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 callbackswill only occur if their corresponding post-patch callback executed).

If the object did successfully patch, but the patch transition neverstarted 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 insamples/livepatch/ directory. These samples were modified for use inkselftests and can be found in the lib/livepatch directory.