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