]>
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 | ||
a365572b PM |
14 | The main object types which implement this interface are DeviceClass |
15 | and BusClass. | |
d66cc84c DH |
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 | |
a4a411fb | 22 | the BQL. |
d66cc84c DH |
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 | ||
631f46d4 | 30 | The Resettable interface handles reset types with an enum ``ResetType``: |
d66cc84c DH |
31 | |
32 | ``RESET_TYPE_COLD`` | |
33 | Cold reset is supported by every resettable object. In QEMU, it means we reset | |
34 | to the initial state corresponding to the start of QEMU; this might differ | |
35 | from what is a real hardware cold reset. It differs from other resets (like | |
36 | warm or bus resets) which may keep certain parts untouched. | |
37 | ||
631f46d4 PM |
38 | ``RESET_TYPE_SNAPSHOT_LOAD`` |
39 | This is called for a reset which is being done to put the system into a | |
40 | clean state prior to loading a snapshot. (This corresponds to a reset | |
41 | with ``SHUTDOWN_CAUSE_SNAPSHOT_LOAD``.) Almost all devices should treat | |
42 | this the same as ``RESET_TYPE_COLD``. The main exception is devices which | |
43 | have some non-deterministic state they want to reinitialize to a different | |
44 | value on each cold reset, such as RNG seed information, and which they | |
45 | must not reinitialize on a snapshot-load reset. | |
46 | ||
47 | Devices which implement reset methods must treat any unknown ``ResetType`` | |
48 | as equivalent to ``RESET_TYPE_COLD``; this will reduce the amount of | |
49 | existing code we need to change if we add more types in future. | |
50 | ||
d66cc84c DH |
51 | Calling ``resettable_reset()`` is equivalent to calling |
52 | ``resettable_assert_reset()`` then ``resettable_release_reset()``. It is | |
53 | possible to interleave multiple calls to these three functions. There may | |
54 | be several reset sources/controllers of a given object. The interface handles | |
55 | everything and the different reset controllers do not need to know anything | |
56 | about each others. The object will leave reset state only when each other | |
57 | controllers end their reset operation. This point is handled internally by | |
58 | maintaining a count of in-progress resets; it is crucial to call | |
59 | ``resettable_release_reset()`` one time and only one time per | |
60 | ``resettable_assert_reset()`` call. | |
61 | ||
62 | For now migration of a device or bus in reset is not supported. Care must be | |
63 | taken not to delay ``resettable_release_reset()`` after its | |
64 | ``resettable_assert_reset()`` counterpart. | |
65 | ||
66 | Note that, since resettable is an interface, the API takes a simple Object as | |
67 | parameter. Still, it is a programming error to call a resettable function on a | |
68 | non-resettable object and it will trigger a run time assert error. Since most | |
69 | calls to resettable interface are done through base class functions, such an | |
70 | error is not likely to happen. | |
71 | ||
72 | For Devices and Buses, the following helper functions exist: | |
73 | ||
74 | - ``device_cold_reset()`` | |
75 | - ``bus_cold_reset()`` | |
76 | ||
77 | These are simple wrappers around resettable_reset() function; they only cast the | |
78 | Device or Bus into an Object and pass the cold reset type. When possible | |
79 | prefer to use these functions instead of ``resettable_reset()``. | |
80 | ||
81 | Device and bus functions co-exist because there can be semantic differences | |
82 | between resetting a bus and resetting the controller bridge which owns it. | |
83 | For example, consider a SCSI controller. Resetting the controller puts all | |
84 | its registers back to what reset state was as well as reset everything on the | |
85 | SCSI bus, whereas resetting just the SCSI bus only resets everything that's on | |
86 | it but not the controller. | |
87 | ||
88 | ||
89 | Multi-phase mechanism | |
90 | --------------------- | |
91 | ||
92 | This section documents the internals of the resettable interface. | |
93 | ||
94 | The resettable interface uses a multi-phase system to relieve objects and | |
95 | machines from reset ordering problems. To address this, the reset operation | |
96 | of an object is split into three well defined phases. | |
97 | ||
98 | When resetting several objects (for example the whole machine at simulation | |
99 | startup), all first phases of all objects are executed, then all second phases | |
100 | and then all third phases. | |
101 | ||
102 | The three phases are: | |
103 | ||
104 | 1. The **enter** phase is executed when the object enters reset. It resets only | |
105 | local state of the object; it must not do anything that has a side-effect | |
106 | on other objects, such as raising or lowering a qemu_irq line or reading or | |
107 | writing guest memory. | |
108 | ||
109 | 2. The **hold** phase is executed for entry into reset, once every object in the | |
110 | group which is being reset has had its *enter* phase executed. At this point | |
111 | devices can do actions that affect other objects. | |
112 | ||
113 | 3. The **exit** phase is executed when the object leaves the reset state. | |
114 | Actions affecting other objects are permitted. | |
115 | ||
116 | As said in previous section, the interface maintains a count of reset. This | |
117 | count is used to ensure phases are executed only when required. *enter* and | |
118 | *hold* phases are executed only when asserting reset for the first time | |
119 | (if an object is already in reset state when calling | |
120 | ``resettable_assert_reset()`` or ``resettable_reset()``, they are not | |
121 | executed). | |
122 | The *exit* phase is executed only when the last reset operation ends. Therefore | |
123 | the object does not need to care how many of reset controllers it has and how | |
124 | many of them have started a reset. | |
125 | ||
126 | ||
127 | Handling reset in a resettable object | |
128 | ------------------------------------- | |
129 | ||
130 | This section documents the APIs that an implementation of a resettable object | |
131 | must provide and what functions it has access to. It is intended for people | |
132 | who want to implement or convert a class which has the resettable interface; | |
133 | for example when specializing an existing device or bus. | |
134 | ||
135 | Methods to implement | |
136 | .................... | |
137 | ||
138 | Three methods should be defined or left empty. Each method corresponds to a | |
139 | phase of the reset; they are name ``phases.enter()``, ``phases.hold()`` and | |
140 | ``phases.exit()``. They all take the object as parameter. The *enter* method | |
141 | also take the reset type as second parameter. | |
142 | ||
143 | When extending an existing class, these methods may need to be extended too. | |
144 | The ``resettable_class_set_parent_phases()`` class function may be used to | |
145 | backup parent class methods. | |
146 | ||
147 | Here follows an example to implement reset for a Device which sets an IO while | |
148 | in reset. | |
149 | ||
150 | :: | |
151 | ||
152 | static void mydev_reset_enter(Object *obj, ResetType type) | |
153 | { | |
154 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
155 | MyDevState *mydev = MYDEV(obj); | |
156 | /* call parent class enter phase */ | |
157 | if (myclass->parent_phases.enter) { | |
158 | myclass->parent_phases.enter(obj, type); | |
159 | } | |
160 | /* initialize local state only */ | |
161 | mydev->var = 0; | |
162 | } | |
163 | ||
41d49ec1 | 164 | static void mydev_reset_hold(Object *obj, ResetType type) |
d66cc84c DH |
165 | { |
166 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
167 | MyDevState *mydev = MYDEV(obj); | |
168 | /* call parent class hold phase */ | |
169 | if (myclass->parent_phases.hold) { | |
41d49ec1 | 170 | myclass->parent_phases.hold(obj, type); |
d66cc84c DH |
171 | } |
172 | /* set an IO */ | |
173 | qemu_set_irq(mydev->irq, 1); | |
174 | } | |
175 | ||
41d49ec1 | 176 | static void mydev_reset_exit(Object *obj, ResetType type) |
d66cc84c DH |
177 | { |
178 | MyDevClass *myclass = MYDEV_GET_CLASS(obj); | |
179 | MyDevState *mydev = MYDEV(obj); | |
180 | /* call parent class exit phase */ | |
181 | if (myclass->parent_phases.exit) { | |
41d49ec1 | 182 | myclass->parent_phases.exit(obj, type); |
d66cc84c DH |
183 | } |
184 | /* clear an IO */ | |
185 | qemu_set_irq(mydev->irq, 0); | |
186 | } | |
187 | ||
188 | typedef struct MyDevClass { | |
189 | MyParentClass parent_class; | |
190 | /* to store eventual parent reset methods */ | |
191 | ResettablePhases parent_phases; | |
192 | } MyDevClass; | |
193 | ||
194 | static void mydev_class_init(ObjectClass *class, void *data) | |
195 | { | |
196 | MyDevClass *myclass = MYDEV_CLASS(class); | |
197 | ResettableClass *rc = RESETTABLE_CLASS(class); | |
fa365d05 AO |
198 | resettable_class_set_parent_phases(rc, |
199 | mydev_reset_enter, | |
200 | mydev_reset_hold, | |
201 | mydev_reset_exit, | |
202 | &myclass->parent_phases); | |
d66cc84c DH |
203 | } |
204 | ||
205 | In the above example, we override all three phases. It is possible to override | |
206 | only some of them by passing NULL instead of a function pointer to | |
fa365d05 | 207 | ``resettable_class_set_parent_phases()``. For example, the following will |
d66cc84c DH |
208 | only override the *enter* phase and leave *hold* and *exit* untouched:: |
209 | ||
fa365d05 AO |
210 | resettable_class_set_parent_phases(rc, mydev_reset_enter, NULL, NULL, |
211 | &myclass->parent_phases); | |
d66cc84c DH |
212 | |
213 | This is equivalent to providing a trivial implementation of the hold and exit | |
214 | phases which does nothing but call the parent class's implementation of the | |
215 | phase. | |
216 | ||
217 | Polling the reset state | |
218 | ....................... | |
219 | ||
220 | Resettable interface provides the ``resettable_is_in_reset()`` function. | |
221 | This function returns true if the object parameter is currently under reset. | |
222 | ||
310616d3 DH |
223 | An object is under reset from the beginning of the *enter* phase (before |
224 | either its children or its own enter method is called) to the *exit* | |
225 | phase. During *enter* and *hold* phase only, the function will return that the | |
226 | object is in reset. The state is changed after the *exit* is propagated to | |
227 | its children and just before calling the object's own *exit* method. | |
d66cc84c DH |
228 | |
229 | This function may be used if the object behavior has to be adapted | |
230 | while in reset state. For example if a device has an irq input, | |
231 | it will probably need to ignore it while in reset; then it can for | |
232 | example check the reset state at the beginning of the irq callback. | |
233 | ||
234 | Note that until migration of the reset state is supported, an object | |
235 | should not be left in reset. So apart from being currently executing | |
236 | one of the reset phases, the only cases when this function will return | |
237 | true is if an external interaction (like changing an io) is made during | |
238 | *hold* or *exit* phase of another object in the same reset group. | |
239 | ||
240 | Helpers ``device_is_in_reset()`` and ``bus_is_in_reset()`` are also provided | |
241 | for devices and buses and should be preferred. | |
242 | ||
243 | ||
244 | Base class handling of reset | |
245 | ---------------------------- | |
246 | ||
247 | This section documents parts of the reset mechanism that you only need to know | |
248 | about if you are extending it to work with a new base class other than | |
249 | DeviceClass or BusClass, or maintaining the existing code in those classes. Most | |
250 | people can ignore it. | |
251 | ||
252 | Methods to implement | |
253 | .................... | |
254 | ||
255 | There are two other methods that need to exist in a class implementing the | |
256 | interface: ``get_state()`` and ``child_foreach()``. | |
257 | ||
258 | ``get_state()`` is simple. *resettable* is an interface and, as a consequence, | |
259 | does not have any class state structure. But in order to factorize the code, we | |
260 | need one. This method must return a pointer to ``ResettableState`` structure. | |
261 | The structure must be allocated by the base class; preferably it should be | |
262 | located inside the object instance structure. | |
263 | ||
264 | ``child_foreach()`` is more complex. It should execute the given callback on | |
265 | every reset child of the given resettable object. All children must be | |
266 | resettable too. Additional parameters (a reset type and an opaque pointer) must | |
267 | be passed to the callback too. | |
268 | ||
269 | In ``DeviceClass`` and ``BusClass`` the ``ResettableState`` is located | |
270 | ``DeviceState`` and ``BusState`` structure. ``child_foreach()`` is implemented | |
271 | to follow the bus hierarchy; for a bus, it calls the function on every child | |
272 | device; for a device, it calls the function on every bus child. When we reset | |
273 | the main system bus, we reset the whole machine bus tree. | |
274 | ||
275 | Changing a resettable parent | |
276 | ............................ | |
277 | ||
278 | One thing which should be taken care of by the base class is handling reset | |
279 | hierarchy changes. | |
280 | ||
281 | The reset hierarchy is supposed to be static and built during machine creation. | |
282 | But there are actually some exceptions. To cope with this, the resettable API | |
283 | provides ``resettable_change_parent()``. This function allows to set, update or | |
284 | remove the parent of a resettable object after machine creation is done. As | |
285 | parameters, it takes the object being moved, the old parent if any and the new | |
286 | parent if any. | |
287 | ||
288 | This function can be used at any time when not in a reset operation. During | |
289 | a reset operation it must be used only in *hold* phase. Using it in *enter* or | |
290 | *exit* phase is an error. | |
291 | Also it should not be used during machine creation, although it is harmless to | |
292 | do so: the function is a no-op as long as old and new parent are NULL or not | |
293 | in reset. | |
294 | ||
295 | There is currently 2 cases where this function is used: | |
296 | ||
297 | 1. *device hotplug*; it means a new device is introduced on a live bus. | |
298 | ||
299 | 2. *hot bus change*; it means an existing live device is added, moved or | |
300 | removed in the bus hierarchy. At the moment, it occurs only in the raspi | |
301 | machines for changing the sdbus used by sd card. | |
a365572b PM |
302 | |
303 | Reset of the complete system | |
304 | ---------------------------- | |
305 | ||
306 | Reset of the complete system is a little complicated. The typical | |
307 | flow is: | |
308 | ||
309 | 1. Code which wishes to reset the entire system does so by calling | |
310 | ``qemu_system_reset_request()``. This schedules a reset, but the | |
311 | reset will happen asynchronously after the function returns. | |
312 | That makes this safe to call from, for example, device models. | |
313 | ||
314 | 2. The function which is called to make the reset happen is | |
315 | ``qemu_system_reset()``. Generally only core system code should | |
316 | call this directly. | |
317 | ||
318 | 3. ``qemu_system_reset()`` calls the ``MachineClass::reset`` method of | |
319 | the current machine, if it has one. That method must call | |
320 | ``qemu_devices_reset()``. If the machine has no reset method, | |
321 | ``qemu_system_reset()`` calls ``qemu_devices_reset()`` directly. | |
322 | ||
323 | 4. ``qemu_devices_reset()`` performs a reset of the system, using | |
324 | the three-phase mechanism listed above. It resets all objects | |
325 | that were registered with it using ``qemu_register_resettable()``. | |
326 | It also calls all the functions registered with it using | |
327 | ``qemu_register_reset()``. Those functions are called during the | |
328 | "hold" phase of this reset. | |
329 | ||
330 | 5. The most important object that this reset resets is the | |
331 | 'sysbus' bus. The sysbus bus is the root of the qbus tree. This | |
332 | means that all devices on the sysbus are reset, and all their | |
333 | child buses, and all the devices on those child buses. | |
334 | ||
335 | 6. Devices which are not on the qbus tree are *not* automatically | |
336 | reset! (The most obvious example of this is CPU objects, but | |
337 | anything that directly inherits from ``TYPE_OBJECT`` or ``TYPE_DEVICE`` | |
338 | rather than from ``TYPE_SYS_BUS_DEVICE`` or some other plugs-into-a-bus | |
339 | type will be in this category.) You need to therefore arrange for these | |
340 | to be reset in some other way (e.g. using ``qemu_register_resettable()`` | |
341 | or ``qemu_register_reset()``). |