docs/devel/reset.rst

18 ----------------
43   have some non-deterministic state they want to reinitialize to a different
45   must not reinitialize on a snapshot-load reset.
49   its devices during wake-up (from the ``MachineClass::wakeup()`` method), this
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
54   such state during wake-ups, but might do so during cold resets. However, this
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.
78 maintaining a count of in-progress resets; it is crucial to call
87 parameter. Still, it is a programming error to call a resettable function on a
88 non-resettable object and it will trigger a run time assert error. Since most
94 - ``device_cold_reset()``
95 - ``bus_cold_reset()``
97 These are simple wrappers around resettable_reset() function; they only cast the
101 Device and bus functions co-exist because there can be semantic differences
109 Multi-phase mechanism
110 ---------------------
114 The resettable interface uses a multi-phase system to relieve objects and
125    local state of the object; it must not do anything that has a side-effect
153 -------------------------------------
169 The ``resettable_class_set_parent_phases()`` class function may be used to
182         if (myclass->parent_phases.enter) {
183             myclass->parent_phases.enter(obj, type);
186         mydev->var = 0;
194         if (myclass->parent_phases.hold) {
195             myclass->parent_phases.hold(obj, type);
198         qemu_set_irq(mydev->irq, 1);
206         if (myclass->parent_phases.exit) {
207             myclass->parent_phases.exit(obj, type);
210         qemu_set_irq(mydev->irq, 0);
227                                            &myclass->parent_phases);
231 only some of them by passing NULL instead of a function pointer to
236                                        &myclass->parent_phases);
245 Resettable interface provides the ``resettable_is_in_reset()`` function.
246 This function returns true if the object parameter is currently under reset.
250 phase. During *enter* and *hold* phase only, the function will return that the
254 This function may be used if the object behavior has to be adapted
261 one of the reset phases, the only cases when this function will return
270 ----------------------------
296 to follow the bus hierarchy; for a bus, it calls the function on every child
297 device; for a device, it calls the function on every bus child. When we reset
308 provides ``resettable_change_parent()``. This function allows to set, update or
313 This function can be used at any time when not in a reset operation. During
317 do so: the function is a no-op as long as old and new parent are NULL or not
320 There is currently 2 cases where this function is used:
329 ----------------------------
336    reset will happen asynchronously after the function returns.
339 2. The function which is called to make the reset happen is
349    the three-phase mechanism listed above. It resets all objects
363    rather than from ``TYPE_SYS_BUS_DEVICE`` or some other plugs-into-a-bus