reset.rst (12633B)
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 *enter* phase (before 214 either its children or its own enter method is called) to the *exit* 215 phase. During *enter* and *hold* phase only, the function will return that the 216 object is in reset. The state is changed after the *exit* is propagated to 217 its children and just before calling the object's own *exit* method. 218 219 This function may be used if the object behavior has to be adapted 220 while in reset state. For example if a device has an irq input, 221 it will probably need to ignore it while in reset; then it can for 222 example check the reset state at the beginning of the irq callback. 223 224 Note that until migration of the reset state is supported, an object 225 should not be left in reset. So apart from being currently executing 226 one of the reset phases, the only cases when this function will return 227 true is if an external interaction (like changing an io) is made during 228 *hold* or *exit* phase of another object in the same reset group. 229 230 Helpers ``device_is_in_reset()`` and ``bus_is_in_reset()`` are also provided 231 for devices and buses and should be preferred. 232 233 234 Base class handling of reset 235 ---------------------------- 236 237 This section documents parts of the reset mechanism that you only need to know 238 about if you are extending it to work with a new base class other than 239 DeviceClass or BusClass, or maintaining the existing code in those classes. Most 240 people can ignore it. 241 242 Methods to implement 243 .................... 244 245 There are two other methods that need to exist in a class implementing the 246 interface: ``get_state()`` and ``child_foreach()``. 247 248 ``get_state()`` is simple. *resettable* is an interface and, as a consequence, 249 does not have any class state structure. But in order to factorize the code, we 250 need one. This method must return a pointer to ``ResettableState`` structure. 251 The structure must be allocated by the base class; preferably it should be 252 located inside the object instance structure. 253 254 ``child_foreach()`` is more complex. It should execute the given callback on 255 every reset child of the given resettable object. All children must be 256 resettable too. Additional parameters (a reset type and an opaque pointer) must 257 be passed to the callback too. 258 259 In ``DeviceClass`` and ``BusClass`` the ``ResettableState`` is located 260 ``DeviceState`` and ``BusState`` structure. ``child_foreach()`` is implemented 261 to follow the bus hierarchy; for a bus, it calls the function on every child 262 device; for a device, it calls the function on every bus child. When we reset 263 the main system bus, we reset the whole machine bus tree. 264 265 Changing a resettable parent 266 ............................ 267 268 One thing which should be taken care of by the base class is handling reset 269 hierarchy changes. 270 271 The reset hierarchy is supposed to be static and built during machine creation. 272 But there are actually some exceptions. To cope with this, the resettable API 273 provides ``resettable_change_parent()``. This function allows to set, update or 274 remove the parent of a resettable object after machine creation is done. As 275 parameters, it takes the object being moved, the old parent if any and the new 276 parent if any. 277 278 This function can be used at any time when not in a reset operation. During 279 a reset operation it must be used only in *hold* phase. Using it in *enter* or 280 *exit* phase is an error. 281 Also it should not be used during machine creation, although it is harmless to 282 do so: the function is a no-op as long as old and new parent are NULL or not 283 in reset. 284 285 There is currently 2 cases where this function is used: 286 287 1. *device hotplug*; it means a new device is introduced on a live bus. 288 289 2. *hot bus change*; it means an existing live device is added, moved or 290 removed in the bus hierarchy. At the moment, it occurs only in the raspi 291 machines for changing the sdbus used by sd card.