Documentation/livepatch/callbacks.rst

   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 1. Motivation
  21 =============
  22
  23 Callbacks 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
  30 Callbacks are part of the klp_object structure and their implementation
  31 is specific to that klp_object.  Other livepatch objects may or may not
  32 be patched, irrespective of the target klp_object's current state.
  33
  34 2. Callback types
  35 =================
  36
  37 Callbacks 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
  56 3. How it works
  57 ===============
  58
  59 Each callback is optional, omitting one does not preclude specifying any
  60 other.  However, the livepatching core executes the handlers in
  61 symmetry: pre-patch callbacks have a post-unpatch counterpart and
  62 post-patch callbacks have a pre-unpatch counterpart.  An unpatch
  63 callback will only be executed if its corresponding patch callback was
  64 executed.  Typical use cases pair a patch handler that acquires and
  65 configures resources with an unpatch handler tears down and releases
  66 those same resources.
  67
  68 A callback is only executed if its host klp_object is loaded.  For
  69 in-kernel vmlinux targets, this means that callbacks will always execute
  70 when a livepatch is enabled/disabled.  For patch target kernel modules,
  71 callbacks will only execute if the target module is loaded.  When a
  72 module target is (un)loaded, its callbacks will execute only if the
  73 livepatch module is enabled.
  74
  75 The pre-patch callback, if specified, is expected to return a status
  76 code (0 for success, -ERRNO on error).  An error status code indicates
  77 to the livepatching core that patching of the current klp_object is not
  78 safe and to stop the current patching request.  (When no pre-patch
  79 callback is provided, the transition is assumed to be safe.)  If a
  80 pre-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
  90 No post-patch, pre-unpatch, or post-unpatch callbacks will be executed
  91 for a given klp_object if the object failed to patch, due to a failed
  92 pre_patch callback or for any other reason.
  93
  94 If a patch transition is reversed, no pre-unpatch handlers will be run
  95 (this follows the previously mentioned symmetry -- pre-unpatch callbacks
  96 will only occur if their corresponding post-patch callback executed).
  97
  98 If the object did successfully patch, but the patch transition never
  99 started for some reason (e.g., if another object failed to patch),
 100 only the post-unpatch callback will be called.
 101
 102 4. Use cases
 103 ============
 104
 105 Sample livepatch modules demonstrating the callback API can be found in
 106 samples/livepatch/ directory.  These samples were modified for use in
 107 kselftests and can be found in the lib/livepatch directory.
 108
 109 Global data update
 110 ------------------
 111
 112 A pre-patch callback can be useful to update a global variable.  For
 113 example, 75ff39ccc1bd ("tcp: make challenge acks less predictable")
 114 changes a global sysctl, as well as patches the tcp_send_challenge_ack()
 115 function.
 116
 117 In this case, if we're being super paranoid, it might make sense to
 118 patch the data *after* patching is complete with a post-patch callback,
 119 so that tcp_send_challenge_ack() could first be changed to read
 120 sysctl_tcp_challenge_ack_limit with READ_ONCE.
 121
 122 __init and probe function patches support
 123 -----------------------------------------
 124
 125 Although __init and probe functions are not directly livepatch-able, it
 126 may be possible to implement similar updates via pre/post-patch
 127 callbacks.
 128
 129 The commit ``48900cb6af42 ("virtio-net: drop NETIF_F_FRAGLIST")`` change the way that
 130 virtnet_probe() initialized its driver's net_device features.  A
 131 pre/post-patch callback could iterate over all such devices, making a
 132 similar change to their hw_features value.  (Client functions of the
 133 value may need to be updated accordingly.)