docs/devel/reset.rst

3 Reset in QEMU: the Resettable interface
6 The reset of qemu objects is handled using the resettable interface declared
10 whole group can be reset consistently. Each individual member object does not
12 reset first) are addressed.
17 Triggering reset
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
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
35   from what is a real hardware cold reset. It differs from other resets (like
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
44   value on each cold reset, such as RNG seed information, and which they
45   must not reinitialize on a snapshot-load reset.
48   If the machine supports waking up from a suspended state and needs to reset
50   reset type should be used for such a request. Devices can utilize this reset
51   type to differentiate the reset requested during machine wake-up from other
52   reset requests. For example, RAM content must not be lost during wake-up, and
53   memory devices like virtio-mem that provide additional RAM must not reset
55   reset type should not be used for wake-up detection, as not every machine
56   type issues a device reset request during wake-up.
67 Devices which implement reset methods must treat any unknown ``ResetType``
74 be several reset sources/controllers of a given object. The interface handles
75 everything and the different reset controllers do not need to know anything
76 about each others. The object will leave reset state only when each other
77 controllers end their reset operation. This point is handled internally by
82 For now migration of a device or bus in reset is not supported. Care must be
98 Device or Bus into an Object and pass the cold reset type. When possible
104 its registers back to what reset state was as well as reset everything on the
115 machines from reset ordering problems. To address this, the reset operation
124 1. The **enter** phase is executed when the object enters reset. It resets only
129 2. The **hold** phase is executed for entry into reset, once every object in the
130    group which is being reset has had its *enter* phase executed. At this point
133 3. The **exit** phase is executed when the object leaves the reset state.
136 As said in previous section, the interface maintains a count of reset. This
138 *hold* phases are executed only when asserting reset for the first time
139 (if an object is already in reset state when calling
142 The *exit* phase is executed only when the last reset operation ends. Therefore
143 the object does not need to care how many of reset controllers it has and how
144 many of them have started a reset.
147 Handling reset in a resettable object
159 phase of the reset; they are name ``phases.enter()``, ``phases.hold()`` and
161 also take the reset type as second parameter.
167 Here follows an example to implement reset for a Device which sets an IO while
168 in reset.
210         /* to store eventual parent reset methods */
237 Polling the reset state
241 This function returns true if the object parameter is currently under reset.
243 An object is under reset from the beginning of the *enter* phase (before
246 object is in reset. The state is changed after the *exit* is propagated to
250 while in reset state. For example if a device has an irq input,
251 it will probably need to ignore it while in reset; then it can for
252 example check the reset state at the beginning of the irq callback.
254 Note that until migration of the reset state is supported, an object
255 should not be left in reset. So apart from being currently executing
256 one of the reset phases, the only cases when this function will return
258 *hold* or *exit* phase of another object in the same reset group.
264 Base class handling of reset
267 This section documents parts of the reset mechanism that you only need to know
285 every reset child of the given resettable object. All children must be
286 resettable too. Additional parameters (a reset type and an opaque pointer) must
292 device; for a device, it calls the function on every bus child. When we reset
293 the main system bus, we reset the whole machine bus tree.
298 One thing which should be taken care of by the base class is handling reset
301 The reset hierarchy is supposed to be static and built during machine creation.
308 This function can be used at any time when not in a reset operation. During
309 a reset operation it must be used only in *hold* phase. Using it in *enter* or
313 in reset.
323 Reset of the complete system
326 Reset of the complete system is a little complicated. The typical
329 1. Code which wishes to reset the entire system does so by calling
330    ``qemu_system_reset_request()``. This schedules a reset, but the
331    reset will happen asynchronously after the function returns.
334 2. The function which is called to make the reset happen is
338 3. ``qemu_system_reset()`` calls the ``MachineClass::reset`` method of
340    ``qemu_devices_reset()``. If the machine has no reset method,
343 4. ``qemu_devices_reset()`` performs a reset of the system, using
348    "hold" phase of this reset.
350 5. The most important object that this reset resets is the
352    means that all devices on the sysbus are reset, and all their
356    reset! (The most obvious example of this is CPU objects, but
360    to be reset in some other way (e.g. using ``qemu_register_resettable()``