qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
docs/devel/reset.rst: add doc about Resettable interface
Signed-off-by: Damien Hedde <damien.hedde@greensocs.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200123132823.1117486-10-damien.hedde@greensocs.com
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
authored by
Damien Hedde
and committed by
Peter Maydell
d66cc84c
abb89dbf
+290
+289
docs/devel/reset.rst
+289
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.