1====================
2System State Changes
3====================
4
5Some users are really reluctant to reboot a system. This brings the need
6to provide more livepatches and maintain some compatibility between them.
7
8Maintaining more livepatches is much easier with cumulative livepatches.
9Each new livepatch completely replaces any older one. It can keep,
10add, and even remove fixes. And it is typically safe to replace any version
11of the livepatch with any other one thanks to the atomic replace feature.
12
13The problems might come with shadow variables and callbacks. They might
14change the system behavior or state so that it is no longer safe to
15go back and use an older livepatch or the original kernel code. Also
16any new livepatch must be able to detect what changes have already been
17done by the already installed livepatches.
18
19This is where the livepatch system state tracking gets useful. It
20allows 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
281. Livepatch system state API
29=============================
30
31The state of the system might get modified either by several livepatch callbacks
32or by the newly used code. Also it must be possible to find changes done by
33already installed livepatches.
34
35Each modified state is described by struct klp_state, see
36include/linux/livepatch.h.
37
38Each livepatch defines an array of struct klp_states. They mention
39all states that the livepatch modifies.
40
41The livepatch author must define the following two fields for each
42struct 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
53The 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
652. Livepatch compatibility
66==========================
67
68The system state version is used to prevent loading incompatible livepatches.
69The 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
823. Supported scenarios
83======================
84
85Livepatches have their life-cycle and the same is true for the system
86state changes. Every compatible livepatch has to support the following
87scenarios:
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
1054. Expected usage
106=================
107
108System states are usually modified by livepatch callbacks. The expected
109role 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.
168