Documentation/livepatch/system-state.rst

   1 ====================
   2 System State Changes
   3 ====================
   4
   5 Some users are really reluctant to reboot a system. This brings the need
   6 to provide more livepatches and maintain some compatibility between them.
   7
   8 Maintaining more livepatches is much easier with cumulative livepatches.
   9 Each new livepatch completely replaces any older one. It can keep,
  10 add, and even remove fixes. And it is typically safe to replace any version
  11 of the livepatch with any other one thanks to the atomic replace feature.
  12
  13 The problems might come with shadow variables and callbacks. They might
  14 change the system behavior or state so that it is no longer safe to
  15 go back and use an older livepatch or the original kernel code. Also
  16 any new livepatch must be able to detect what changes have already been
  17 done by the already installed livepatches.
  18
  19 This is where the livepatch system state tracking gets useful. It
  20 allows to:
  21
  22   - store data needed to manipulate and restore the system state
  23
  24   - define compatibility between livepatches using a change id
  25     and version
  26
  27
  28 1. Livepatch system state API
  29 =============================
  30
  31 The state of the system might get modified either by several livepatch callbacks
  32 or by the newly used code. Also it must be possible to find changes done by
  33 already installed livepatches.
  34
  35 Each modified state is described by struct klp_state, see
  36 include/linux/livepatch.h.
  37
  38 Each livepatch defines an array of struct klp_states. They mention
  39 all states that the livepatch modifies.
  40
  41 The livepatch author must define the following two fields for each
  42 struct klp_state:
  43
  44   - *id*
  45
  46     - Non-zero number used to identify the affected system state.
  47
  48   - *version*
  49
  50     - Number describing the variant of the system state change that
  51       is supported by the given livepatch.
  52
  53 The state can be manipulated using two functions:
  54
  55   - *klp_get_state(patch, id)*
  56
  57     - Get struct klp_state associated with the given livepatch
  58       and state id.
  59
  60   - *klp_get_prev_state(id)*
  61
  62     - Get struct klp_state associated with the given feature id and
  63       already installed livepatches.
  64
  65 2. Livepatch compatibility
  66 ==========================
  67
  68 The system state version is used to prevent loading incompatible livepatches.
  69 The check is done when the livepatch is enabled. The rules are:
  70
  71   - Any completely new system state modification is allowed.
  72
  73   - System state modifications with the same or higher version are allowed
  74     for already modified system states.
  75
  76   - Cumulative livepatches must handle all system state modifications from
  77     already installed livepatches.
  78
  79   - Non-cumulative livepatches are allowed to touch already modified
  80     system states.
  81
  82 3. Supported scenarios
  83 ======================
  84
  85 Livepatches have their life-cycle and the same is true for the system
  86 state changes. Every compatible livepatch has to support the following
  87 scenarios:
  88
  89   - Modify the system state when the livepatch gets enabled and the state
  90     has not been already modified by a livepatches that are being
  91     replaced.
  92
  93   - Take over or update the system state modification when is has already
  94     been done by a livepatch that is being replaced.
  95
  96   - Restore the original state when the livepatch is disabled.
  97
  98   - Restore the previous state when the transition is reverted.
  99     It might be the original system state or the state modification
 100     done by livepatches that were being replaced.
 101
 102   - Remove any already made changes when error occurs and the livepatch
 103     cannot get enabled.
 104
 105 4. Expected usage
 106 =================
 107
 108 System states are usually modified by livepatch callbacks. The expected
 109 role of each callback is as follows:
 110
 111 *pre_patch()*
 112
 113   - Allocate *state->data* when necessary. The allocation might fail
 114     and *pre_patch()* is the only callback that could stop loading
 115     of the livepatch. The allocation is not needed when the data
 116     are already provided by previously installed livepatches.
 117
 118   - Do any other preparatory action that is needed by
 119     the new code even before the transition gets finished.
 120     For example, initialize *state->data*.
 121
 122     The system state itself is typically modified in *post_patch()*
 123     when the entire system is able to handle it.
 124
 125   - Clean up its own mess in case of error. It might be done by a custom
 126     code or by calling *post_unpatch()* explicitly.
 127
 128 *post_patch()*
 129
 130   - Copy *state->data* from the previous livepatch when they are
 131     compatible.
 132
 133   - Do the actual system state modification. Eventually allow
 134     the new code to use it.
 135
 136   - Make sure that *state->data* has all necessary information.
 137
 138   - Free *state->data* from replaces livepatches when they are
 139     not longer needed.
 140
 141 *pre_unpatch()*
 142
 143   - Prevent the code, added by the livepatch, relying on the system
 144     state change.
 145
 146   - Revert the system state modification..
 147
 148 *post_unpatch()*
 149
 150   - Distinguish transition reverse and livepatch disabling by
 151     checking *klp_get_prev_state()*.
 152
 153   - In case of transition reverse, restore the previous system
 154     state. It might mean doing nothing.
 155
 156   - Remove any not longer needed setting or data.
 157
 158 .. note::
 159
 160    *pre_unpatch()* typically does symmetric operations to *post_patch()*.
 161    Except that it is called only when the livepatch is being disabled.
 162    Therefore it does not need to care about any previously installed
 163    livepatch.
 164
 165    *post_unpatch()* typically does symmetric operations to *pre_patch()*.
 166    It might be called also during the transition reverse. Therefore it
 167    has to handle the state of the previously installed livepatches.