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