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