1 #ifndef QDEV_CORE_H
2 #define QDEV_CORE_H
3
4 #include "qemu/atomic.h"
5 #include "qemu/queue.h"
6 #include "qemu/bitmap.h"
7 #include "qemu/rcu.h"
8 #include "qemu/rcu_queue.h"
9 #include "qom/object.h"
10 #include "hw/hotplug.h"
11 #include "hw/resettable.h"
12
13 /**
14 * DOC: The QEMU Device API
15 *
16 * All modern devices should represented as a derived QOM class of
17 * TYPE_DEVICE. The device API introduces the additional methods of
18 * @realize and @unrealize to represent additional stages in a device
19 * objects life cycle.
20 *
21 * Realization
22 * -----------
23 *
24 * Devices are constructed in two stages:
25 *
26 * 1) object instantiation via object_initialize() and
27 * 2) device realization via the #DeviceState.realized property
28 *
29 * The former may not fail (and must not abort or exit, since it is called
30 * during device introspection already), and the latter may return error
31 * information to the caller and must be re-entrant.
32 * Trivial field initializations should go into #TypeInfo.instance_init.
33 * Operations depending on @props static properties should go into @realize.
34 * After successful realization, setting static properties will fail.
35 *
36 * As an interim step, the #DeviceState.realized property can also be
37 * set with qdev_realize(). In the future, devices will propagate this
38 * state change to their children and along busses they expose. The
39 * point in time will be deferred to machine creation, so that values
40 * set in @realize will not be introspectable beforehand. Therefore
41 * devices must not create children during @realize; they should
42 * initialize them via object_initialize() in their own
43 * #TypeInfo.instance_init and forward the realization events
44 * appropriately.
45 *
46 * Any type may override the @realize and/or @unrealize callbacks but needs
47 * to call the parent type's implementation if keeping their functionality
48 * is desired. Refer to QOM documentation for further discussion and examples.
49 *
50 * .. note::
51 * Since TYPE_DEVICE doesn't implement @realize and @unrealize, types
52 * derived directly from it need not call their parent's @realize and
53 * @unrealize. For other types consult the documentation and
54 * implementation of the respective parent types.
55 *
56 * Hiding a device
57 * ---------------
58 *
59 * To hide a device, a DeviceListener function hide_device() needs to
60 * be registered. It can be used to defer adding a device and
61 * therefore hide it from the guest. The handler registering to this
62 * DeviceListener can save the QOpts passed to it for re-using it
63 * later. It must return if it wants the device to be hidden or
64 * visible. When the handler function decides the device shall be
65 * visible it will be added with qdev_device_add() and realized as any
66 * other device. Otherwise qdev_device_add() will return early without
67 * adding the device. The guest will not see a "hidden" device until
68 * it was marked visible and qdev_device_add called again.
69 *
70 */
71
72 enum {
73 DEV_NVECTORS_UNSPECIFIED = -1,
74 };
75
76 #define TYPE_DEVICE "device"
77 OBJECT_DECLARE_TYPE(DeviceState, DeviceClass, DEVICE)
78
79 typedef enum DeviceCategory {
80 DEVICE_CATEGORY_BRIDGE,
81 DEVICE_CATEGORY_USB,
82 DEVICE_CATEGORY_STORAGE,
83 DEVICE_CATEGORY_NETWORK,
84 DEVICE_CATEGORY_INPUT,
85 DEVICE_CATEGORY_DISPLAY,
86 DEVICE_CATEGORY_SOUND,
87 DEVICE_CATEGORY_MISC,
88 DEVICE_CATEGORY_CPU,
89 DEVICE_CATEGORY_WATCHDOG,
90 DEVICE_CATEGORY_MAX
91 } DeviceCategory;
92
93 typedef void (*DeviceRealize)(DeviceState *dev, Error **errp);
94 typedef void (*DeviceUnrealize)(DeviceState *dev);
95 typedef void (*DeviceReset)(DeviceState *dev);
96 typedef void (*BusRealize)(BusState *bus, Error **errp);
97 typedef void (*BusUnrealize)(BusState *bus);
98
99 /**
100 * struct DeviceClass - The base class for all devices.
101 * @props: Properties accessing state fields.
102 * @realize: Callback function invoked when the #DeviceState:realized
103 * property is changed to %true.
104 * @unrealize: Callback function invoked when the #DeviceState:realized
105 * property is changed to %false.
106 * @hotpluggable: indicates if #DeviceClass is hotpluggable, available
107 * as readonly "hotpluggable" property of #DeviceState instance
108 *
109 */
110 struct DeviceClass {
111 /* private: */
112 ObjectClass parent_class;
113
114 /* public: */
115
116 /**
117 * @categories: device categories device belongs to
118 */
119 DECLARE_BITMAP(categories, DEVICE_CATEGORY_MAX);
120 /**
121 * @fw_name: name used to identify device to firmware interfaces
122 */
123 const char *fw_name;
124 /**
125 * @desc: human readable description of device
126 */
127 const char *desc;
128
129 /**
130 * @props_: properties associated with device, should only be
131 * assigned by using device_class_set_props(). The underscore
132 * ensures a compile-time error if someone attempts to assign
133 * dc->props directly.
134 */
135 Property *props_;
136
137 /**
138 * @user_creatable: Can user instantiate with -device / device_add?
139 *
140 * All devices should support instantiation with device_add, and
141 * this flag should not exist. But we're not there, yet. Some
142 * devices fail to instantiate with cryptic error messages.
143 * Others instantiate, but don't work. Exposing users to such
144 * behavior would be cruel; clearing this flag will protect them.
145 * It should never be cleared without a comment explaining why it
146 * is cleared.
147 *
148 * TODO remove once we're there
149 */
150 bool user_creatable;
151 bool hotpluggable;
152
153 /* callbacks */
154 /**
155 * @reset: deprecated device reset method pointer
156 *
157 * Modern code should use the ResettableClass interface to
158 * implement a multi-phase reset.
159 *
160 * TODO: remove once every reset callback is unused
161 */
162 DeviceReset reset;
163 DeviceRealize realize;
164 DeviceUnrealize unrealize;
165
166 /**
167 * @vmsd: device state serialisation description for
168 * migration/save/restore
169 */
170 const VMStateDescription *vmsd;
171
172 /**
173 * @bus_type: bus type
174 * private: to qdev / bus.
175 */
176 const char *bus_type;
177 };
178
179 typedef struct NamedGPIOList NamedGPIOList;
180
181 struct NamedGPIOList {
182 char *name;
183 qemu_irq *in;
184 int num_in;
185 int num_out;
186 QLIST_ENTRY(NamedGPIOList) node;
187 };
188
189 typedef struct Clock Clock;
190 typedef struct NamedClockList NamedClockList;
191
192 struct NamedClockList {
193 char *name;
194 Clock *clock;
195 bool output;
196 bool alias;
197 QLIST_ENTRY(NamedClockList) node;
198 };
199
200 typedef struct {
201 bool engaged_in_io;
202 } MemReentrancyGuard;
203
204
205 typedef QLIST_HEAD(, NamedGPIOList) NamedGPIOListHead;
206 typedef QLIST_HEAD(, NamedClockList) NamedClockListHead;
207 typedef QLIST_HEAD(, BusState) BusStateHead;
208
209 /**
210 * struct DeviceState - common device state, accessed with qdev helpers
211 *
212 * This structure should not be accessed directly. We declare it here
213 * so that it can be embedded in individual device state structures.
214 */
215 struct DeviceState {
216 /* private: */
217 Object parent_obj;
218 /* public: */
219
220 /**
221 * @id: global device id
222 */
223 char *id;
224 /**
225 * @canonical_path: canonical path of realized device in the QOM tree
226 */
227 char *canonical_path;
228 /**
229 * @realized: has device been realized?
230 */
231 bool realized;
232 /**
233 * @pending_deleted_event: track pending deletion events during unplug
234 */
235 bool pending_deleted_event;
236 /**
237 * @pending_deleted_expires_ms: optional timeout for deletion events
238 */
239 int64_t pending_deleted_expires_ms;
240 /**
241 * @opts: QDict of options for the device
242 */
243 QDict *opts;
244 /**
245 * @hotplugged: was device added after PHASE_MACHINE_READY?
246 */
247 int hotplugged;
248 /**
249 * @allow_unplug_during_migration: can device be unplugged during migration
250 */
251 bool allow_unplug_during_migration;
252 /**
253 * @parent_bus: bus this device belongs to
254 */
255 BusState *parent_bus;
256 /**
257 * @gpios: QLIST of named GPIOs the device provides.
258 */
259 NamedGPIOListHead gpios;
260 /**
261 * @clocks: QLIST of named clocks the device provides.
262 */
263 NamedClockListHead clocks;
264 /**
265 * @child_bus: QLIST of child buses
266 */
267 BusStateHead child_bus;
268 /**
269 * @num_child_bus: number of @child_bus entries
270 */
271 int num_child_bus;
272 /**
273 * @instance_id_alias: device alias for handling legacy migration setups
274 */
275 int instance_id_alias;
276 /**
277 * @alias_required_for_version: indicates @instance_id_alias is
278 * needed for migration
279 */
280 int alias_required_for_version;
281 /**
282 * @reset: ResettableState for the device; handled by Resettable interface.
283 */
284 ResettableState reset;
285 /**
286 * @unplug_blockers: list of reasons to block unplugging of device
287 */
288 GSList *unplug_blockers;
289 /**
290 * @mem_reentrancy_guard: Is the device currently in mmio/pio/dma?
291 *
292 * Used to prevent re-entrancy confusing things.
293 */
294 MemReentrancyGuard mem_reentrancy_guard;
295 };
296
297 struct DeviceListener {
298 void (*realize)(DeviceListener *listener, DeviceState *dev);
299 void (*unrealize)(DeviceListener *listener, DeviceState *dev);
300 /*
301 * This callback is called upon init of the DeviceState and
302 * informs qdev if a device should be visible or hidden. We can
303 * hide a failover device depending for example on the device
304 * opts.
305 *
306 * On errors, it returns false and errp is set. Device creation
307 * should fail in this case.
308 */
309 bool (*hide_device)(DeviceListener *listener, const QDict *device_opts,
310 bool from_json, Error **errp);
311 QTAILQ_ENTRY(DeviceListener) link;
312 };
313
314 #define TYPE_BUS "bus"
315 DECLARE_OBJ_CHECKERS(BusState, BusClass,
316 BUS, TYPE_BUS)
317
318 struct BusClass {
319 ObjectClass parent_class;
320
321 /* FIXME first arg should be BusState */
322 void (*print_dev)(Monitor *mon, DeviceState *dev, int indent);
323 char *(*get_dev_path)(DeviceState *dev);
324
325 /*
326 * This callback is used to create Open Firmware device path in accordance
327 * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus
328 * bindings can be found at http://playground.sun.com/1275/bindings/.
329 */
330 char *(*get_fw_dev_path)(DeviceState *dev);
331
332 /*
333 * Return whether the device can be added to @bus,
334 * based on the address that was set (via device properties)
335 * before realize. If not, on return @errp contains the
336 * human-readable error message.
337 */
338 bool (*check_address)(BusState *bus, DeviceState *dev, Error **errp);
339
340 BusRealize realize;
341 BusUnrealize unrealize;
342
343 /* maximum devices allowed on the bus, 0: no limit. */
344 int max_dev;
345 /* number of automatically allocated bus ids (e.g. ide.0) */
346 int automatic_ids;
347 };
348
349 typedef struct BusChild {
350 struct rcu_head rcu;
351 DeviceState *child;
352 int index;
353 QTAILQ_ENTRY(BusChild) sibling;
354 } BusChild;
355
356 #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler"
357
358 typedef QTAILQ_HEAD(, BusChild) BusChildHead;
359 typedef QLIST_ENTRY(BusState) BusStateEntry;
360
361 /**
362 * struct BusState:
363 * @obj: parent object
364 * @parent: parent Device
365 * @name: name of bus
366 * @hotplug_handler: link to a hotplug handler associated with bus.
367 * @max_index: max number of child buses
368 * @realized: is the bus itself realized?
369 * @full: is the bus full?
370 * @num_children: current number of child buses
371 */
372 struct BusState {
373 /* private: */
374 Object obj;
375 /* public: */
376 DeviceState *parent;
377 char *name;
378 HotplugHandler *hotplug_handler;
379 int max_index;
380 bool realized;
381 bool full;
382 int num_children;
383
384 /**
385 * @children: an RCU protected QTAILQ, thus readers must use RCU
386 * to access it, and writers must hold the big qemu lock
387 */
388 BusChildHead children;
389 /**
390 * @sibling: next bus
391 */
392 BusStateEntry sibling;
393 /**
394 * @reset: ResettableState for the bus; handled by Resettable interface.
395 */
396 ResettableState reset;
397 };
398
399 /**
400 * typedef GlobalProperty - a global property type
401 *
402 * @used: Set to true if property was used when initializing a device.
403 * @optional: If set to true, GlobalProperty will be skipped without errors
404 * if the property doesn't exist.
405 *
406 * An error is fatal for non-hotplugged devices, when the global is applied.
407 */
408 typedef struct GlobalProperty {
409 const char *driver;
410 const char *property;
411 const char *value;
412 bool used;
413 bool optional;
414 } GlobalProperty;
415
416 static inline void
compat_props_add(GPtrArray * arr,GlobalProperty props[],size_t nelem)417 compat_props_add(GPtrArray *arr,
418 GlobalProperty props[], size_t nelem)
419 {
420 int i;
421 for (i = 0; i < nelem; i++) {
422 g_ptr_array_add(arr, (void *)&props[i]);
423 }
424 }
425
426 /*** Board API. This should go away once we have a machine config file. ***/
427
428 /**
429 * qdev_new: Create a device on the heap
430 * @name: device type to create (we assert() that this type exists)
431 *
432 * This only allocates the memory and initializes the device state
433 * structure, ready for the caller to set properties if they wish.
434 * The device still needs to be realized.
435 *
436 * Return: a derived DeviceState object with a reference count of 1.
437 */
438 DeviceState *qdev_new(const char *name);
439
440 /**
441 * qdev_try_new: Try to create a device on the heap
442 * @name: device type to create
443 *
444 * This is like qdev_new(), except it returns %NULL when type @name
445 * does not exist, rather than asserting.
446 *
447 * Return: a derived DeviceState object with a reference count of 1 or
448 * NULL if type @name does not exist.
449 */
450 DeviceState *qdev_try_new(const char *name);
451
452 /**
453 * qdev_is_realized() - check if device is realized
454 * @dev: The device to check.
455 *
456 * Context: May be called outside big qemu lock.
457 * Return: true if the device has been fully constructed, false otherwise.
458 */
qdev_is_realized(DeviceState * dev)459 static inline bool qdev_is_realized(DeviceState *dev)
460 {
461 return qatomic_load_acquire(&dev->realized);
462 }
463
464 /**
465 * qdev_realize: Realize @dev.
466 * @dev: device to realize
467 * @bus: bus to plug it into (may be NULL)
468 * @errp: pointer to error object
469 *
470 * "Realize" the device, i.e. perform the second phase of device
471 * initialization.
472 * @dev must not be plugged into a bus already.
473 * If @bus, plug @dev into @bus. This takes a reference to @dev.
474 * If @dev has no QOM parent, make one up, taking another reference.
475 *
476 * If you created @dev using qdev_new(), you probably want to use
477 * qdev_realize_and_unref() instead.
478 *
479 * Return: true on success, else false setting @errp with error
480 */
481 bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp);
482
483 /**
484 * qdev_realize_and_unref: Realize @dev and drop a reference
485 * @dev: device to realize
486 * @bus: bus to plug it into (may be NULL)
487 * @errp: pointer to error object
488 *
489 * Realize @dev and drop a reference.
490 * This is like qdev_realize(), except the caller must hold a
491 * (private) reference, which is dropped on return regardless of
492 * success or failure. Intended use::
493 *
494 * dev = qdev_new();
495 * [...]
496 * qdev_realize_and_unref(dev, bus, errp);
497 *
498 * Now @dev can go away without further ado.
499 *
500 * If you are embedding the device into some other QOM device and
501 * initialized it via some variant on object_initialize_child() then
502 * do not use this function, because that family of functions arrange
503 * for the only reference to the child device to be held by the parent
504 * via the child<> property, and so the reference-count-drop done here
505 * would be incorrect. For that use case you want qdev_realize().
506 *
507 * Return: true on success, else false setting @errp with error
508 */
509 bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp);
510
511 /**
512 * qdev_unrealize: Unrealize a device
513 * @dev: device to unrealize
514 *
515 * This function will "unrealize" a device, which is the first phase
516 * of correctly destroying a device that has been realized. It will:
517 *
518 * - unrealize any child buses by calling qbus_unrealize()
519 * (this will recursively unrealize any devices on those buses)
520 * - call the unrealize method of @dev
521 *
522 * The device can then be freed by causing its reference count to go
523 * to zero.
524 *
525 * Warning: most devices in QEMU do not expect to be unrealized. Only
526 * devices which are hot-unpluggable should be unrealized (as part of
527 * the unplugging process); all other devices are expected to last for
528 * the life of the simulation and should not be unrealized and freed.
529 */
530 void qdev_unrealize(DeviceState *dev);
531 void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
532 int required_for_version);
533 HotplugHandler *qdev_get_bus_hotplug_handler(DeviceState *dev);
534 HotplugHandler *qdev_get_machine_hotplug_handler(DeviceState *dev);
535 bool qdev_hotplug_allowed(DeviceState *dev, Error **errp);
536
537 /**
538 * qdev_get_hotplug_handler() - Get handler responsible for device wiring
539 * @dev: the device we want the HOTPLUG_HANDLER for.
540 *
541 * Note: in case @dev has a parent bus, it will be returned as handler unless
542 * machine handler overrides it.
543 *
544 * Return: pointer to object that implements TYPE_HOTPLUG_HANDLER interface
545 * or NULL if there aren't any.
546 */
547 HotplugHandler *qdev_get_hotplug_handler(DeviceState *dev);
548 void qdev_unplug(DeviceState *dev, Error **errp);
549 void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev,
550 DeviceState *dev, Error **errp);
551 void qdev_machine_creation_done(void);
552 bool qdev_machine_modified(void);
553
554 /**
555 * qdev_add_unplug_blocker: Add an unplug blocker to a device
556 *
557 * @dev: Device to be blocked from unplug
558 * @reason: Reason for blocking
559 */
560 void qdev_add_unplug_blocker(DeviceState *dev, Error *reason);
561
562 /**
563 * qdev_del_unplug_blocker: Remove an unplug blocker from a device
564 *
565 * @dev: Device to be unblocked
566 * @reason: Pointer to the Error used with qdev_add_unplug_blocker.
567 * Used as a handle to lookup the blocker for deletion.
568 */
569 void qdev_del_unplug_blocker(DeviceState *dev, Error *reason);
570
571 /**
572 * qdev_unplug_blocked: Confirm if a device is blocked from unplug
573 *
574 * @dev: Device to be tested
575 * @errp: The reasons why the device is blocked, if any
576 *
577 * Returns: true (also setting @errp) if device is blocked from unplug,
578 * false otherwise
579 */
580 bool qdev_unplug_blocked(DeviceState *dev, Error **errp);
581
582 /**
583 * typedef GpioPolarity - Polarity of a GPIO line
584 *
585 * GPIO lines use either positive (active-high) logic,
586 * or negative (active-low) logic.
587 *
588 * In active-high logic (%GPIO_POLARITY_ACTIVE_HIGH), a pin is
589 * active when the voltage on the pin is high (relative to ground);
590 * whereas in active-low logic (%GPIO_POLARITY_ACTIVE_LOW), a pin
591 * is active when the voltage on the pin is low (or grounded).
592 */
593 typedef enum {
594 GPIO_POLARITY_ACTIVE_LOW,
595 GPIO_POLARITY_ACTIVE_HIGH
596 } GpioPolarity;
597
598 /**
599 * qdev_get_gpio_in: Get one of a device's anonymous input GPIO lines
600 * @dev: Device whose GPIO we want
601 * @n: Number of the anonymous GPIO line (which must be in range)
602 *
603 * Returns the qemu_irq corresponding to an anonymous input GPIO line
604 * (which the device has set up with qdev_init_gpio_in()). The index
605 * @n of the GPIO line must be valid (i.e. be at least 0 and less than
606 * the total number of anonymous input GPIOs the device has); this
607 * function will assert() if passed an invalid index.
608 *
609 * This function is intended to be used by board code or SoC "container"
610 * device models to wire up the GPIO lines; usually the return value
611 * will be passed to qdev_connect_gpio_out() or a similar function to
612 * connect another device's output GPIO line to this input.
613 *
614 * For named input GPIO lines, use qdev_get_gpio_in_named().
615 *
616 * Return: qemu_irq corresponding to anonymous input GPIO line
617 */
618 qemu_irq qdev_get_gpio_in(DeviceState *dev, int n);
619
620 /**
621 * qdev_get_gpio_in_named: Get one of a device's named input GPIO lines
622 * @dev: Device whose GPIO we want
623 * @name: Name of the input GPIO array
624 * @n: Number of the GPIO line in that array (which must be in range)
625 *
626 * Returns the qemu_irq corresponding to a named input GPIO line
627 * (which the device has set up with qdev_init_gpio_in_named()).
628 * The @name string must correspond to an input GPIO array which exists on
629 * the device, and the index @n of the GPIO line must be valid (i.e.
630 * be at least 0 and less than the total number of input GPIOs in that
631 * array); this function will assert() if passed an invalid name or index.
632 *
633 * For anonymous input GPIO lines, use qdev_get_gpio_in().
634 *
635 * Return: qemu_irq corresponding to named input GPIO line
636 */
637 qemu_irq qdev_get_gpio_in_named(DeviceState *dev, const char *name, int n);
638
639 /**
640 * qdev_connect_gpio_out: Connect one of a device's anonymous output GPIO lines
641 * @dev: Device whose GPIO to connect
642 * @n: Number of the anonymous output GPIO line (which must be in range)
643 * @pin: qemu_irq to connect the output line to
644 *
645 * This function connects an anonymous output GPIO line on a device
646 * up to an arbitrary qemu_irq, so that when the device asserts that
647 * output GPIO line, the qemu_irq's callback is invoked.
648 * The index @n of the GPIO line must be valid (i.e. be at least 0 and
649 * less than the total number of anonymous output GPIOs the device has
650 * created with qdev_init_gpio_out()); otherwise this function will assert().
651 *
652 * Outbound GPIO lines can be connected to any qemu_irq, but the common
653 * case is connecting them to another device's inbound GPIO line, using
654 * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named().
655 *
656 * It is not valid to try to connect one outbound GPIO to multiple
657 * qemu_irqs at once, or to connect multiple outbound GPIOs to the
658 * same qemu_irq. (Warning: there is no assertion or other guard to
659 * catch this error: the model will just not do the right thing.)
660 * Instead, for fan-out you can use the TYPE_SPLIT_IRQ device: connect
661 * a device's outbound GPIO to the splitter's input, and connect each
662 * of the splitter's outputs to a different device. For fan-in you
663 * can use the TYPE_OR_IRQ device, which is a model of a logical OR
664 * gate with multiple inputs and one output.
665 *
666 * For named output GPIO lines, use qdev_connect_gpio_out_named().
667 */
668 void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin);
669
670 /**
671 * qdev_connect_gpio_out_named: Connect one of a device's named output
672 * GPIO lines
673 * @dev: Device whose GPIO to connect
674 * @name: Name of the output GPIO array
675 * @n: Number of the anonymous output GPIO line (which must be in range)
676 * @input_pin: qemu_irq to connect the output line to
677 *
678 * This function connects an anonymous output GPIO line on a device
679 * up to an arbitrary qemu_irq, so that when the device asserts that
680 * output GPIO line, the qemu_irq's callback is invoked.
681 * The @name string must correspond to an output GPIO array which exists on
682 * the device, and the index @n of the GPIO line must be valid (i.e.
683 * be at least 0 and less than the total number of input GPIOs in that
684 * array); this function will assert() if passed an invalid name or index.
685 *
686 * Outbound GPIO lines can be connected to any qemu_irq, but the common
687 * case is connecting them to another device's inbound GPIO line, using
688 * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named().
689 *
690 * It is not valid to try to connect one outbound GPIO to multiple
691 * qemu_irqs at once, or to connect multiple outbound GPIOs to the
692 * same qemu_irq; see qdev_connect_gpio_out() for details.
693 *
694 * For anonymous output GPIO lines, use qdev_connect_gpio_out().
695 */
696 void qdev_connect_gpio_out_named(DeviceState *dev, const char *name, int n,
697 qemu_irq input_pin);
698
699 /**
700 * qdev_get_gpio_out_connector: Get the qemu_irq connected to an output GPIO
701 * @dev: Device whose output GPIO we are interested in
702 * @name: Name of the output GPIO array
703 * @n: Number of the output GPIO line within that array
704 *
705 * Returns whatever qemu_irq is currently connected to the specified
706 * output GPIO line of @dev. This will be NULL if the output GPIO line
707 * has never been wired up to the anything. Note that the qemu_irq
708 * returned does not belong to @dev -- it will be the input GPIO or
709 * IRQ of whichever device the board code has connected up to @dev's
710 * output GPIO.
711 *
712 * You probably don't need to use this function -- it is used only
713 * by the platform-bus subsystem.
714 *
715 * Return: qemu_irq associated with GPIO or NULL if un-wired.
716 */
717 qemu_irq qdev_get_gpio_out_connector(DeviceState *dev, const char *name, int n);
718
719 /**
720 * qdev_intercept_gpio_out: Intercept an existing GPIO connection
721 * @dev: Device to intercept the outbound GPIO line from
722 * @icpt: New qemu_irq to connect instead
723 * @name: Name of the output GPIO array
724 * @n: Number of the GPIO line in the array
725 *
726 * .. note::
727 * This function is provided only for use by the qtest testing framework
728 * and is not suitable for use in non-testing parts of QEMU.
729 *
730 * This function breaks an existing connection of an outbound GPIO
731 * line from @dev, and replaces it with the new qemu_irq @icpt, as if
732 * ``qdev_connect_gpio_out_named(dev, icpt, name, n)`` had been called.
733 * The previously connected qemu_irq is returned, so it can be restored
734 * by a second call to qdev_intercept_gpio_out() if desired.
735 *
736 * Return: old disconnected qemu_irq if one existed
737 */
738 qemu_irq qdev_intercept_gpio_out(DeviceState *dev, qemu_irq icpt,
739 const char *name, int n);
740
741 BusState *qdev_get_child_bus(DeviceState *dev, const char *name);
742
743 /*** Device API. ***/
744
745 /**
746 * qdev_init_gpio_in: create an array of anonymous input GPIO lines
747 * @dev: Device to create input GPIOs for
748 * @handler: Function to call when GPIO line value is set
749 * @n: Number of GPIO lines to create
750 *
751 * Devices should use functions in the qdev_init_gpio_in* family in
752 * their instance_init or realize methods to create any input GPIO
753 * lines they need. There is no functional difference between
754 * anonymous and named GPIO lines. Stylistically, named GPIOs are
755 * preferable (easier to understand at callsites) unless a device
756 * has exactly one uniform kind of GPIO input whose purpose is obvious.
757 * Note that input GPIO lines can serve as 'sinks' for IRQ lines.
758 *
759 * See qdev_get_gpio_in() for how code that uses such a device can get
760 * hold of an input GPIO line to manipulate it.
761 */
762 void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n);
763
764 /**
765 * qdev_init_gpio_out: create an array of anonymous output GPIO lines
766 * @dev: Device to create output GPIOs for
767 * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines
768 * @n: Number of GPIO lines to create
769 *
770 * Devices should use functions in the qdev_init_gpio_out* family
771 * in their instance_init or realize methods to create any output
772 * GPIO lines they need. There is no functional difference between
773 * anonymous and named GPIO lines. Stylistically, named GPIOs are
774 * preferable (easier to understand at callsites) unless a device
775 * has exactly one uniform kind of GPIO output whose purpose is obvious.
776 *
777 * The @pins argument should be a pointer to either a "qemu_irq"
778 * (if @n == 1) or a "qemu_irq []" array (if @n > 1) in the device's
779 * state structure. The device implementation can then raise and
780 * lower the GPIO line by calling qemu_set_irq(). (If anything is
781 * connected to the other end of the GPIO this will cause the handler
782 * function for that input GPIO to be called.)
783 *
784 * See qdev_connect_gpio_out() for how code that uses such a device
785 * can connect to one of its output GPIO lines.
786 *
787 * There is no need to release the @pins allocated array because it
788 * will be automatically released when @dev calls its instance_finalize()
789 * handler.
790 */
791 void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n);
792
793 /**
794 * qdev_init_gpio_out_named: create an array of named output GPIO lines
795 * @dev: Device to create output GPIOs for
796 * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines
797 * @name: Name to give this array of GPIO lines
798 * @n: Number of GPIO lines to create
799 *
800 * Like qdev_init_gpio_out(), but creates an array of GPIO output lines
801 * with a name. Code using the device can then connect these GPIO lines
802 * using qdev_connect_gpio_out_named().
803 */
804 void qdev_init_gpio_out_named(DeviceState *dev, qemu_irq *pins,
805 const char *name, int n);
806
807 /**
808 * qdev_init_gpio_in_named_with_opaque() - create an array of input GPIO lines
809 * @dev: Device to create input GPIOs for
810 * @handler: Function to call when GPIO line value is set
811 * @opaque: Opaque data pointer to pass to @handler
812 * @name: Name of the GPIO input (must be unique for this device)
813 * @n: Number of GPIO lines in this input set
814 */
815 void qdev_init_gpio_in_named_with_opaque(DeviceState *dev,
816 qemu_irq_handler handler,
817 void *opaque,
818 const char *name, int n);
819
820 /**
821 * qdev_init_gpio_in_named() - create an array of input GPIO lines
822 * @dev: device to add array to
823 * @handler: a &typedef qemu_irq_handler function to call when GPIO is set
824 * @name: Name of the GPIO input (must be unique for this device)
825 * @n: Number of GPIO lines in this input set
826 *
827 * Like qdev_init_gpio_in_named_with_opaque(), but the opaque pointer
828 * passed to the handler is @dev (which is the most commonly desired behaviour).
829 */
qdev_init_gpio_in_named(DeviceState * dev,qemu_irq_handler handler,const char * name,int n)830 static inline void qdev_init_gpio_in_named(DeviceState *dev,
831 qemu_irq_handler handler,
832 const char *name, int n)
833 {
834 qdev_init_gpio_in_named_with_opaque(dev, handler, dev, name, n);
835 }
836
837 /**
838 * qdev_pass_gpios: create GPIO lines on container which pass through to device
839 * @dev: Device which has GPIO lines
840 * @container: Container device which needs to expose them
841 * @name: Name of GPIO array to pass through (NULL for the anonymous GPIO array)
842 *
843 * In QEMU, complicated devices like SoCs are often modelled with a
844 * "container" QOM device which itself contains other QOM devices and
845 * which wires them up appropriately. This function allows the container
846 * to create GPIO arrays on itself which simply pass through to a GPIO
847 * array of one of its internal devices.
848 *
849 * If @dev has both input and output GPIOs named @name then both will
850 * be passed through. It is not possible to pass a subset of the array
851 * with this function.
852 *
853 * To users of the container device, the GPIO array created on @container
854 * behaves exactly like any other.
855 */
856 void qdev_pass_gpios(DeviceState *dev, DeviceState *container,
857 const char *name);
858
859 BusState *qdev_get_parent_bus(const DeviceState *dev);
860
861 /*** BUS API. ***/
862
863 DeviceState *qdev_find_recursive(BusState *bus, const char *id);
864
865 /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */
866 typedef int (qbus_walkerfn)(BusState *bus, void *opaque);
867 typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque);
868
869 void qbus_init(void *bus, size_t size, const char *typename,
870 DeviceState *parent, const char *name);
871 BusState *qbus_new(const char *typename, DeviceState *parent, const char *name);
872 bool qbus_realize(BusState *bus, Error **errp);
873 void qbus_unrealize(BusState *bus);
874
875 /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion,
876 * < 0 if either devfn or busfn terminate walk somewhere in cursion,
877 * 0 otherwise. */
878 int qbus_walk_children(BusState *bus,
879 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
880 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
881 void *opaque);
882 int qdev_walk_children(DeviceState *dev,
883 qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
884 qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
885 void *opaque);
886
887 /**
888 * device_cold_reset() - perform a recursive cold reset on a device
889 * @dev: device to reset.
890 *
891 * Reset device @dev and perform a recursive processing using the resettable
892 * interface. It triggers a RESET_TYPE_COLD.
893 */
894 void device_cold_reset(DeviceState *dev);
895
896 /**
897 * bus_cold_reset() - perform a recursive cold reset on a bus
898 * @bus: bus to reset
899 *
900 * Reset bus @bus and perform a recursive processing using the resettable
901 * interface. It triggers a RESET_TYPE_COLD.
902 */
903 void bus_cold_reset(BusState *bus);
904
905 /**
906 * device_is_in_reset() - check device reset state
907 * @dev: device to check
908 *
909 * Return: true if the device @dev is currently being reset.
910 */
911 bool device_is_in_reset(DeviceState *dev);
912
913 /**
914 * bus_is_in_reset() - check bus reset state
915 * @bus: bus to check
916 *
917 * Return: true if the bus @bus is currently being reset.
918 */
919 bool bus_is_in_reset(BusState *bus);
920
921 /* This should go away once we get rid of the NULL bus hack */
922 BusState *sysbus_get_default(void);
923
924 char *qdev_get_fw_dev_path(DeviceState *dev);
925 char *qdev_get_own_fw_dev_path_from_handler(BusState *bus, DeviceState *dev);
926
927 /**
928 * device_class_set_props(): add a set of properties to an device
929 * @dc: the parent DeviceClass all devices inherit
930 * @props: an array of properties, terminate by DEFINE_PROP_END_OF_LIST()
931 *
932 * This will add a set of properties to the object. It will fault if
933 * you attempt to add an existing property defined by a parent class.
934 * To modify an inherited property you need to use????
935 */
936 void device_class_set_props(DeviceClass *dc, Property *props);
937
938 /**
939 * device_class_set_parent_reset() - legacy set device reset handlers
940 * @dc: device class
941 * @dev_reset: function pointer to reset handler
942 * @parent_reset: function pointer to parents reset handler
943 *
944 * Modern code should use the ResettableClass interface to
945 * implement a multi-phase reset instead.
946 *
947 * TODO: remove the function when DeviceClass's reset method
948 * is not used anymore.
949 */
950 void device_class_set_parent_reset(DeviceClass *dc,
951 DeviceReset dev_reset,
952 DeviceReset *parent_reset);
953
954 /**
955 * device_class_set_parent_realize() - set up for chaining realize fns
956 * @dc: The device class
957 * @dev_realize: the device realize function
958 * @parent_realize: somewhere to save the parents realize function
959 *
960 * This is intended to be used when the new realize function will
961 * eventually call its parent realization function during creation.
962 * This requires storing the function call somewhere (usually in the
963 * instance structure) so you can eventually call
964 * dc->parent_realize(dev, errp)
965 */
966 void device_class_set_parent_realize(DeviceClass *dc,
967 DeviceRealize dev_realize,
968 DeviceRealize *parent_realize);
969
970
971 /**
972 * device_class_set_parent_unrealize() - set up for chaining unrealize fns
973 * @dc: The device class
974 * @dev_unrealize: the device realize function
975 * @parent_unrealize: somewhere to save the parents unrealize function
976 *
977 * This is intended to be used when the new unrealize function will
978 * eventually call its parent unrealization function during the
979 * unrealize phase. This requires storing the function call somewhere
980 * (usually in the instance structure) so you can eventually call
981 * dc->parent_unrealize(dev);
982 */
983 void device_class_set_parent_unrealize(DeviceClass *dc,
984 DeviceUnrealize dev_unrealize,
985 DeviceUnrealize *parent_unrealize);
986
987 const VMStateDescription *qdev_get_vmsd(DeviceState *dev);
988
989 const char *qdev_fw_name(DeviceState *dev);
990
991 void qdev_assert_realized_properly(void);
992 Object *qdev_get_machine(void);
993
994 /**
995 * qdev_get_human_name() - Return a human-readable name for a device
996 * @dev: The device. Must be a valid and non-NULL pointer.
997 *
998 * .. note::
999 * This function is intended for user friendly error messages.
1000 *
1001 * Returns: A newly allocated string containing the device id if not null,
1002 * else the object canonical path.
1003 *
1004 * Use g_free() to free it.
1005 */
1006 char *qdev_get_human_name(DeviceState *dev);
1007
1008 /* FIXME: make this a link<> */
1009 bool qdev_set_parent_bus(DeviceState *dev, BusState *bus, Error **errp);
1010
1011 extern bool qdev_hot_removed;
1012
1013 char *qdev_get_dev_path(DeviceState *dev);
1014
1015 void qbus_set_hotplug_handler(BusState *bus, Object *handler);
1016 void qbus_set_bus_hotplug_handler(BusState *bus);
1017
qbus_is_hotpluggable(BusState * bus)1018 static inline bool qbus_is_hotpluggable(BusState *bus)
1019 {
1020 HotplugHandler *plug_handler = bus->hotplug_handler;
1021 bool ret = !!plug_handler;
1022
1023 if (plug_handler) {
1024 HotplugHandlerClass *hdc;
1025
1026 hdc = HOTPLUG_HANDLER_GET_CLASS(plug_handler);
1027 if (hdc->is_hotpluggable_bus) {
1028 ret = hdc->is_hotpluggable_bus(plug_handler, bus);
1029 }
1030 }
1031 return ret;
1032 }
1033
1034 /**
1035 * qbus_mark_full: Mark this bus as full, so no more devices can be attached
1036 * @bus: Bus to mark as full
1037 *
1038 * By default, QEMU will allow devices to be plugged into a bus up
1039 * to the bus class's device count limit. Calling this function
1040 * marks a particular bus as full, so that no more devices can be
1041 * plugged into it. In particular this means that the bus will not
1042 * be considered as a candidate for plugging in devices created by
1043 * the user on the commandline or via the monitor.
1044 * If a machine has multiple buses of a given type, such as I2C,
1045 * where some of those buses in the real hardware are used only for
1046 * internal devices and some are exposed via expansion ports, you
1047 * can use this function to mark the internal-only buses as full
1048 * after you have created all their internal devices. Then user
1049 * created devices will appear on the expansion-port bus where
1050 * guest software expects them.
1051 */
qbus_mark_full(BusState * bus)1052 static inline void qbus_mark_full(BusState *bus)
1053 {
1054 bus->full = true;
1055 }
1056
1057 void device_listener_register(DeviceListener *listener);
1058 void device_listener_unregister(DeviceListener *listener);
1059
1060 /**
1061 * qdev_should_hide_device() - check if device should be hidden
1062 *
1063 * @opts: options QDict
1064 * @from_json: true if @opts entries are typed, false for all strings
1065 * @errp: pointer to error object
1066 *
1067 * When a device is added via qdev_device_add() this will be called.
1068 *
1069 * Return: if the device should be added now or not.
1070 */
1071 bool qdev_should_hide_device(const QDict *opts, bool from_json, Error **errp);
1072
1073 typedef enum MachineInitPhase {
1074 /* current_machine is NULL. */
1075 PHASE_NO_MACHINE,
1076
1077 /* current_machine is not NULL, but current_machine->accel is NULL. */
1078 PHASE_MACHINE_CREATED,
1079
1080 /*
1081 * current_machine->accel is not NULL, but the machine properties have
1082 * not been validated and machine_class->init has not yet been called.
1083 */
1084 PHASE_ACCEL_CREATED,
1085
1086 /*
1087 * Late backend objects have been created and initialized.
1088 */
1089 PHASE_LATE_BACKENDS_CREATED,
1090
1091 /*
1092 * machine_class->init has been called, thus creating any embedded
1093 * devices and validating machine properties. Devices created at
1094 * this time are considered to be cold-plugged.
1095 */
1096 PHASE_MACHINE_INITIALIZED,
1097
1098 /*
1099 * QEMU is ready to start CPUs and devices created at this time
1100 * are considered to be hot-plugged. The monitor is not restricted
1101 * to "preconfig" commands.
1102 */
1103 PHASE_MACHINE_READY,
1104 } MachineInitPhase;
1105
1106 bool phase_check(MachineInitPhase phase);
1107 void phase_advance(MachineInitPhase phase);
1108
1109 #endif
1110