]>
Commit | Line | Data |
---|---|---|
d66cc84c DH |
1 | |
2 | ======================================= | |
3 | Reset in QEMU: the Resettable interface | |
4 | ======================================= | |
5 | ||
6 | The reset of qemu objects is handled using the resettable interface declared | |
7 | in ``include/hw/resettable.h``. | |
8 | ||
9 | This interface allows objects to be grouped (on a tree basis); so that the | |
10 | whole group can be reset consistently. Each individual member object does not | |
11 | have to care about others; in particular, problems of order (which object is | |
12 | reset first) are addressed. | |
13 | ||
14 | As of now DeviceClass and BusClass implement this interface. | |
15 | ||
16 | ||
17 | Triggering reset | |
18 | ---------------- | |
19 | ||
20 | This section documents the APIs which "users" of a resettable object should use | |
21 | to control it. All resettable control functions must be called while holding | |
22 | the iothread lock. | |
23 | ||
24 | You can apply a reset to an object using ``resettable_assert_reset()``. You need | |
25 | to call ``resettable_release_reset()`` to release the object from reset. To | |
26 | instantly reset an object, without keeping it in reset state, just call | |
27 | ``resettable_reset()``. These functions take two parameters: a pointer to the | |
28 | object to reset and a reset type. | |
29 | ||
30 | Several types of reset will be supported. For now only cold reset is defined; | |
31 | others may be added later. The Resettable interface handles reset types with an | |
32 | enum: | |
33 | ||
34 | ``RESET_TYPE_COLD`` | |
35 | Cold reset is supported by every resettable object. In QEMU, it means we reset | |
36 | to the initial state corresponding to the start of QEMU; this might differ | |
37 | from what is a real hardware cold reset. It differs from other resets (like | |
38 | warm or bus resets) which may keep certain parts untouched. | |
39 | ||
40 | Calling ``resettable_reset()`` is equivalent to calling | |
41 | ``resettable_assert_reset()`` then ``resettable_release_reset()``. It is | |
42 | possible to interleave multiple calls to these three functions. There may | |
43 | be several reset sources/controllers of a given object. The interface handles | |
44 | everything and the different reset controllers do not need to know anything | |
45 | about each others. The object will leave reset state only when each other | |
46 | controllers end their reset operation. This point is handled internally by | |
47 | maintaining a count of in-progress resets; it is crucial to call | |
48 | ``resettable_release_reset()`` one time and only one time per | |
49 | ``resettable_assert_reset()`` call. | |
50 | ||
51 | For now migration of a device or bus in reset is not supported. Care must be | |
52 | taken not to delay ``resettable_release_reset()`` after its | |
53 | ``resettable_assert_reset()`` counterpart. | |
54 | ||
55 | Note that, since resettable is an interface, the API takes a simple Object as | |
56 | parameter. Still, it is a programming error to call a resettable function on a | |
57 | non-resettable object and it will trigger a run time assert error. Since most | |
58 | calls to resettable interface are done through base class functions, such an | |
59 | error is not likely to happen. | |
60 | ||
61 | For Devices and Buses, the following helper functions exist: | |
62 | ||
63 | - ``device_cold_reset()`` | |
64 | - ``bus_cold_reset()`` | |
65 | ||
66 | These are simple wrappers around resettable_reset() function; they only cast the | |
67 | Device or Bus into an Object and pass the cold reset type. When possible | |
68 | prefer to use these functions instead of ``resettable_reset()``. | |
69 | ||
70 | Device and bus functions co-exist because there can be semantic differences | |
71 | between resetting a bus and resetting the controller bridge which owns it. | |
72 | For example, consider a SCSI controller. Resetting the controller puts all | |
73 | its registers back to what reset state was as well as reset everything on the | |
74 | SCSI bus, whereas resetting just the SCSI bus only resets everything that's on | |
75 | it but not the controller. | |
76 | ||
77 | ||
78 | Multi-phase mechanism | |
79 | --------------------- | |
80 | ||
81 | This section documents the internals of the resettable interface. | |
82 | ||
83 | The resettable interface uses a multi-phase system to relieve objects and | |
84 | machines from reset ordering problems. To address this, the reset operation | |
85 | of an object is split into three well defined phases. | |
86 | ||
87 | When resetting several objects (for example the whole machine at simulation | |
88 | startup), all first phases of all objects are executed, then all second phases | |
89 | and then all third phases. | |
90 | ||
91 | The three phases are: | |
92 | ||
93 | 1. The **enter** phase is executed when the object enters reset. It resets only | |
94 | local state of the object; it must not do anything that has a side-effect | |
95 | on other objects, such as raising or lowering a qemu_irq line or reading or | |
96 | writing guest memory. | |
97 | ||
98 | 2. The **hold** phase is executed for entry into reset, once every object in the | |
99 | group which is being reset has had its *enter* phase executed. At this point | |
100 | devices can do actions that affect other objects. | |
101 | ||
102 | 3. The **exit** phase is executed when the object leaves the reset state. | |
103 | Actions affecting other objects are permitted. | |
104 | ||
105 | As said in previous section, the interface maintains a count of reset. This | |
106 | count is used to ensure phases are executed only when required. *enter* and | |
107 | *hold* phases are executed only when asserting reset for the first time | |
108 | (if an object is already in reset state when calling | |
109 | ``resettable_assert_reset()`` or ``resettable_reset()``, they are not | |
110 | executed). | |
111 | The *exit* phase is executed only when the last reset operation ends. Therefore | |
112 | the object does not need to care how many of reset controllers it has and how | |
113 | many of them have started a reset. | |
114 | ||
115 | ||
116 | Handling reset in a resettable object | |
117 | ------------------------------------- | |
118 | ||
119 | This section documents the APIs that an implementation of a resettable object | |
120 | must provide and what functions it has access to. It is intended for people | |
121 | who want to implement or convert a class which has the resettable interface; | |
122 | for example when specializing an existing device or bus. | |
123 | ||
124 | Methods to implement | |
125 | .................... | |
126 | ||
127 | Three methods should be defined or left empty. Each method corresponds to a | |
128 | phase of the reset; they are name ``phases.enter()``, ``phases.hold()`` and | |
129 | ``phases.exit()``. They all take the object as parameter. The *enter* method | |
130 | also take the reset type as second parameter. | |
131 | ||
132 | When extending an existing class, these methods may need to be extended too. | |
133 | The ``resettable_class_set_parent_phases()`` class function may be used to | |
134 | backup parent class methods. | |
135 | ||
136 | Here follows an example to implement reset for a Device which sets an IO while | |
137 | in reset. | |
138 | ||
139 | :: | |
140 | ||
141 | static void mydev_reset_enter(Object *obj, ResetType type) | |
142 | { | |
143 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
144 | MyDevState *mydev = MYDEV(obj); | |
145 | /* call parent class enter phase */ | |
146 | if (myclass->parent_phases.enter) { | |
147 | myclass->parent_phases.enter(obj, type); | |
148 | } | |
149 | /* initialize local state only */ | |
150 | mydev->var = 0; | |
151 | } | |
152 | ||
153 | static void mydev_reset_hold(Object *obj) | |
154 | { | |
155 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
156 | MyDevState *mydev = MYDEV(obj); | |
157 | /* call parent class hold phase */ | |
158 | if (myclass->parent_phases.hold) { | |
159 | myclass->parent_phases.hold(obj); | |
160 | } | |
161 | /* set an IO */ | |
162 | qemu_set_irq(mydev->irq, 1); | |
163 | } | |
164 | ||
165 | static void mydev_reset_exit(Object *obj) | |
166 | { | |
167 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
168 | MyDevState *mydev = MYDEV(obj); | |
169 | /* call parent class exit phase */ | |
170 | if (myclass->parent_phases.exit) { | |
171 | myclass->parent_phases.exit(obj); | |
172 | } | |
173 | /* clear an IO */ | |
174 | qemu_set_irq(mydev->irq, 0); | |
175 | } | |
176 | ||
177 | typedef struct MyDevClass { | |
178 | MyParentClass parent_class; | |
179 | /* to store eventual parent reset methods */ | |
180 | ResettablePhases parent_phases; | |
181 | } MyDevClass; | |
182 | ||
183 | static void mydev_class_init(ObjectClass *class, void *data) | |
184 | { | |
185 | MyDevClass *myclass = MYDEV_CLASS(class); | |
186 | ResettableClass *rc = RESETTABLE_CLASS(class); | |
187 | resettable_class_set_parent_reset_phases(rc, | |
188 | mydev_reset_enter, | |
189 | mydev_reset_hold, | |
190 | mydev_reset_exit, | |
191 | &myclass->parent_phases); | |
192 | } | |
193 | ||
194 | In the above example, we override all three phases. It is possible to override | |
195 | only some of them by passing NULL instead of a function pointer to | |
196 | ``resettable_class_set_parent_reset_phases()``. For example, the following will | |
197 | only override the *enter* phase and leave *hold* and *exit* untouched:: | |
198 | ||
199 | resettable_class_set_parent_reset_phases(rc, mydev_reset_enter, | |
200 | NULL, NULL, | |
201 | &myclass->parent_phases); | |
202 | ||
203 | This is equivalent to providing a trivial implementation of the hold and exit | |
204 | phases which does nothing but call the parent class's implementation of the | |
205 | phase. | |
206 | ||
207 | Polling the reset state | |
208 | ....................... | |
209 | ||
210 | Resettable interface provides the ``resettable_is_in_reset()`` function. | |
211 | This function returns true if the object parameter is currently under reset. | |
212 | ||
213 | An object is under reset from the beginning of the *init* phase to the end of | |
214 | the *exit* phase. During all three phases, the function will return that the | |
215 | object is in reset. | |
216 | ||
217 | This function may be used if the object behavior has to be adapted | |
218 | while in reset state. For example if a device has an irq input, | |
219 | it will probably need to ignore it while in reset; then it can for | |
220 | example check the reset state at the beginning of the irq callback. | |
221 | ||
222 | Note that until migration of the reset state is supported, an object | |
223 | should not be left in reset. So apart from being currently executing | |
224 | one of the reset phases, the only cases when this function will return | |
225 | true is if an external interaction (like changing an io) is made during | |
226 | *hold* or *exit* phase of another object in the same reset group. | |
227 | ||
228 | Helpers ``device_is_in_reset()`` and ``bus_is_in_reset()`` are also provided | |
229 | for devices and buses and should be preferred. | |
230 | ||
231 | ||
232 | Base class handling of reset | |
233 | ---------------------------- | |
234 | ||
235 | This section documents parts of the reset mechanism that you only need to know | |
236 | about if you are extending it to work with a new base class other than | |
237 | DeviceClass or BusClass, or maintaining the existing code in those classes. Most | |
238 | people can ignore it. | |
239 | ||
240 | Methods to implement | |
241 | .................... | |
242 | ||
243 | There are two other methods that need to exist in a class implementing the | |
244 | interface: ``get_state()`` and ``child_foreach()``. | |
245 | ||
246 | ``get_state()`` is simple. *resettable* is an interface and, as a consequence, | |
247 | does not have any class state structure. But in order to factorize the code, we | |
248 | need one. This method must return a pointer to ``ResettableState`` structure. | |
249 | The structure must be allocated by the base class; preferably it should be | |
250 | located inside the object instance structure. | |
251 | ||
252 | ``child_foreach()`` is more complex. It should execute the given callback on | |
253 | every reset child of the given resettable object. All children must be | |
254 | resettable too. Additional parameters (a reset type and an opaque pointer) must | |
255 | be passed to the callback too. | |
256 | ||
257 | In ``DeviceClass`` and ``BusClass`` the ``ResettableState`` is located | |
258 | ``DeviceState`` and ``BusState`` structure. ``child_foreach()`` is implemented | |
259 | to follow the bus hierarchy; for a bus, it calls the function on every child | |
260 | device; for a device, it calls the function on every bus child. When we reset | |
261 | the main system bus, we reset the whole machine bus tree. | |
262 | ||
263 | Changing a resettable parent | |
264 | ............................ | |
265 | ||
266 | One thing which should be taken care of by the base class is handling reset | |
267 | hierarchy changes. | |
268 | ||
269 | The reset hierarchy is supposed to be static and built during machine creation. | |
270 | But there are actually some exceptions. To cope with this, the resettable API | |
271 | provides ``resettable_change_parent()``. This function allows to set, update or | |
272 | remove the parent of a resettable object after machine creation is done. As | |
273 | parameters, it takes the object being moved, the old parent if any and the new | |
274 | parent if any. | |
275 | ||
276 | This function can be used at any time when not in a reset operation. During | |
277 | a reset operation it must be used only in *hold* phase. Using it in *enter* or | |
278 | *exit* phase is an error. | |
279 | Also it should not be used during machine creation, although it is harmless to | |
280 | do so: the function is a no-op as long as old and new parent are NULL or not | |
281 | in reset. | |
282 | ||
283 | There is currently 2 cases where this function is used: | |
284 | ||
285 | 1. *device hotplug*; it means a new device is introduced on a live bus. | |
286 | ||
287 | 2. *hot bus change*; it means an existing live device is added, moved or | |
288 | removed in the bus hierarchy. At the moment, it occurs only in the raspi | |
289 | machines for changing the sdbus used by sd card. |