Documentation/livepatch/callbacks.txt

   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 Callbacks differ from existing kernel facilities:
  21
  22   - Module init/exit code doesn't run when disabling and re-enabling a
  23     patch.
  24
  25   - A module notifier can't stop a to-be-patched module from loading.
  26
  27 Callbacks are part of the klp_object structure and their implementation
  28 is specific to that klp_object.  Other livepatch objects may or may not
  29 be patched, irrespective of the target klp_object's current state.
  30
  31 Callbacks can be registered for the following livepatch actions:
  32
  33   * Pre-patch    - before a klp_object is patched
  34
  35   * Post-patch   - after a klp_object has been patched and is active
  36                    across all tasks
  37
  38   * Pre-unpatch  - before a klp_object is unpatched (ie, patched code is
  39                    active), used to clean up post-patch callback
  40                    resources
  41
  42   * Post-unpatch - after a klp_object has been patched, all code has
  43                    been restored and no tasks are running patched code,
  44                    used to cleanup pre-patch callback resources
  45
  46 Each callback is optional, omitting one does not preclude specifying any
  47 other.  However, the livepatching core executes the handlers in
  48 symmetry: pre-patch callbacks have a post-unpatch counterpart and
  49 post-patch callbacks have a pre-unpatch counterpart.  An unpatch
  50 callback will only be executed if its corresponding patch callback was
  51 executed.  Typical use cases pair a patch handler that acquires and
  52 configures resources with an unpatch handler tears down and releases
  53 those same resources.
  54
  55 A callback is only executed if its host klp_object is loaded.  For
  56 in-kernel vmlinux targets, this means that callbacks will always execute
  57 when a livepatch is enabled/disabled.  For patch target kernel modules,
  58 callbacks will only execute if the target module is loaded.  When a
  59 module target is (un)loaded, its callbacks will execute only if the
  60 livepatch module is enabled.
  61
  62 The pre-patch callback, if specified, is expected to return a status
  63 code (0 for success, -ERRNO on error).  An error status code indicates
  64 to the livepatching core that patching of the current klp_object is not
  65 safe and to stop the current patching request.  (When no pre-patch
  66 callback is provided, the transition is assumed to be safe.)  If a
  67 pre-patch callback returns failure, the kernel's module loader will:
  68
  69   - Refuse to load a livepatch, if the livepatch is loaded after
  70     targeted code.
  71
  72     or:
  73
  74   - Refuse to load a module, if the livepatch was already successfully
  75     loaded.
  76
  77 No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
  78 for a given klp_object if the object failed to patch, due to a failed
  79 pre_patch callback or for any other reason.
  80
  81 If a patch transition is reversed, no pre-unpatch handlers will be run
  82 (this follows the previously mentioned symmetry -- pre-unpatch callbacks
  83 will only occur if their corresponding post-patch callback executed).
  84
  85 If the object did successfully patch, but the patch transition never
  86 started for some reason (e.g., if another object failed to patch),
  87 only the post-unpatch callback will be called.
  88
  89
  90 Example Use-cases
  91 =================
  92
  93 Update global data
  94 ------------------
  95
  96 A pre-patch callback can be useful to update a global variable.  For
  97 example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
  98 changes a global sysctl, as well as patches the tcp_send_challenge_ack()
  99 function.
 100
 101 In this case, if we're being super paranoid, it might make sense to
 102 patch the data *after* patching is complete with a post-patch callback,
 103 so that tcp_send_challenge_ack() could first be changed to read
 104 sysctl_tcp_challenge_ack_limit with READ_ONCE.
 105
 106
 107 Support __init and probe function patches
 108 -----------------------------------------
 109
 110 Although __init and probe functions are not directly livepatch-able, it
 111 may be possible to implement similar updates via pre/post-patch
 112 callbacks.
 113
 114 48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST") change the way that
 115 virtnet_probe() initialized its driver's net_device features.  A
 116 pre/post-patch callback could iterate over all such devices, making a
 117 similar change to their hw_features value.  (Client functions of the
 118 value may need to be updated accordingly.)
 119
 120
 121 Other Examples
 122 ==============
 123
 124 Sample livepatch modules demonstrating the callback API can be found in
 125 samples/livepatch/ directory.  These samples were modified for use in
 126 kselftests and can be found in the lib/livepatch directory.