Orange Pi5 kernel

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