0001 ====================
0002 System State Changes
0003 ====================
0004
0005 Some users are really reluctant to reboot a system. This brings the need
0006 to provide more livepatches and maintain some compatibility between them.
0007
0008 Maintaining more livepatches is much easier with cumulative livepatches.
0009 Each new livepatch completely replaces any older one. It can keep,
0010 add, and even remove fixes. And it is typically safe to replace any version
0011 of the livepatch with any other one thanks to the atomic replace feature.
0012
0013 The problems might come with shadow variables and callbacks. They might
0014 change the system behavior or state so that it is no longer safe to
0015 go back and use an older livepatch or the original kernel code. Also
0016 any new livepatch must be able to detect what changes have already been
0017 done by the already installed livepatches.
0018
0019 This is where the livepatch system state tracking gets useful. It
0020 allows to:
0021
0022 - store data needed to manipulate and restore the system state
0023
0024 - define compatibility between livepatches using a change id
0025 and version
0026
0027
0028 1. Livepatch system state API
0029 =============================
0030
0031 The state of the system might get modified either by several livepatch callbacks
0032 or by the newly used code. Also it must be possible to find changes done by
0033 already installed livepatches.
0034
0035 Each modified state is described by struct klp_state, see
0036 include/linux/livepatch.h.
0037
0038 Each livepatch defines an array of struct klp_states. They mention
0039 all states that the livepatch modifies.
0040
0041 The livepatch author must define the following two fields for each
0042 struct klp_state:
0043
0044 - *id*
0045
0046 - Non-zero number used to identify the affected system state.
0047
0048 - *version*
0049
0050 - Number describing the variant of the system state change that
0051 is supported by the given livepatch.
0052
0053 The state can be manipulated using two functions:
0054
0055 - klp_get_state()
0056
0057 - Get struct klp_state associated with the given livepatch
0058 and state id.
0059
0060 - klp_get_prev_state()
0061
0062 - Get struct klp_state associated with the given feature id and
0063 already installed livepatches.
0064
0065 2. Livepatch compatibility
0066 ==========================
0067
0068 The system state version is used to prevent loading incompatible livepatches.
0069 The check is done when the livepatch is enabled. The rules are:
0070
0071 - Any completely new system state modification is allowed.
0072
0073 - System state modifications with the same or higher version are allowed
0074 for already modified system states.
0075
0076 - Cumulative livepatches must handle all system state modifications from
0077 already installed livepatches.
0078
0079 - Non-cumulative livepatches are allowed to touch already modified
0080 system states.
0081
0082 3. Supported scenarios
0083 ======================
0084
0085 Livepatches have their life-cycle and the same is true for the system
0086 state changes. Every compatible livepatch has to support the following
0087 scenarios:
0088
0089 - Modify the system state when the livepatch gets enabled and the state
0090 has not been already modified by a livepatches that are being
0091 replaced.
0092
0093 - Take over or update the system state modification when is has already
0094 been done by a livepatch that is being replaced.
0095
0096 - Restore the original state when the livepatch is disabled.
0097
0098 - Restore the previous state when the transition is reverted.
0099 It might be the original system state or the state modification
0100 done by livepatches that were being replaced.
0101
0102 - Remove any already made changes when error occurs and the livepatch
0103 cannot get enabled.
0104
0105 4. Expected usage
0106 =================
0107
0108 System states are usually modified by livepatch callbacks. The expected
0109 role of each callback is as follows:
0110
0111 *pre_patch()*
0112
0113 - Allocate *state->data* when necessary. The allocation might fail
0114 and *pre_patch()* is the only callback that could stop loading
0115 of the livepatch. The allocation is not needed when the data
0116 are already provided by previously installed livepatches.
0117
0118 - Do any other preparatory action that is needed by
0119 the new code even before the transition gets finished.
0120 For example, initialize *state->data*.
0121
0122 The system state itself is typically modified in *post_patch()*
0123 when the entire system is able to handle it.
0124
0125 - Clean up its own mess in case of error. It might be done by a custom
0126 code or by calling *post_unpatch()* explicitly.
0127
0128 *post_patch()*
0129
0130 - Copy *state->data* from the previous livepatch when they are
0131 compatible.
0132
0133 - Do the actual system state modification. Eventually allow
0134 the new code to use it.
0135
0136 - Make sure that *state->data* has all necessary information.
0137
0138 - Free *state->data* from replaces livepatches when they are
0139 not longer needed.
0140
0141 *pre_unpatch()*
0142
0143 - Prevent the code, added by the livepatch, relying on the system
0144 state change.
0145
0146 - Revert the system state modification..
0147
0148 *post_unpatch()*
0149
0150 - Distinguish transition reverse and livepatch disabling by
0151 checking *klp_get_prev_state()*.
0152
0153 - In case of transition reverse, restore the previous system
0154 state. It might mean doing nothing.
0155
0156 - Remove any not longer needed setting or data.
0157
0158 .. note::
0159
0160 *pre_unpatch()* typically does symmetric operations to *post_patch()*.
0161 Except that it is called only when the livepatch is being disabled.
0162 Therefore it does not need to care about any previously installed
0163 livepatch.
0164
0165 *post_unpatch()* typically does symmetric operations to *pre_patch()*.
0166 It might be called also during the transition reverse. Therefore it
0167 has to handle the state of the previously installed livepatches.
