1 2======================================= 3Reset in QEMU: the Resettable interface 4======================================= 5 6The reset of qemu objects is handled using the resettable interface declared 7in ``include/hw/resettable.h``. 8 9This interface allows objects to be grouped (on a tree basis); so that the 10whole group can be reset consistently. Each individual member object does not 11have to care about others; in particular, problems of order (which object is 12reset first) are addressed. 13 14The main object types which implement this interface are DeviceClass 15and BusClass. 16 17Triggering reset 18---------------- 19 20This section documents the APIs which "users" of a resettable object should use 21to control it. All resettable control functions must be called while holding 22the BQL. 23 24You can apply a reset to an object using ``resettable_assert_reset()``. You need 25to call ``resettable_release_reset()`` to release the object from reset. To 26instantly reset an object, without keeping it in reset state, just call 27``resettable_reset()``. These functions take two parameters: a pointer to the 28object to reset and a reset type. 29 30The 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 67Devices which implement reset methods must treat any unknown ``ResetType`` 68as equivalent to ``RESET_TYPE_COLD``; this will reduce the amount of 69existing code we need to change if we add more types in future. 70 71Calling ``resettable_reset()`` is equivalent to calling 72``resettable_assert_reset()`` then ``resettable_release_reset()``. It is 73possible to interleave multiple calls to these three functions. There may 74be several reset sources/controllers of a given object. The interface handles 75everything and the different reset controllers do not need to know anything 76about each others. The object will leave reset state only when each other 77controllers end their reset operation. This point is handled internally by 78maintaining 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 82For now migration of a device or bus in reset is not supported. Care must be 83taken not to delay ``resettable_release_reset()`` after its 84``resettable_assert_reset()`` counterpart. 85 86Note that, since resettable is an interface, the API takes a simple Object as 87parameter. Still, it is a programming error to call a resettable function on a 88non-resettable object and it will trigger a run time assert error. Since most 89calls to resettable interface are done through base class functions, such an 90error is not likely to happen. 91 92For Devices and Buses, the following helper functions exist: 93 94- ``device_cold_reset()`` 95- ``bus_cold_reset()`` 96 97These are simple wrappers around resettable_reset() function; they only cast the 98Device or Bus into an Object and pass the cold reset type. When possible 99prefer to use these functions instead of ``resettable_reset()``. 100 101Device and bus functions co-exist because there can be semantic differences 102between resetting a bus and resetting the controller bridge which owns it. 103For example, consider a SCSI controller. Resetting the controller puts all 104its registers back to what reset state was as well as reset everything on the 105SCSI bus, whereas resetting just the SCSI bus only resets everything that's on 106it but not the controller. 107 108 109Multi-phase mechanism 110--------------------- 111 112This section documents the internals of the resettable interface. 113 114The resettable interface uses a multi-phase system to relieve objects and 115machines from reset ordering problems. To address this, the reset operation 116of an object is split into three well defined phases. 117 118When resetting several objects (for example the whole machine at simulation 119startup), all first phases of all objects are executed, then all second phases 120and then all third phases. 121 122The three phases are: 123 1241. 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 1292. 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 1333. The **exit** phase is executed when the object leaves the reset state. 134 Actions affecting other objects are permitted. 135 136As said in previous section, the interface maintains a count of reset. This 137count 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 141executed). 142The *exit* phase is executed only when the last reset operation ends. Therefore 143the object does not need to care how many of reset controllers it has and how 144many of them have started a reset. 145 146DMA capable devices are expected to cancel all outstanding DMA operations 147during either 'enter' or 'hold' phases. IOMMUs are expected to reset during 148the 'exit' phase and this sequencing makes sure no outstanding DMA request 149will fault. 150 151 152Handling reset in a resettable object 153------------------------------------- 154 155This section documents the APIs that an implementation of a resettable object 156must provide and what functions it has access to. It is intended for people 157who want to implement or convert a class which has the resettable interface; 158for example when specializing an existing device or bus. 159 160Methods to implement 161.................... 162 163Three methods should be defined or left empty. Each method corresponds to a 164phase of the reset; they are name ``phases.enter()``, ``phases.hold()`` and 165``phases.exit()``. They all take the object as parameter. The *enter* method 166also take the reset type as second parameter. 167 168When extending an existing class, these methods may need to be extended too. 169The ``resettable_class_set_parent_phases()`` class function may be used to 170backup parent class methods. 171 172Here follows an example to implement reset for a Device which sets an IO while 173in 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, 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 230In the above example, we override all three phases. It is possible to override 231only some of them by passing NULL instead of a function pointer to 232``resettable_class_set_parent_phases()``. For example, the following will 233only 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 238This is equivalent to providing a trivial implementation of the hold and exit 239phases which does nothing but call the parent class's implementation of the 240phase. 241 242Polling the reset state 243....................... 244 245Resettable interface provides the ``resettable_is_in_reset()`` function. 246This function returns true if the object parameter is currently under reset. 247 248An object is under reset from the beginning of the *enter* phase (before 249either its children or its own enter method is called) to the *exit* 250phase. During *enter* and *hold* phase only, the function will return that the 251object is in reset. The state is changed after the *exit* is propagated to 252its children and just before calling the object's own *exit* method. 253 254This function may be used if the object behavior has to be adapted 255while in reset state. For example if a device has an irq input, 256it will probably need to ignore it while in reset; then it can for 257example check the reset state at the beginning of the irq callback. 258 259Note that until migration of the reset state is supported, an object 260should not be left in reset. So apart from being currently executing 261one of the reset phases, the only cases when this function will return 262true 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 265Helpers ``device_is_in_reset()`` and ``bus_is_in_reset()`` are also provided 266for devices and buses and should be preferred. 267 268 269Base class handling of reset 270---------------------------- 271 272This section documents parts of the reset mechanism that you only need to know 273about if you are extending it to work with a new base class other than 274DeviceClass or BusClass, or maintaining the existing code in those classes. Most 275people can ignore it. 276 277Methods to implement 278.................... 279 280There are two other methods that need to exist in a class implementing the 281interface: ``get_state()`` and ``child_foreach()``. 282 283``get_state()`` is simple. *resettable* is an interface and, as a consequence, 284does not have any class state structure. But in order to factorize the code, we 285need one. This method must return a pointer to ``ResettableState`` structure. 286The structure must be allocated by the base class; preferably it should be 287located inside the object instance structure. 288 289``child_foreach()`` is more complex. It should execute the given callback on 290every reset child of the given resettable object. All children must be 291resettable too. Additional parameters (a reset type and an opaque pointer) must 292be passed to the callback too. 293 294In ``DeviceClass`` and ``BusClass`` the ``ResettableState`` is located in the 295``DeviceState`` and ``BusState`` structures. ``child_foreach()`` is implemented 296to follow the bus hierarchy; for a bus, it calls the function on every child 297device; for a device, it calls the function on every bus child. When we reset 298the main system bus, we reset the whole machine bus tree. 299 300Changing a resettable parent 301............................ 302 303One thing which should be taken care of by the base class is handling reset 304hierarchy changes. 305 306The reset hierarchy is supposed to be static and built during machine creation. 307But there are actually some exceptions. To cope with this, the resettable API 308provides ``resettable_change_parent()``. This function allows to set, update or 309remove the parent of a resettable object after machine creation is done. As 310parameters, it takes the object being moved, the old parent if any and the new 311parent if any. 312 313This function can be used at any time when not in a reset operation. During 314a reset operation it must be used only in *hold* phase. Using it in *enter* or 315*exit* phase is an error. 316Also it should not be used during machine creation, although it is harmless to 317do so: the function is a no-op as long as old and new parent are NULL or not 318in reset. 319 320There is currently 2 cases where this function is used: 321 3221. *device hotplug*; it means a new device is introduced on a live bus. 323 3242. *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 328Reset of the complete system 329---------------------------- 330 331Reset of the complete system is a little complicated. The typical 332flow is: 333 3341. 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 3392. 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 3433. ``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 3484. ``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 3555. 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 3606. 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()``). 367