2 =======================================
3 Reset in QEMU: the Resettable interface
4 =======================================
6 The reset of qemu objects is handled using the resettable interface declared
7 in ``include/hw/resettable.h``.
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.
14 The main object types which implement this interface are DeviceClass
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
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.
30 The Resettable interface handles reset types with an enum ``ResetType``:
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.
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.
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.
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.
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.
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.
72 For Devices and Buses, the following helper functions exist:
74 - ``device_cold_reset()``
75 - ``bus_cold_reset()``
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()``.
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.
92 This section documents the internals of the resettable interface.
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.
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.
102 The three phases are:
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.
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.
113 3. The **exit** phase is executed when the object leaves the reset state.
114 Actions affecting other objects are permitted.
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
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.
127 Handling reset in a resettable object
128 -------------------------------------
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.
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.
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.
147 Here follows an example to implement reset for a Device which sets an IO while
152 static void mydev_reset_enter(Object *obj, ResetType type)
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);
160 /* initialize local state only */
164 static void mydev_reset_hold(Object *obj, ResetType type)
166 MyDevClass *myclass = MYDEV_GET_CLASS(obj);
167 MyDevState *mydev = MYDEV(obj);
168 /* call parent class hold phase */
169 if (myclass->parent_phases.hold) {
170 myclass->parent_phases.hold(obj, type);
173 qemu_set_irq(mydev->irq, 1);
176 static void mydev_reset_exit(Object *obj, ResetType type)
178 MyDevClass *myclass = MYDEV_GET_CLASS(obj);
179 MyDevState *mydev = MYDEV(obj);
180 /* call parent class exit phase */
181 if (myclass->parent_phases.exit) {
182 myclass->parent_phases.exit(obj, type);
185 qemu_set_irq(mydev->irq, 0);
188 typedef struct MyDevClass {
189 MyParentClass parent_class;
190 /* to store eventual parent reset methods */
191 ResettablePhases parent_phases;
194 static void mydev_class_init(ObjectClass *class, void *data)
196 MyDevClass *myclass = MYDEV_CLASS(class);
197 ResettableClass *rc = RESETTABLE_CLASS(class);
198 resettable_class_set_parent_phases(rc,
202 &myclass->parent_phases);
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
207 ``resettable_class_set_parent_phases()``. For example, the following will
208 only override the *enter* phase and leave *hold* and *exit* untouched::
210 resettable_class_set_parent_phases(rc, mydev_reset_enter, NULL, NULL,
211 &myclass->parent_phases);
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
217 Polling the reset state
218 .......................
220 Resettable interface provides the ``resettable_is_in_reset()`` function.
221 This function returns true if the object parameter is currently under reset.
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.
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.
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.
240 Helpers ``device_is_in_reset()`` and ``bus_is_in_reset()`` are also provided
241 for devices and buses and should be preferred.
244 Base class handling of reset
245 ----------------------------
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.
255 There are two other methods that need to exist in a class implementing the
256 interface: ``get_state()`` and ``child_foreach()``.
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.
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.
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.
275 Changing a resettable parent
276 ............................
278 One thing which should be taken care of by the base class is handling reset
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
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
295 There is currently 2 cases where this function is used:
297 1. *device hotplug*; it means a new device is introduced on a live bus.
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.
303 Reset of the complete system
304 ----------------------------
306 Reset of the complete system is a little complicated. The typical
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.
314 2. The function which is called to make the reset happen is
315 ``qemu_system_reset()``. Generally only core system code should
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.
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.
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.
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()``).