]>
Commit | Line | Data |
---|---|---|
074a86fc AL |
1 | #ifndef QDEV_CORE_H |
2 | #define QDEV_CORE_H | |
3 | ||
1de7afc9 | 4 | #include "qemu/queue.h" |
949fc823 | 5 | #include "qemu/bitmap.h" |
2d24a646 ML |
6 | #include "qemu/rcu.h" |
7 | #include "qemu/rcu_queue.h" | |
14cccb61 | 8 | #include "qom/object.h" |
0ee4de6c | 9 | #include "hw/hotplug.h" |
c11256aa | 10 | #include "hw/resettable.h" |
074a86fc | 11 | |
074a86fc AL |
12 | enum { |
13 | DEV_NVECTORS_UNSPECIFIED = -1, | |
14 | }; | |
15 | ||
16 | #define TYPE_DEVICE "device" | |
a489d195 | 17 | OBJECT_DECLARE_TYPE(DeviceState, DeviceClass, DEVICE) |
074a86fc | 18 | |
3d1237fb MA |
19 | typedef enum DeviceCategory { |
20 | DEVICE_CATEGORY_BRIDGE, | |
21 | DEVICE_CATEGORY_USB, | |
22 | DEVICE_CATEGORY_STORAGE, | |
23 | DEVICE_CATEGORY_NETWORK, | |
24 | DEVICE_CATEGORY_INPUT, | |
25 | DEVICE_CATEGORY_DISPLAY, | |
26 | DEVICE_CATEGORY_SOUND, | |
27 | DEVICE_CATEGORY_MISC, | |
ba31cc72 | 28 | DEVICE_CATEGORY_CPU, |
b10cb627 | 29 | DEVICE_CATEGORY_WATCHDOG, |
3d1237fb MA |
30 | DEVICE_CATEGORY_MAX |
31 | } DeviceCategory; | |
32 | ||
249d4172 | 33 | typedef void (*DeviceRealize)(DeviceState *dev, Error **errp); |
b69c3c21 | 34 | typedef void (*DeviceUnrealize)(DeviceState *dev); |
b850f664 | 35 | typedef void (*DeviceReset)(DeviceState *dev); |
02e7f85d | 36 | typedef void (*BusRealize)(BusState *bus, Error **errp); |
b69c3c21 | 37 | typedef void (*BusUnrealize)(BusState *bus); |
074a86fc | 38 | |
249d4172 AF |
39 | /** |
40 | * DeviceClass: | |
41 | * @props: Properties accessing state fields. | |
42 | * @realize: Callback function invoked when the #DeviceState:realized | |
ff46d9d4 | 43 | * property is changed to %true. |
249d4172 AF |
44 | * @unrealize: Callback function invoked when the #DeviceState:realized |
45 | * property is changed to %false. | |
1a37eca1 IM |
46 | * @hotpluggable: indicates if #DeviceClass is hotpluggable, available |
47 | * as readonly "hotpluggable" property of #DeviceState instance | |
249d4172 AF |
48 | * |
49 | * # Realization # | |
50 | * Devices are constructed in two stages, | |
51 | * 1) object instantiation via object_initialize() and | |
52 | * 2) device realization via #DeviceState:realized property. | |
6038f989 TH |
53 | * The former may not fail (and must not abort or exit, since it is called |
54 | * during device introspection already), and the latter may return error | |
55 | * information to the caller and must be re-entrant. | |
249d4172 AF |
56 | * Trivial field initializations should go into #TypeInfo.instance_init. |
57 | * Operations depending on @props static properties should go into @realize. | |
58 | * After successful realization, setting static properties will fail. | |
59 | * | |
daeba969 | 60 | * As an interim step, the #DeviceState:realized property can also be |
c835fac3 | 61 | * set with qdev_realize(). |
249d4172 AF |
62 | * In the future, devices will propagate this state change to their children |
63 | * and along busses they expose. | |
64 | * The point in time will be deferred to machine creation, so that values | |
65 | * set in @realize will not be introspectable beforehand. Therefore devices | |
66 | * must not create children during @realize; they should initialize them via | |
67 | * object_initialize() in their own #TypeInfo.instance_init and forward the | |
68 | * realization events appropriately. | |
69 | * | |
249d4172 | 70 | * Any type may override the @realize and/or @unrealize callbacks but needs |
782beb52 AF |
71 | * to call the parent type's implementation if keeping their functionality |
72 | * is desired. Refer to QOM documentation for further discussion and examples. | |
73 | * | |
74 | * <note> | |
75 | * <para> | |
ff46d9d4 PMD |
76 | * Since TYPE_DEVICE doesn't implement @realize and @unrealize, types |
77 | * derived directly from it need not call their parent's @realize and | |
78 | * @unrealize. | |
782beb52 AF |
79 | * For other types consult the documentation and implementation of the |
80 | * respective parent types. | |
81 | * </para> | |
82 | * </note> | |
f3a85056 JF |
83 | * |
84 | * # Hiding a device # | |
b91ad981 | 85 | * To hide a device, a DeviceListener function hide_device() needs to |
f3a85056 | 86 | * be registered. |
b91ad981 JQ |
87 | * It can be used to defer adding a device and therefore hide it from |
88 | * the guest. The handler registering to this DeviceListener can save | |
89 | * the QOpts passed to it for re-using it later. It must return if it | |
90 | * wants the device to be hidden or visible. When the handler function | |
91 | * decides the device shall be visible it will be added with | |
92 | * qdev_device_add() and realized as any other device. Otherwise | |
93 | * qdev_device_add() will return early without adding the device. The | |
94 | * guest will not see a "hidden" device until it was marked visible | |
95 | * and qdev_device_add called again. | |
f3a85056 | 96 | * |
249d4172 | 97 | */ |
db1015e9 | 98 | struct DeviceClass { |
249d4172 | 99 | /*< private >*/ |
074a86fc | 100 | ObjectClass parent_class; |
249d4172 | 101 | /*< public >*/ |
074a86fc | 102 | |
3d1237fb | 103 | DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX); |
074a86fc AL |
104 | const char *fw_name; |
105 | const char *desc; | |
385d8f22 PB |
106 | |
107 | /* | |
108 | * The underscore at the end ensures a compile-time error if someone | |
109 | * assigns to dc->props instead of using device_class_set_props. | |
110 | */ | |
111 | Property *props_; | |
efec3dd6 MA |
112 | |
113 | /* | |
e90f2a8c | 114 | * Can this device be instantiated with -device / device_add? |
efec3dd6 MA |
115 | * All devices should support instantiation with device_add, and |
116 | * this flag should not exist. But we're not there, yet. Some | |
117 | * devices fail to instantiate with cryptic error messages. | |
118 | * Others instantiate, but don't work. Exposing users to such | |
e90f2a8c EH |
119 | * behavior would be cruel; clearing this flag will protect them. |
120 | * It should never be cleared without a comment explaining why it | |
121 | * is cleared. | |
efec3dd6 MA |
122 | * TODO remove once we're there |
123 | */ | |
e90f2a8c | 124 | bool user_creatable; |
1a37eca1 | 125 | bool hotpluggable; |
074a86fc AL |
126 | |
127 | /* callbacks */ | |
c11256aa DH |
128 | /* |
129 | * Reset method here is deprecated and replaced by methods in the | |
130 | * resettable class interface to implement a multi-phase reset. | |
131 | * TODO: remove once every reset callback is unused | |
132 | */ | |
b850f664 | 133 | DeviceReset reset; |
249d4172 AF |
134 | DeviceRealize realize; |
135 | DeviceUnrealize unrealize; | |
074a86fc AL |
136 | |
137 | /* device state */ | |
8a9358cc | 138 | const VMStateDescription *vmsd; |
074a86fc AL |
139 | |
140 | /* Private to qdev / bus. */ | |
074a86fc | 141 | const char *bus_type; |
db1015e9 | 142 | }; |
074a86fc | 143 | |
a5f54290 PC |
144 | typedef struct NamedGPIOList NamedGPIOList; |
145 | ||
146 | struct NamedGPIOList { | |
147 | char *name; | |
148 | qemu_irq *in; | |
149 | int num_in; | |
a5f54290 PC |
150 | int num_out; |
151 | QLIST_ENTRY(NamedGPIOList) node; | |
152 | }; | |
153 | ||
0e6934f2 DH |
154 | typedef struct Clock Clock; |
155 | typedef struct NamedClockList NamedClockList; | |
156 | ||
157 | struct NamedClockList { | |
158 | char *name; | |
159 | Clock *clock; | |
160 | bool output; | |
161 | bool alias; | |
162 | QLIST_ENTRY(NamedClockList) node; | |
163 | }; | |
164 | ||
7983c8a3 AF |
165 | /** |
166 | * DeviceState: | |
167 | * @realized: Indicates whether the device has been fully constructed. | |
5dae6fad ML |
168 | * When accessed outside big qemu lock, must be accessed with |
169 | * qatomic_load_acquire() | |
c11256aa | 170 | * @reset: ResettableState for the device; handled by Resettable interface. |
7983c8a3 AF |
171 | * |
172 | * This structure should not be accessed directly. We declare it here | |
173 | * so that it can be embedded in individual device state structures. | |
174 | */ | |
074a86fc | 175 | struct DeviceState { |
7983c8a3 | 176 | /*< private >*/ |
074a86fc | 177 | Object parent_obj; |
7983c8a3 | 178 | /*< public >*/ |
074a86fc | 179 | |
163f3847 | 180 | char *id; |
04162f8f | 181 | char *canonical_path; |
7983c8a3 | 182 | bool realized; |
352e8da7 | 183 | bool pending_deleted_event; |
18416c62 | 184 | int64_t pending_deleted_expires_ms; |
f3558b1b | 185 | QDict *opts; |
074a86fc | 186 | int hotplugged; |
a1190ab6 | 187 | bool allow_unplug_during_migration; |
074a86fc | 188 | BusState *parent_bus; |
a5f54290 | 189 | QLIST_HEAD(, NamedGPIOList) gpios; |
0e6934f2 | 190 | QLIST_HEAD(, NamedClockList) clocks; |
074a86fc AL |
191 | QLIST_HEAD(, BusState) child_bus; |
192 | int num_child_bus; | |
193 | int instance_id_alias; | |
194 | int alias_required_for_version; | |
c11256aa | 195 | ResettableState reset; |
074a86fc AL |
196 | }; |
197 | ||
707ff800 PD |
198 | struct DeviceListener { |
199 | void (*realize)(DeviceListener *listener, DeviceState *dev); | |
200 | void (*unrealize)(DeviceListener *listener, DeviceState *dev); | |
f3a85056 | 201 | /* |
b91ad981 JQ |
202 | * This callback is called upon init of the DeviceState and |
203 | * informs qdev if a device should be visible or hidden. We can | |
204 | * hide a failover device depending for example on the device | |
205 | * opts. | |
7d618082 KW |
206 | * |
207 | * On errors, it returns false and errp is set. Device creation | |
208 | * should fail in this case. | |
f3a85056 | 209 | */ |
f3558b1b KW |
210 | bool (*hide_device)(DeviceListener *listener, const QDict *device_opts, |
211 | bool from_json, Error **errp); | |
707ff800 PD |
212 | QTAILQ_ENTRY(DeviceListener) link; |
213 | }; | |
214 | ||
074a86fc | 215 | #define TYPE_BUS "bus" |
8110fa1d EH |
216 | DECLARE_OBJ_CHECKERS(BusState, BusClass, |
217 | BUS, TYPE_BUS) | |
074a86fc AL |
218 | |
219 | struct BusClass { | |
220 | ObjectClass parent_class; | |
221 | ||
222 | /* FIXME first arg should be BusState */ | |
223 | void (*print_dev)(Monitor *mon, DeviceState *dev, int indent); | |
224 | char *(*get_dev_path)(DeviceState *dev); | |
bb755ba4 | 225 | |
074a86fc AL |
226 | /* |
227 | * This callback is used to create Open Firmware device path in accordance | |
228 | * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus | |
229 | * bindings can be found at http://playground.sun.com/1275/bindings/. | |
230 | */ | |
231 | char *(*get_fw_dev_path)(DeviceState *dev); | |
bb755ba4 | 232 | |
dcc20931 | 233 | void (*reset)(BusState *bus); |
bb755ba4 PB |
234 | |
235 | /* | |
236 | * Return whether the device can be added to @bus, | |
237 | * based on the address that was set (via device properties) | |
238 | * before realize. If not, on return @errp contains the | |
239 | * human-readable error message. | |
240 | */ | |
241 | bool (*check_address)(BusState *bus, DeviceState *dev, Error **errp); | |
242 | ||
02e7f85d BD |
243 | BusRealize realize; |
244 | BusUnrealize unrealize; | |
245 | ||
1395af6f FK |
246 | /* maximum devices allowed on the bus, 0: no limit. */ |
247 | int max_dev; | |
61de3676 AG |
248 | /* number of automatically allocated bus ids (e.g. ide.0) */ |
249 | int automatic_ids; | |
074a86fc AL |
250 | }; |
251 | ||
252 | typedef struct BusChild { | |
2d24a646 | 253 | struct rcu_head rcu; |
074a86fc AL |
254 | DeviceState *child; |
255 | int index; | |
256 | QTAILQ_ENTRY(BusChild) sibling; | |
257 | } BusChild; | |
258 | ||
0ee4de6c IM |
259 | #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler" |
260 | ||
074a86fc AL |
261 | /** |
262 | * BusState: | |
27c6ef1b | 263 | * @hotplug_handler: link to a hotplug handler associated with bus. |
c11256aa | 264 | * @reset: ResettableState for the bus; handled by Resettable interface. |
074a86fc AL |
265 | */ |
266 | struct BusState { | |
267 | Object obj; | |
268 | DeviceState *parent; | |
f73480c3 | 269 | char *name; |
0ee4de6c | 270 | HotplugHandler *hotplug_handler; |
074a86fc | 271 | int max_index; |
02e7f85d | 272 | bool realized; |
1518562b | 273 | bool full; |
12b2e9f3 | 274 | int num_children; |
2d24a646 ML |
275 | |
276 | /* | |
277 | * children is a RCU QTAILQ, thus readers must use RCU to access it, | |
278 | * and writers must hold the big qemu lock | |
279 | */ | |
280 | ||
eae3eb3e | 281 | QTAILQ_HEAD(, BusChild) children; |
074a86fc | 282 | QLIST_ENTRY(BusState) sibling; |
c11256aa | 283 | ResettableState reset; |
074a86fc AL |
284 | }; |
285 | ||
9f9260a3 DS |
286 | /** |
287 | * GlobalProperty: | |
b3ce84fe | 288 | * @used: Set to true if property was used when initializing a device. |
92fd453c DDAG |
289 | * @optional: If set to true, GlobalProperty will be skipped without errors |
290 | * if the property doesn't exist. | |
cff8b715 MAL |
291 | * |
292 | * An error is fatal for non-hotplugged devices, when the global is applied. | |
9f9260a3 | 293 | */ |
074a86fc AL |
294 | typedef struct GlobalProperty { |
295 | const char *driver; | |
296 | const char *property; | |
297 | const char *value; | |
b3ce84fe | 298 | bool used; |
92fd453c | 299 | bool optional; |
074a86fc AL |
300 | } GlobalProperty; |
301 | ||
ea9ce893 MAL |
302 | static inline void |
303 | compat_props_add(GPtrArray *arr, | |
304 | GlobalProperty props[], size_t nelem) | |
305 | { | |
306 | int i; | |
307 | for (i = 0; i < nelem; i++) { | |
308 | g_ptr_array_add(arr, (void *)&props[i]); | |
309 | } | |
310 | } | |
311 | ||
074a86fc AL |
312 | /*** Board API. This should go away once we have a machine config file. ***/ |
313 | ||
b51238e2 PM |
314 | /** |
315 | * qdev_new: Create a device on the heap | |
316 | * @name: device type to create (we assert() that this type exists) | |
317 | * | |
318 | * This only allocates the memory and initializes the device state | |
319 | * structure, ready for the caller to set properties if they wish. | |
320 | * The device still needs to be realized. | |
321 | * The returned object has a reference count of 1. | |
322 | */ | |
9940b2cf | 323 | DeviceState *qdev_new(const char *name); |
694804ed | 324 | |
b51238e2 PM |
325 | /** |
326 | * qdev_try_new: Try to create a device on the heap | |
327 | * @name: device type to create | |
328 | * | |
329 | * This is like qdev_new(), except it returns %NULL when type @name | |
330 | * does not exist, rather than asserting. | |
331 | */ | |
9940b2cf | 332 | DeviceState *qdev_try_new(const char *name); |
694804ed | 333 | |
b51238e2 PM |
334 | /** |
335 | * qdev_realize: Realize @dev. | |
336 | * @dev: device to realize | |
337 | * @bus: bus to plug it into (may be NULL) | |
338 | * @errp: pointer to error object | |
339 | * | |
340 | * "Realize" the device, i.e. perform the second phase of device | |
341 | * initialization. | |
342 | * @dev must not be plugged into a bus already. | |
343 | * If @bus, plug @dev into @bus. This takes a reference to @dev. | |
344 | * If @dev has no QOM parent, make one up, taking another reference. | |
345 | * On success, return true. | |
346 | * On failure, store an error through @errp and return false. | |
347 | * | |
348 | * If you created @dev using qdev_new(), you probably want to use | |
349 | * qdev_realize_and_unref() instead. | |
350 | */ | |
9940b2cf | 351 | bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp); |
694804ed | 352 | |
b51238e2 PM |
353 | /** |
354 | * qdev_realize_and_unref: Realize @dev and drop a reference | |
355 | * @dev: device to realize | |
356 | * @bus: bus to plug it into (may be NULL) | |
357 | * @errp: pointer to error object | |
358 | * | |
359 | * Realize @dev and drop a reference. | |
360 | * This is like qdev_realize(), except the caller must hold a | |
361 | * (private) reference, which is dropped on return regardless of | |
362 | * success or failure. Intended use:: | |
363 | * | |
364 | * dev = qdev_new(); | |
365 | * [...] | |
366 | * qdev_realize_and_unref(dev, bus, errp); | |
367 | * | |
368 | * Now @dev can go away without further ado. | |
369 | * | |
370 | * If you are embedding the device into some other QOM device and | |
371 | * initialized it via some variant on object_initialize_child() then | |
372 | * do not use this function, because that family of functions arrange | |
373 | * for the only reference to the child device to be held by the parent | |
374 | * via the child<> property, and so the reference-count-drop done here | |
375 | * would be incorrect. For that use case you want qdev_realize(). | |
376 | */ | |
9940b2cf | 377 | bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); |
694804ed | 378 | |
46ea1be1 PM |
379 | /** |
380 | * qdev_unrealize: Unrealize a device | |
381 | * @dev: device to unrealize | |
382 | * | |
383 | * This function will "unrealize" a device, which is the first phase | |
384 | * of correctly destroying a device that has been realized. It will: | |
385 | * | |
386 | * - unrealize any child buses by calling qbus_unrealize() | |
387 | * (this will recursively unrealize any devices on those buses) | |
388 | * - call the the unrealize method of @dev | |
389 | * | |
390 | * The device can then be freed by causing its reference count to go | |
391 | * to zero. | |
392 | * | |
393 | * Warning: most devices in QEMU do not expect to be unrealized. Only | |
394 | * devices which are hot-unpluggable should be unrealized (as part of | |
395 | * the unplugging process); all other devices are expected to last for | |
396 | * the life of the simulation and should not be unrealized and freed. | |
397 | */ | |
9940b2cf | 398 | void qdev_unrealize(DeviceState *dev); |
074a86fc AL |
399 | void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id, |
400 | int required_for_version); | |
14405c27 | 401 | HotplugHandler *qdev_get_bus_hotplug_handler(DeviceState *dev); |
03fcbd9d | 402 | HotplugHandler *qdev_get_machine_hotplug_handler(DeviceState *dev); |
d2321d31 | 403 | bool qdev_hotplug_allowed(DeviceState *dev, Error **errp); |
17cc0128 IM |
404 | /** |
405 | * qdev_get_hotplug_handler: Get handler responsible for device wiring | |
406 | * | |
407 | * Find HOTPLUG_HANDLER for @dev that provides [pre|un]plug callbacks for it. | |
408 | * | |
409 | * Note: in case @dev has a parent bus, it will be returned as handler unless | |
410 | * machine handler overrides it. | |
411 | * | |
412 | * Returns: pointer to object that implements TYPE_HOTPLUG_HANDLER interface | |
413 | * or NULL if there aren't any. | |
414 | */ | |
c06b2ffb | 415 | HotplugHandler *qdev_get_hotplug_handler(DeviceState *dev); |
074a86fc | 416 | void qdev_unplug(DeviceState *dev, Error **errp); |
014176f9 IM |
417 | void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev, |
418 | DeviceState *dev, Error **errp); | |
074a86fc AL |
419 | void qdev_machine_creation_done(void); |
420 | bool qdev_machine_modified(void); | |
421 | ||
ddb67f64 PMD |
422 | /** |
423 | * GpioPolarity: Polarity of a GPIO line | |
424 | * | |
425 | * GPIO lines use either positive (active-high) logic, | |
426 | * or negative (active-low) logic. | |
427 | * | |
428 | * In active-high logic (%GPIO_POLARITY_ACTIVE_HIGH), a pin is | |
429 | * active when the voltage on the pin is high (relative to ground); | |
430 | * whereas in active-low logic (%GPIO_POLARITY_ACTIVE_LOW), a pin | |
431 | * is active when the voltage on the pin is low (or grounded). | |
432 | */ | |
433 | typedef enum { | |
434 | GPIO_POLARITY_ACTIVE_LOW, | |
435 | GPIO_POLARITY_ACTIVE_HIGH | |
436 | } GpioPolarity; | |
437 | ||
cd07d7f9 PM |
438 | /** |
439 | * qdev_get_gpio_in: Get one of a device's anonymous input GPIO lines | |
440 | * @dev: Device whose GPIO we want | |
441 | * @n: Number of the anonymous GPIO line (which must be in range) | |
442 | * | |
443 | * Returns the qemu_irq corresponding to an anonymous input GPIO line | |
444 | * (which the device has set up with qdev_init_gpio_in()). The index | |
445 | * @n of the GPIO line must be valid (i.e. be at least 0 and less than | |
446 | * the total number of anonymous input GPIOs the device has); this | |
447 | * function will assert() if passed an invalid index. | |
448 | * | |
449 | * This function is intended to be used by board code or SoC "container" | |
450 | * device models to wire up the GPIO lines; usually the return value | |
451 | * will be passed to qdev_connect_gpio_out() or a similar function to | |
452 | * connect another device's output GPIO line to this input. | |
453 | * | |
454 | * For named input GPIO lines, use qdev_get_gpio_in_named(). | |
455 | */ | |
074a86fc | 456 | qemu_irq qdev_get_gpio_in(DeviceState *dev, int n); |
694804ed | 457 | |
cd07d7f9 PM |
458 | /** |
459 | * qdev_get_gpio_in_named: Get one of a device's named input GPIO lines | |
460 | * @dev: Device whose GPIO we want | |
461 | * @name: Name of the input GPIO array | |
462 | * @n: Number of the GPIO line in that array (which must be in range) | |
463 | * | |
464 | * Returns the qemu_irq corresponding to a named input GPIO line | |
465 | * (which the device has set up with qdev_init_gpio_in_named()). | |
466 | * The @name string must correspond to an input GPIO array which exists on | |
467 | * the device, and the index @n of the GPIO line must be valid (i.e. | |
468 | * be at least 0 and less than the total number of input GPIOs in that | |
469 | * array); this function will assert() if passed an invalid name or index. | |
470 | * | |
471 | * For anonymous input GPIO lines, use qdev_get_gpio_in(). | |
472 | */ | |
a5f54290 PC |
473 | qemu_irq qdev_get_gpio_in_named(DeviceState *dev, const char *name, int n); |
474 | ||
cd07d7f9 PM |
475 | /** |
476 | * qdev_connect_gpio_out: Connect one of a device's anonymous output GPIO lines | |
477 | * @dev: Device whose GPIO to connect | |
478 | * @n: Number of the anonymous output GPIO line (which must be in range) | |
2ebd9ce1 | 479 | * @input_pin: qemu_irq to connect the output line to |
cd07d7f9 PM |
480 | * |
481 | * This function connects an anonymous output GPIO line on a device | |
482 | * up to an arbitrary qemu_irq, so that when the device asserts that | |
483 | * output GPIO line, the qemu_irq's callback is invoked. | |
484 | * The index @n of the GPIO line must be valid (i.e. be at least 0 and | |
485 | * less than the total number of anonymous output GPIOs the device has | |
486 | * created with qdev_init_gpio_out()); otherwise this function will assert(). | |
487 | * | |
488 | * Outbound GPIO lines can be connected to any qemu_irq, but the common | |
489 | * case is connecting them to another device's inbound GPIO line, using | |
490 | * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named(). | |
491 | * | |
492 | * It is not valid to try to connect one outbound GPIO to multiple | |
493 | * qemu_irqs at once, or to connect multiple outbound GPIOs to the | |
494 | * same qemu_irq. (Warning: there is no assertion or other guard to | |
495 | * catch this error: the model will just not do the right thing.) | |
5df69ab8 | 496 | * Instead, for fan-out you can use the TYPE_SPLIT_IRQ device: connect |
cd07d7f9 PM |
497 | * a device's outbound GPIO to the splitter's input, and connect each |
498 | * of the splitter's outputs to a different device. For fan-in you | |
499 | * can use the TYPE_OR_IRQ device, which is a model of a logical OR | |
500 | * gate with multiple inputs and one output. | |
501 | * | |
502 | * For named output GPIO lines, use qdev_connect_gpio_out_named(). | |
503 | */ | |
074a86fc | 504 | void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin); |
694804ed | 505 | |
cd07d7f9 | 506 | /** |
1fbd004b PMD |
507 | * qdev_connect_gpio_out_named: Connect one of a device's named output |
508 | * GPIO lines | |
cd07d7f9 PM |
509 | * @dev: Device whose GPIO to connect |
510 | * @name: Name of the output GPIO array | |
511 | * @n: Number of the anonymous output GPIO line (which must be in range) | |
2ebd9ce1 | 512 | * @input_pin: qemu_irq to connect the output line to |
cd07d7f9 PM |
513 | * |
514 | * This function connects an anonymous output GPIO line on a device | |
515 | * up to an arbitrary qemu_irq, so that when the device asserts that | |
516 | * output GPIO line, the qemu_irq's callback is invoked. | |
517 | * The @name string must correspond to an output GPIO array which exists on | |
518 | * the device, and the index @n of the GPIO line must be valid (i.e. | |
519 | * be at least 0 and less than the total number of input GPIOs in that | |
520 | * array); this function will assert() if passed an invalid name or index. | |
521 | * | |
522 | * Outbound GPIO lines can be connected to any qemu_irq, but the common | |
523 | * case is connecting them to another device's inbound GPIO line, using | |
524 | * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named(). | |
525 | * | |
526 | * It is not valid to try to connect one outbound GPIO to multiple | |
527 | * qemu_irqs at once, or to connect multiple outbound GPIOs to the | |
528 | * same qemu_irq; see qdev_connect_gpio_out() for details. | |
529 | * | |
1fbd004b | 530 | * For anonymous output GPIO lines, use qdev_connect_gpio_out(). |
cd07d7f9 | 531 | */ |
a5f54290 | 532 | void qdev_connect_gpio_out_named(DeviceState *dev, const char *name, int n, |
2ebd9ce1 | 533 | qemu_irq input_pin); |
694804ed | 534 | |
cd07d7f9 PM |
535 | /** |
536 | * qdev_get_gpio_out_connector: Get the qemu_irq connected to an output GPIO | |
537 | * @dev: Device whose output GPIO we are interested in | |
538 | * @name: Name of the output GPIO array | |
539 | * @n: Number of the output GPIO line within that array | |
540 | * | |
541 | * Returns whatever qemu_irq is currently connected to the specified | |
542 | * output GPIO line of @dev. This will be NULL if the output GPIO line | |
543 | * has never been wired up to the anything. Note that the qemu_irq | |
544 | * returned does not belong to @dev -- it will be the input GPIO or | |
545 | * IRQ of whichever device the board code has connected up to @dev's | |
546 | * output GPIO. | |
547 | * | |
548 | * You probably don't need to use this function -- it is used only | |
549 | * by the platform-bus subsystem. | |
550 | */ | |
b7973186 | 551 | qemu_irq qdev_get_gpio_out_connector(DeviceState *dev, const char *name, int n); |
694804ed | 552 | |
cd07d7f9 PM |
553 | /** |
554 | * qdev_intercept_gpio_out: Intercept an existing GPIO connection | |
555 | * @dev: Device to intercept the outbound GPIO line from | |
556 | * @icpt: New qemu_irq to connect instead | |
557 | * @name: Name of the output GPIO array | |
558 | * @n: Number of the GPIO line in the array | |
559 | * | |
560 | * This function is provided only for use by the qtest testing framework | |
561 | * and is not suitable for use in non-testing parts of QEMU. | |
562 | * | |
563 | * This function breaks an existing connection of an outbound GPIO | |
564 | * line from @dev, and replaces it with the new qemu_irq @icpt, as if | |
565 | * ``qdev_connect_gpio_out_named(dev, icpt, name, n)`` had been called. | |
566 | * The previously connected qemu_irq is returned, so it can be restored | |
567 | * by a second call to qdev_intercept_gpio_out() if desired. | |
568 | */ | |
0c24db2b PC |
569 | qemu_irq qdev_intercept_gpio_out(DeviceState *dev, qemu_irq icpt, |
570 | const char *name, int n); | |
074a86fc AL |
571 | |
572 | BusState *qdev_get_child_bus(DeviceState *dev, const char *name); | |
573 | ||
574 | /*** Device API. ***/ | |
575 | ||
cd07d7f9 PM |
576 | /** |
577 | * qdev_init_gpio_in: create an array of anonymous input GPIO lines | |
578 | * @dev: Device to create input GPIOs for | |
579 | * @handler: Function to call when GPIO line value is set | |
580 | * @n: Number of GPIO lines to create | |
581 | * | |
582 | * Devices should use functions in the qdev_init_gpio_in* family in | |
583 | * their instance_init or realize methods to create any input GPIO | |
584 | * lines they need. There is no functional difference between | |
585 | * anonymous and named GPIO lines. Stylistically, named GPIOs are | |
586 | * preferable (easier to understand at callsites) unless a device | |
587 | * has exactly one uniform kind of GPIO input whose purpose is obvious. | |
588 | * Note that input GPIO lines can serve as 'sinks' for IRQ lines. | |
589 | * | |
590 | * See qdev_get_gpio_in() for how code that uses such a device can get | |
591 | * hold of an input GPIO line to manipulate it. | |
592 | */ | |
074a86fc | 593 | void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n); |
694804ed | 594 | |
cd07d7f9 PM |
595 | /** |
596 | * qdev_init_gpio_out: create an array of anonymous output GPIO lines | |
597 | * @dev: Device to create output GPIOs for | |
598 | * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines | |
599 | * @n: Number of GPIO lines to create | |
600 | * | |
601 | * Devices should use functions in the qdev_init_gpio_out* family | |
602 | * in their instance_init or realize methods to create any output | |
603 | * GPIO lines they need. There is no functional difference between | |
604 | * anonymous and named GPIO lines. Stylistically, named GPIOs are | |
605 | * preferable (easier to understand at callsites) unless a device | |
606 | * has exactly one uniform kind of GPIO output whose purpose is obvious. | |
607 | * | |
608 | * The @pins argument should be a pointer to either a "qemu_irq" | |
609 | * (if @n == 1) or a "qemu_irq []" array (if @n > 1) in the device's | |
610 | * state structure. The device implementation can then raise and | |
611 | * lower the GPIO line by calling qemu_set_irq(). (If anything is | |
612 | * connected to the other end of the GPIO this will cause the handler | |
613 | * function for that input GPIO to be called.) | |
614 | * | |
615 | * See qdev_connect_gpio_out() for how code that uses such a device | |
616 | * can connect to one of its output GPIO lines. | |
526dc840 PMD |
617 | * |
618 | * There is no need to release the @pins allocated array because it | |
619 | * will be automatically released when @dev calls its instance_finalize() | |
620 | * handler. | |
cd07d7f9 | 621 | */ |
074a86fc | 622 | void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n); |
694804ed | 623 | |
cd07d7f9 | 624 | /** |
14b0375b | 625 | * qdev_init_gpio_out_named: create an array of named output GPIO lines |
cd07d7f9 PM |
626 | * @dev: Device to create output GPIOs for |
627 | * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines | |
628 | * @name: Name to give this array of GPIO lines | |
629 | * @n: Number of GPIO lines to create | |
630 | * | |
631 | * Like qdev_init_gpio_out(), but creates an array of GPIO output lines | |
632 | * with a name. Code using the device can then connect these GPIO lines | |
633 | * using qdev_connect_gpio_out_named(). | |
634 | */ | |
a5f54290 PC |
635 | void qdev_init_gpio_out_named(DeviceState *dev, qemu_irq *pins, |
636 | const char *name, int n); | |
694804ed | 637 | |
4a151677 PM |
638 | /** |
639 | * qdev_init_gpio_in_named_with_opaque: create an array of input GPIO lines | |
640 | * for the specified device | |
641 | * | |
642 | * @dev: Device to create input GPIOs for | |
643 | * @handler: Function to call when GPIO line value is set | |
644 | * @opaque: Opaque data pointer to pass to @handler | |
645 | * @name: Name of the GPIO input (must be unique for this device) | |
646 | * @n: Number of GPIO lines in this input set | |
647 | */ | |
648 | void qdev_init_gpio_in_named_with_opaque(DeviceState *dev, | |
649 | qemu_irq_handler handler, | |
650 | void *opaque, | |
651 | const char *name, int n); | |
652 | ||
653 | /** | |
654 | * qdev_init_gpio_in_named: create an array of input GPIO lines | |
655 | * for the specified device | |
656 | * | |
657 | * Like qdev_init_gpio_in_named_with_opaque(), but the opaque pointer | |
658 | * passed to the handler is @dev (which is the most commonly desired behaviour). | |
659 | */ | |
660 | static inline void qdev_init_gpio_in_named(DeviceState *dev, | |
661 | qemu_irq_handler handler, | |
662 | const char *name, int n) | |
663 | { | |
664 | qdev_init_gpio_in_named_with_opaque(dev, handler, dev, name, n); | |
665 | } | |
074a86fc | 666 | |
cd07d7f9 PM |
667 | /** |
668 | * qdev_pass_gpios: create GPIO lines on container which pass through to device | |
669 | * @dev: Device which has GPIO lines | |
670 | * @container: Container device which needs to expose them | |
671 | * @name: Name of GPIO array to pass through (NULL for the anonymous GPIO array) | |
672 | * | |
673 | * In QEMU, complicated devices like SoCs are often modelled with a | |
674 | * "container" QOM device which itself contains other QOM devices and | |
675 | * which wires them up appropriately. This function allows the container | |
676 | * to create GPIO arrays on itself which simply pass through to a GPIO | |
677 | * array of one of its internal devices. | |
678 | * | |
679 | * If @dev has both input and output GPIOs named @name then both will | |
680 | * be passed through. It is not possible to pass a subset of the array | |
681 | * with this function. | |
682 | * | |
683 | * To users of the container device, the GPIO array created on @container | |
684 | * behaves exactly like any other. | |
685 | */ | |
17a96a14 PC |
686 | void qdev_pass_gpios(DeviceState *dev, DeviceState *container, |
687 | const char *name); | |
688 | ||
074a86fc AL |
689 | BusState *qdev_get_parent_bus(DeviceState *dev); |
690 | ||
691 | /*** BUS API. ***/ | |
692 | ||
693 | DeviceState *qdev_find_recursive(BusState *bus, const char *id); | |
694 | ||
695 | /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */ | |
696 | typedef int (qbus_walkerfn)(BusState *bus, void *opaque); | |
697 | typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque); | |
698 | ||
d637e1dc PM |
699 | void qbus_init(void *bus, size_t size, const char *typename, |
700 | DeviceState *parent, const char *name); | |
9388d170 | 701 | BusState *qbus_new(const char *typename, DeviceState *parent, const char *name); |
9940b2cf MA |
702 | bool qbus_realize(BusState *bus, Error **errp); |
703 | void qbus_unrealize(BusState *bus); | |
704 | ||
074a86fc AL |
705 | /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion, |
706 | * < 0 if either devfn or busfn terminate walk somewhere in cursion, | |
707 | * 0 otherwise. */ | |
0293214b PB |
708 | int qbus_walk_children(BusState *bus, |
709 | qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn, | |
710 | qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn, | |
711 | void *opaque); | |
712 | int qdev_walk_children(DeviceState *dev, | |
713 | qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn, | |
714 | qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn, | |
715 | void *opaque); | |
716 | ||
abb89dbf DH |
717 | /** |
718 | * @qdev_reset_all: | |
719 | * Reset @dev. See @qbus_reset_all() for more details. | |
720 | * | |
721 | * Note: This function is deprecated and will be removed when it becomes unused. | |
722 | * Please use device_cold_reset() now. | |
723 | */ | |
074a86fc | 724 | void qdev_reset_all(DeviceState *dev); |
ff8de075 | 725 | void qdev_reset_all_fn(void *opaque); |
d0508c36 PB |
726 | |
727 | /** | |
728 | * @qbus_reset_all: | |
729 | * @bus: Bus to be reset. | |
730 | * | |
731 | * Reset @bus and perform a bus-level ("hard") reset of all devices connected | |
732 | * to it, including recursive processing of all buses below @bus itself. A | |
733 | * hard reset means that qbus_reset_all will reset all state of the device. | |
734 | * For PCI devices, for example, this will include the base address registers | |
735 | * or configuration space. | |
abb89dbf DH |
736 | * |
737 | * Note: This function is deprecated and will be removed when it becomes unused. | |
738 | * Please use bus_cold_reset() now. | |
d0508c36 PB |
739 | */ |
740 | void qbus_reset_all(BusState *bus); | |
074a86fc AL |
741 | void qbus_reset_all_fn(void *opaque); |
742 | ||
abb89dbf DH |
743 | /** |
744 | * device_cold_reset: | |
745 | * Reset device @dev and perform a recursive processing using the resettable | |
746 | * interface. It triggers a RESET_TYPE_COLD. | |
747 | */ | |
748 | void device_cold_reset(DeviceState *dev); | |
749 | ||
750 | /** | |
751 | * bus_cold_reset: | |
752 | * | |
753 | * Reset bus @bus and perform a recursive processing using the resettable | |
754 | * interface. It triggers a RESET_TYPE_COLD. | |
755 | */ | |
756 | void bus_cold_reset(BusState *bus); | |
757 | ||
c11256aa DH |
758 | /** |
759 | * device_is_in_reset: | |
760 | * Return true if the device @dev is currently being reset. | |
761 | */ | |
762 | bool device_is_in_reset(DeviceState *dev); | |
763 | ||
764 | /** | |
765 | * bus_is_in_reset: | |
766 | * Return true if the bus @bus is currently being reset. | |
767 | */ | |
768 | bool bus_is_in_reset(BusState *bus); | |
769 | ||
074a86fc AL |
770 | /* This should go away once we get rid of the NULL bus hack */ |
771 | BusState *sysbus_get_default(void); | |
772 | ||
773 | char *qdev_get_fw_dev_path(DeviceState *dev); | |
0be63901 | 774 | char *qdev_get_own_fw_dev_path_from_handler(BusState *bus, DeviceState *dev); |
074a86fc | 775 | |
074a86fc | 776 | /** |
f703a04c | 777 | * device_legacy_reset: |
074a86fc AL |
778 | * |
779 | * Reset a single device (by calling the reset method). | |
abb89dbf DH |
780 | * Note: This function is deprecated and will be removed when it becomes unused. |
781 | * Please use device_cold_reset() now. | |
074a86fc | 782 | */ |
f703a04c | 783 | void device_legacy_reset(DeviceState *dev); |
074a86fc | 784 | |
4f67d30b MAL |
785 | void device_class_set_props(DeviceClass *dc, Property *props); |
786 | ||
c11256aa DH |
787 | /** |
788 | * device_class_set_parent_reset: | |
789 | * TODO: remove the function when DeviceClass's reset method | |
790 | * is not used anymore. | |
791 | */ | |
46795cf2 PMD |
792 | void device_class_set_parent_reset(DeviceClass *dc, |
793 | DeviceReset dev_reset, | |
794 | DeviceReset *parent_reset); | |
795 | void device_class_set_parent_realize(DeviceClass *dc, | |
796 | DeviceRealize dev_realize, | |
797 | DeviceRealize *parent_realize); | |
798 | void device_class_set_parent_unrealize(DeviceClass *dc, | |
799 | DeviceUnrealize dev_unrealize, | |
800 | DeviceUnrealize *parent_unrealize); | |
801 | ||
8a9358cc | 802 | const VMStateDescription *qdev_get_vmsd(DeviceState *dev); |
074a86fc AL |
803 | |
804 | const char *qdev_fw_name(DeviceState *dev); | |
805 | ||
f66dc873 | 806 | void qdev_assert_realized_properly(void); |
074a86fc AL |
807 | Object *qdev_get_machine(void); |
808 | ||
809 | /* FIXME: make this a link<> */ | |
bb755ba4 | 810 | bool qdev_set_parent_bus(DeviceState *dev, BusState *bus, Error **errp); |
074a86fc | 811 | |
21def24a | 812 | extern bool qdev_hot_removed; |
074a86fc AL |
813 | |
814 | char *qdev_get_dev_path(DeviceState *dev); | |
815 | ||
9bc6bfdf | 816 | void qbus_set_hotplug_handler(BusState *bus, Object *handler); |
cd7c8660 | 817 | void qbus_set_bus_hotplug_handler(BusState *bus); |
39b888bd IM |
818 | |
819 | static inline bool qbus_is_hotpluggable(BusState *bus) | |
820 | { | |
2d9a982f | 821 | return bus->hotplug_handler; |
39b888bd | 822 | } |
707ff800 | 823 | |
1518562b PM |
824 | /** |
825 | * qbus_mark_full: Mark this bus as full, so no more devices can be attached | |
826 | * @bus: Bus to mark as full | |
827 | * | |
828 | * By default, QEMU will allow devices to be plugged into a bus up | |
829 | * to the bus class's device count limit. Calling this function | |
830 | * marks a particular bus as full, so that no more devices can be | |
831 | * plugged into it. In particular this means that the bus will not | |
832 | * be considered as a candidate for plugging in devices created by | |
833 | * the user on the commandline or via the monitor. | |
834 | * If a machine has multiple buses of a given type, such as I2C, | |
835 | * where some of those buses in the real hardware are used only for | |
836 | * internal devices and some are exposed via expansion ports, you | |
837 | * can use this function to mark the internal-only buses as full | |
838 | * after you have created all their internal devices. Then user | |
839 | * created devices will appear on the expansion-port bus where | |
840 | * guest software expects them. | |
841 | */ | |
842 | static inline void qbus_mark_full(BusState *bus) | |
843 | { | |
844 | bus->full = true; | |
845 | } | |
846 | ||
707ff800 PD |
847 | void device_listener_register(DeviceListener *listener); |
848 | void device_listener_unregister(DeviceListener *listener); | |
849 | ||
f3a85056 JF |
850 | /** |
851 | * @qdev_should_hide_device: | |
f3558b1b KW |
852 | * @opts: options QDict |
853 | * @from_json: true if @opts entries are typed, false for all strings | |
854 | * @errp: pointer to error object | |
f3a85056 JF |
855 | * |
856 | * Check if a device should be added. | |
857 | * When a device is added via qdev_device_add() this will be called, | |
858 | * and return if the device should be added now or not. | |
859 | */ | |
f3558b1b | 860 | bool qdev_should_hide_device(const QDict *opts, bool from_json, Error **errp); |
f3a85056 | 861 | |
2f181fbd PB |
862 | typedef enum MachineInitPhase { |
863 | /* current_machine is NULL. */ | |
864 | PHASE_NO_MACHINE, | |
865 | ||
866 | /* current_machine is not NULL, but current_machine->accel is NULL. */ | |
867 | PHASE_MACHINE_CREATED, | |
868 | ||
869 | /* | |
870 | * current_machine->accel is not NULL, but the machine properties have | |
871 | * not been validated and machine_class->init has not yet been called. | |
872 | */ | |
873 | PHASE_ACCEL_CREATED, | |
874 | ||
875 | /* | |
876 | * machine_class->init has been called, thus creating any embedded | |
877 | * devices and validating machine properties. Devices created at | |
878 | * this time are considered to be cold-plugged. | |
879 | */ | |
880 | PHASE_MACHINE_INITIALIZED, | |
881 | ||
882 | /* | |
883 | * QEMU is ready to start CPUs and devices created at this time | |
884 | * are considered to be hot-plugged. The monitor is not restricted | |
885 | * to "preconfig" commands. | |
886 | */ | |
887 | PHASE_MACHINE_READY, | |
888 | } MachineInitPhase; | |
889 | ||
890 | extern bool phase_check(MachineInitPhase phase); | |
891 | extern void phase_advance(MachineInitPhase phase); | |
892 | ||
074a86fc | 893 | #endif |