| 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()
|
| 56 |
|
| 57 | - Get struct klp_state associated with the given livepatch
|
| 58 | and state id.
|
| 59 |
|
| 60 | - klp_get_prev_state()
|
| 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.
|