docs/devel/reset.rst

   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.