Commit | Line | Data |
---|---|---|
e553d2a5 PM |
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 | ||
e368cd72 | 55 | - klp_get_state() |
e553d2a5 PM |
56 | |
57 | - Get struct klp_state associated with the given livepatch | |
58 | and state id. | |
59 | ||
e368cd72 | 60 | - klp_get_prev_state() |
e553d2a5 PM |
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. |