xref: /openbmc/qemu/include/hw/qdev-core.h (revision 19ed42e8)
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 typedef struct DeviceListener DeviceListener;
298 struct DeviceListener {
299     void (*realize)(DeviceListener *listener, DeviceState *dev);
300     void (*unrealize)(DeviceListener *listener, DeviceState *dev);
301     /*
302      * This callback is called upon init of the DeviceState and
303      * informs qdev if a device should be visible or hidden.  We can
304      * hide a failover device depending for example on the device
305      * opts.
306      *
307      * On errors, it returns false and errp is set. Device creation
308      * should fail in this case.
309      */
310     bool (*hide_device)(DeviceListener *listener, const QDict *device_opts,
311                         bool from_json, Error **errp);
312     QTAILQ_ENTRY(DeviceListener) link;
313 };
314 
315 #define TYPE_BUS "bus"
316 DECLARE_OBJ_CHECKERS(BusState, BusClass,
317                      BUS, TYPE_BUS)
318 
319 struct BusClass {
320     ObjectClass parent_class;
321 
322     /* FIXME first arg should be BusState */
323     void (*print_dev)(Monitor *mon, DeviceState *dev, int indent);
324     char *(*get_dev_path)(DeviceState *dev);
325 
326     /*
327      * This callback is used to create Open Firmware device path in accordance
328      * with OF spec http://forthworks.com/standards/of1275.pdf. Individual bus
329      * bindings can be found at http://playground.sun.com/1275/bindings/.
330      */
331     char *(*get_fw_dev_path)(DeviceState *dev);
332 
333     /*
334      * Return whether the device can be added to @bus,
335      * based on the address that was set (via device properties)
336      * before realize.  If not, on return @errp contains the
337      * human-readable error message.
338      */
339     bool (*check_address)(BusState *bus, DeviceState *dev, Error **errp);
340 
341     BusRealize realize;
342     BusUnrealize unrealize;
343 
344     /* maximum devices allowed on the bus, 0: no limit. */
345     int max_dev;
346     /* number of automatically allocated bus ids (e.g. ide.0) */
347     int automatic_ids;
348 };
349 
350 typedef struct BusChild {
351     struct rcu_head rcu;
352     DeviceState *child;
353     int index;
354     QTAILQ_ENTRY(BusChild) sibling;
355 } BusChild;
356 
357 #define QDEV_HOTPLUG_HANDLER_PROPERTY "hotplug-handler"
358 
359 typedef QTAILQ_HEAD(, BusChild) BusChildHead;
360 typedef QLIST_ENTRY(BusState) BusStateEntry;
361 
362 /**
363  * struct BusState:
364  * @obj: parent object
365  * @parent: parent Device
366  * @name: name of bus
367  * @hotplug_handler: link to a hotplug handler associated with bus.
368  * @max_index: max number of child buses
369  * @realized: is the bus itself realized?
370  * @full: is the bus full?
371  * @num_children: current number of child buses
372  */
373 struct BusState {
374     /* private: */
375     Object obj;
376     /* public: */
377     DeviceState *parent;
378     char *name;
379     HotplugHandler *hotplug_handler;
380     int max_index;
381     bool realized;
382     bool full;
383     int num_children;
384 
385     /**
386      * @children: an RCU protected QTAILQ, thus readers must use RCU
387      * to access it, and writers must hold the big qemu lock
388      */
389     BusChildHead children;
390     /**
391      * @sibling: next bus
392      */
393     BusStateEntry sibling;
394     /**
395      * @reset: ResettableState for the bus; handled by Resettable interface.
396      */
397     ResettableState reset;
398 };
399 
400 /**
401  * typedef GlobalProperty - a global property type
402  *
403  * @used: Set to true if property was used when initializing a device.
404  * @optional: If set to true, GlobalProperty will be skipped without errors
405  *            if the property doesn't exist.
406  *
407  * An error is fatal for non-hotplugged devices, when the global is applied.
408  */
409 typedef struct GlobalProperty {
410     const char *driver;
411     const char *property;
412     const char *value;
413     bool used;
414     bool optional;
415 } GlobalProperty;
416 
417 static inline void
418 compat_props_add(GPtrArray *arr,
419                  GlobalProperty props[], size_t nelem)
420 {
421     int i;
422     for (i = 0; i < nelem; i++) {
423         g_ptr_array_add(arr, (void *)&props[i]);
424     }
425 }
426 
427 /*** Board API.  This should go away once we have a machine config file.  ***/
428 
429 /**
430  * qdev_new: Create a device on the heap
431  * @name: device type to create (we assert() that this type exists)
432  *
433  * This only allocates the memory and initializes the device state
434  * structure, ready for the caller to set properties if they wish.
435  * The device still needs to be realized.
436  *
437  * Return: a derived DeviceState object with a reference count of 1.
438  */
439 DeviceState *qdev_new(const char *name);
440 
441 /**
442  * qdev_try_new: Try to create a device on the heap
443  * @name: device type to create
444  *
445  * This is like qdev_new(), except it returns %NULL when type @name
446  * does not exist, rather than asserting.
447  *
448  * Return: a derived DeviceState object with a reference count of 1 or
449  * NULL if type @name does not exist.
450  */
451 DeviceState *qdev_try_new(const char *name);
452 
453 /**
454  * qdev_is_realized() - check if device is realized
455  * @dev: The device to check.
456  *
457  * Context: May be called outside big qemu lock.
458  * Return: true if the device has been fully constructed, false otherwise.
459  */
460 static inline bool qdev_is_realized(DeviceState *dev)
461 {
462     return qatomic_load_acquire(&dev->realized);
463 }
464 
465 /**
466  * qdev_realize: Realize @dev.
467  * @dev: device to realize
468  * @bus: bus to plug it into (may be NULL)
469  * @errp: pointer to error object
470  *
471  * "Realize" the device, i.e. perform the second phase of device
472  * initialization.
473  * @dev must not be plugged into a bus already.
474  * If @bus, plug @dev into @bus.  This takes a reference to @dev.
475  * If @dev has no QOM parent, make one up, taking another reference.
476  *
477  * If you created @dev using qdev_new(), you probably want to use
478  * qdev_realize_and_unref() instead.
479  *
480  * Return: true on success, else false setting @errp with error
481  */
482 bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp);
483 
484 /**
485  * qdev_realize_and_unref: Realize @dev and drop a reference
486  * @dev: device to realize
487  * @bus: bus to plug it into (may be NULL)
488  * @errp: pointer to error object
489  *
490  * Realize @dev and drop a reference.
491  * This is like qdev_realize(), except the caller must hold a
492  * (private) reference, which is dropped on return regardless of
493  * success or failure.  Intended use::
494  *
495  *     dev = qdev_new();
496  *     [...]
497  *     qdev_realize_and_unref(dev, bus, errp);
498  *
499  * Now @dev can go away without further ado.
500  *
501  * If you are embedding the device into some other QOM device and
502  * initialized it via some variant on object_initialize_child() then
503  * do not use this function, because that family of functions arrange
504  * for the only reference to the child device to be held by the parent
505  * via the child<> property, and so the reference-count-drop done here
506  * would be incorrect. For that use case you want qdev_realize().
507  *
508  * Return: true on success, else false setting @errp with error
509  */
510 bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp);
511 
512 /**
513  * qdev_unrealize: Unrealize a device
514  * @dev: device to unrealize
515  *
516  * This function will "unrealize" a device, which is the first phase
517  * of correctly destroying a device that has been realized. It will:
518  *
519  *  - unrealize any child buses by calling qbus_unrealize()
520  *    (this will recursively unrealize any devices on those buses)
521  *  - call the unrealize method of @dev
522  *
523  * The device can then be freed by causing its reference count to go
524  * to zero.
525  *
526  * Warning: most devices in QEMU do not expect to be unrealized.  Only
527  * devices which are hot-unpluggable should be unrealized (as part of
528  * the unplugging process); all other devices are expected to last for
529  * the life of the simulation and should not be unrealized and freed.
530  */
531 void qdev_unrealize(DeviceState *dev);
532 void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id,
533                                  int required_for_version);
534 HotplugHandler *qdev_get_bus_hotplug_handler(DeviceState *dev);
535 HotplugHandler *qdev_get_machine_hotplug_handler(DeviceState *dev);
536 bool qdev_hotplug_allowed(DeviceState *dev, Error **errp);
537 
538 /**
539  * qdev_get_hotplug_handler() - Get handler responsible for device wiring
540  * @dev: the device we want the HOTPLUG_HANDLER for.
541  *
542  * Note: in case @dev has a parent bus, it will be returned as handler unless
543  * machine handler overrides it.
544  *
545  * Return: pointer to object that implements TYPE_HOTPLUG_HANDLER interface
546  * or NULL if there aren't any.
547  */
548 HotplugHandler *qdev_get_hotplug_handler(DeviceState *dev);
549 void qdev_unplug(DeviceState *dev, Error **errp);
550 void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev,
551                                   DeviceState *dev, Error **errp);
552 void qdev_machine_creation_done(void);
553 bool qdev_machine_modified(void);
554 
555 /**
556  * qdev_add_unplug_blocker: Add an unplug blocker to a device
557  *
558  * @dev: Device to be blocked from unplug
559  * @reason: Reason for blocking
560  */
561 void qdev_add_unplug_blocker(DeviceState *dev, Error *reason);
562 
563 /**
564  * qdev_del_unplug_blocker: Remove an unplug blocker from a device
565  *
566  * @dev: Device to be unblocked
567  * @reason: Pointer to the Error used with qdev_add_unplug_blocker.
568  *          Used as a handle to lookup the blocker for deletion.
569  */
570 void qdev_del_unplug_blocker(DeviceState *dev, Error *reason);
571 
572 /**
573  * qdev_unplug_blocked: Confirm if a device is blocked from unplug
574  *
575  * @dev: Device to be tested
576  * @errp: The reasons why the device is blocked, if any
577  *
578  * Returns: true (also setting @errp) if device is blocked from unplug,
579  * false otherwise
580  */
581 bool qdev_unplug_blocked(DeviceState *dev, Error **errp);
582 
583 /**
584  * typedef GpioPolarity - Polarity of a GPIO line
585  *
586  * GPIO lines use either positive (active-high) logic,
587  * or negative (active-low) logic.
588  *
589  * In active-high logic (%GPIO_POLARITY_ACTIVE_HIGH), a pin is
590  * active when the voltage on the pin is high (relative to ground);
591  * whereas in active-low logic (%GPIO_POLARITY_ACTIVE_LOW), a pin
592  * is active when the voltage on the pin is low (or grounded).
593  */
594 typedef enum {
595     GPIO_POLARITY_ACTIVE_LOW,
596     GPIO_POLARITY_ACTIVE_HIGH
597 } GpioPolarity;
598 
599 /**
600  * qdev_get_gpio_in: Get one of a device's anonymous input GPIO lines
601  * @dev: Device whose GPIO we want
602  * @n: Number of the anonymous GPIO line (which must be in range)
603  *
604  * Returns the qemu_irq corresponding to an anonymous input GPIO line
605  * (which the device has set up with qdev_init_gpio_in()). The index
606  * @n of the GPIO line must be valid (i.e. be at least 0 and less than
607  * the total number of anonymous input GPIOs the device has); this
608  * function will assert() if passed an invalid index.
609  *
610  * This function is intended to be used by board code or SoC "container"
611  * device models to wire up the GPIO lines; usually the return value
612  * will be passed to qdev_connect_gpio_out() or a similar function to
613  * connect another device's output GPIO line to this input.
614  *
615  * For named input GPIO lines, use qdev_get_gpio_in_named().
616  *
617  * Return: qemu_irq corresponding to anonymous input GPIO line
618  */
619 qemu_irq qdev_get_gpio_in(DeviceState *dev, int n);
620 
621 /**
622  * qdev_get_gpio_in_named: Get one of a device's named input GPIO lines
623  * @dev: Device whose GPIO we want
624  * @name: Name of the input GPIO array
625  * @n: Number of the GPIO line in that array (which must be in range)
626  *
627  * Returns the qemu_irq corresponding to a named input GPIO line
628  * (which the device has set up with qdev_init_gpio_in_named()).
629  * The @name string must correspond to an input GPIO array which exists on
630  * the device, and the index @n of the GPIO line must be valid (i.e.
631  * be at least 0 and less than the total number of input GPIOs in that
632  * array); this function will assert() if passed an invalid name or index.
633  *
634  * For anonymous input GPIO lines, use qdev_get_gpio_in().
635  *
636  * Return: qemu_irq corresponding to named input GPIO line
637  */
638 qemu_irq qdev_get_gpio_in_named(DeviceState *dev, const char *name, int n);
639 
640 /**
641  * qdev_connect_gpio_out: Connect one of a device's anonymous output GPIO lines
642  * @dev: Device whose GPIO to connect
643  * @n: Number of the anonymous output GPIO line (which must be in range)
644  * @pin: qemu_irq to connect the output line to
645  *
646  * This function connects an anonymous output GPIO line on a device
647  * up to an arbitrary qemu_irq, so that when the device asserts that
648  * output GPIO line, the qemu_irq's callback is invoked.
649  * The index @n of the GPIO line must be valid (i.e. be at least 0 and
650  * less than the total number of anonymous output GPIOs the device has
651  * created with qdev_init_gpio_out()); otherwise this function will assert().
652  *
653  * Outbound GPIO lines can be connected to any qemu_irq, but the common
654  * case is connecting them to another device's inbound GPIO line, using
655  * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named().
656  *
657  * It is not valid to try to connect one outbound GPIO to multiple
658  * qemu_irqs at once, or to connect multiple outbound GPIOs to the
659  * same qemu_irq. (Warning: there is no assertion or other guard to
660  * catch this error: the model will just not do the right thing.)
661  * Instead, for fan-out you can use the TYPE_SPLIT_IRQ device: connect
662  * a device's outbound GPIO to the splitter's input, and connect each
663  * of the splitter's outputs to a different device.  For fan-in you
664  * can use the TYPE_OR_IRQ device, which is a model of a logical OR
665  * gate with multiple inputs and one output.
666  *
667  * For named output GPIO lines, use qdev_connect_gpio_out_named().
668  */
669 void qdev_connect_gpio_out(DeviceState *dev, int n, qemu_irq pin);
670 
671 /**
672  * qdev_connect_gpio_out_named: Connect one of a device's named output
673  *                              GPIO lines
674  * @dev: Device whose GPIO to connect
675  * @name: Name of the output GPIO array
676  * @n: Number of the anonymous output GPIO line (which must be in range)
677  * @input_pin: qemu_irq to connect the output line to
678  *
679  * This function connects an anonymous output GPIO line on a device
680  * up to an arbitrary qemu_irq, so that when the device asserts that
681  * output GPIO line, the qemu_irq's callback is invoked.
682  * The @name string must correspond to an output GPIO array which exists on
683  * the device, and the index @n of the GPIO line must be valid (i.e.
684  * be at least 0 and less than the total number of input GPIOs in that
685  * array); this function will assert() if passed an invalid name or index.
686  *
687  * Outbound GPIO lines can be connected to any qemu_irq, but the common
688  * case is connecting them to another device's inbound GPIO line, using
689  * the qemu_irq returned by qdev_get_gpio_in() or qdev_get_gpio_in_named().
690  *
691  * It is not valid to try to connect one outbound GPIO to multiple
692  * qemu_irqs at once, or to connect multiple outbound GPIOs to the
693  * same qemu_irq; see qdev_connect_gpio_out() for details.
694  *
695  * For anonymous output GPIO lines, use qdev_connect_gpio_out().
696  */
697 void qdev_connect_gpio_out_named(DeviceState *dev, const char *name, int n,
698                                  qemu_irq input_pin);
699 
700 /**
701  * qdev_get_gpio_out_connector: Get the qemu_irq connected to an output GPIO
702  * @dev: Device whose output GPIO we are interested in
703  * @name: Name of the output GPIO array
704  * @n: Number of the output GPIO line within that array
705  *
706  * Returns whatever qemu_irq is currently connected to the specified
707  * output GPIO line of @dev. This will be NULL if the output GPIO line
708  * has never been wired up to the anything.  Note that the qemu_irq
709  * returned does not belong to @dev -- it will be the input GPIO or
710  * IRQ of whichever device the board code has connected up to @dev's
711  * output GPIO.
712  *
713  * You probably don't need to use this function -- it is used only
714  * by the platform-bus subsystem.
715  *
716  * Return: qemu_irq associated with GPIO or NULL if un-wired.
717  */
718 qemu_irq qdev_get_gpio_out_connector(DeviceState *dev, const char *name, int n);
719 
720 /**
721  * qdev_intercept_gpio_out: Intercept an existing GPIO connection
722  * @dev: Device to intercept the outbound GPIO line from
723  * @icpt: New qemu_irq to connect instead
724  * @name: Name of the output GPIO array
725  * @n: Number of the GPIO line in the array
726  *
727  * .. note::
728  *   This function is provided only for use by the qtest testing framework
729  *   and is not suitable for use in non-testing parts of QEMU.
730  *
731  * This function breaks an existing connection of an outbound GPIO
732  * line from @dev, and replaces it with the new qemu_irq @icpt, as if
733  * ``qdev_connect_gpio_out_named(dev, icpt, name, n)`` had been called.
734  * The previously connected qemu_irq is returned, so it can be restored
735  * by a second call to qdev_intercept_gpio_out() if desired.
736  *
737  * Return: old disconnected qemu_irq if one existed
738  */
739 qemu_irq qdev_intercept_gpio_out(DeviceState *dev, qemu_irq icpt,
740                                  const char *name, int n);
741 
742 BusState *qdev_get_child_bus(DeviceState *dev, const char *name);
743 
744 /*** Device API.  ***/
745 
746 /**
747  * qdev_init_gpio_in: create an array of anonymous input GPIO lines
748  * @dev: Device to create input GPIOs for
749  * @handler: Function to call when GPIO line value is set
750  * @n: Number of GPIO lines to create
751  *
752  * Devices should use functions in the qdev_init_gpio_in* family in
753  * their instance_init or realize methods to create any input GPIO
754  * lines they need. There is no functional difference between
755  * anonymous and named GPIO lines. Stylistically, named GPIOs are
756  * preferable (easier to understand at callsites) unless a device
757  * has exactly one uniform kind of GPIO input whose purpose is obvious.
758  * Note that input GPIO lines can serve as 'sinks' for IRQ lines.
759  *
760  * See qdev_get_gpio_in() for how code that uses such a device can get
761  * hold of an input GPIO line to manipulate it.
762  */
763 void qdev_init_gpio_in(DeviceState *dev, qemu_irq_handler handler, int n);
764 
765 /**
766  * qdev_init_gpio_out: create an array of anonymous output GPIO lines
767  * @dev: Device to create output GPIOs for
768  * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines
769  * @n: Number of GPIO lines to create
770  *
771  * Devices should use functions in the qdev_init_gpio_out* family
772  * in their instance_init or realize methods to create any output
773  * GPIO lines they need. There is no functional difference between
774  * anonymous and named GPIO lines. Stylistically, named GPIOs are
775  * preferable (easier to understand at callsites) unless a device
776  * has exactly one uniform kind of GPIO output whose purpose is obvious.
777  *
778  * The @pins argument should be a pointer to either a "qemu_irq"
779  * (if @n == 1) or a "qemu_irq []" array (if @n > 1) in the device's
780  * state structure. The device implementation can then raise and
781  * lower the GPIO line by calling qemu_set_irq(). (If anything is
782  * connected to the other end of the GPIO this will cause the handler
783  * function for that input GPIO to be called.)
784  *
785  * See qdev_connect_gpio_out() for how code that uses such a device
786  * can connect to one of its output GPIO lines.
787  *
788  * There is no need to release the @pins allocated array because it
789  * will be automatically released when @dev calls its instance_finalize()
790  * handler.
791  */
792 void qdev_init_gpio_out(DeviceState *dev, qemu_irq *pins, int n);
793 
794 /**
795  * qdev_init_gpio_out_named: create an array of named output GPIO lines
796  * @dev: Device to create output GPIOs for
797  * @pins: Pointer to qemu_irq or qemu_irq array for the GPIO lines
798  * @name: Name to give this array of GPIO lines
799  * @n: Number of GPIO lines to create
800  *
801  * Like qdev_init_gpio_out(), but creates an array of GPIO output lines
802  * with a name. Code using the device can then connect these GPIO lines
803  * using qdev_connect_gpio_out_named().
804  */
805 void qdev_init_gpio_out_named(DeviceState *dev, qemu_irq *pins,
806                               const char *name, int n);
807 
808 /**
809  * qdev_init_gpio_in_named_with_opaque() - create an array of input GPIO lines
810  * @dev: Device to create input GPIOs for
811  * @handler: Function to call when GPIO line value is set
812  * @opaque: Opaque data pointer to pass to @handler
813  * @name: Name of the GPIO input (must be unique for this device)
814  * @n: Number of GPIO lines in this input set
815  */
816 void qdev_init_gpio_in_named_with_opaque(DeviceState *dev,
817                                          qemu_irq_handler handler,
818                                          void *opaque,
819                                          const char *name, int n);
820 
821 /**
822  * qdev_init_gpio_in_named() - create an array of input GPIO lines
823  * @dev: device to add array to
824  * @handler: a &typedef qemu_irq_handler function to call when GPIO is set
825  * @name: Name of the GPIO input (must be unique for this device)
826  * @n: Number of GPIO lines in this input set
827  *
828  * Like qdev_init_gpio_in_named_with_opaque(), but the opaque pointer
829  * passed to the handler is @dev (which is the most commonly desired behaviour).
830  */
831 static inline void qdev_init_gpio_in_named(DeviceState *dev,
832                                            qemu_irq_handler handler,
833                                            const char *name, int n)
834 {
835     qdev_init_gpio_in_named_with_opaque(dev, handler, dev, name, n);
836 }
837 
838 /**
839  * qdev_pass_gpios: create GPIO lines on container which pass through to device
840  * @dev: Device which has GPIO lines
841  * @container: Container device which needs to expose them
842  * @name: Name of GPIO array to pass through (NULL for the anonymous GPIO array)
843  *
844  * In QEMU, complicated devices like SoCs are often modelled with a
845  * "container" QOM device which itself contains other QOM devices and
846  * which wires them up appropriately. This function allows the container
847  * to create GPIO arrays on itself which simply pass through to a GPIO
848  * array of one of its internal devices.
849  *
850  * If @dev has both input and output GPIOs named @name then both will
851  * be passed through. It is not possible to pass a subset of the array
852  * with this function.
853  *
854  * To users of the container device, the GPIO array created on @container
855  * behaves exactly like any other.
856  */
857 void qdev_pass_gpios(DeviceState *dev, DeviceState *container,
858                      const char *name);
859 
860 BusState *qdev_get_parent_bus(const DeviceState *dev);
861 
862 /*** BUS API. ***/
863 
864 DeviceState *qdev_find_recursive(BusState *bus, const char *id);
865 
866 /* Returns 0 to walk children, > 0 to skip walk, < 0 to terminate walk. */
867 typedef int (qbus_walkerfn)(BusState *bus, void *opaque);
868 typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque);
869 
870 void qbus_init(void *bus, size_t size, const char *typename,
871                DeviceState *parent, const char *name);
872 BusState *qbus_new(const char *typename, DeviceState *parent, const char *name);
873 bool qbus_realize(BusState *bus, Error **errp);
874 void qbus_unrealize(BusState *bus);
875 
876 /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion,
877  *         < 0 if either devfn or busfn terminate walk somewhere in cursion,
878  *           0 otherwise. */
879 int qbus_walk_children(BusState *bus,
880                        qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
881                        qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
882                        void *opaque);
883 int qdev_walk_children(DeviceState *dev,
884                        qdev_walkerfn *pre_devfn, qbus_walkerfn *pre_busfn,
885                        qdev_walkerfn *post_devfn, qbus_walkerfn *post_busfn,
886                        void *opaque);
887 
888 /**
889  * device_cold_reset() - perform a recursive cold reset on a device
890  * @dev: device to reset.
891  *
892  * Reset device @dev and perform a recursive processing using the resettable
893  * interface. It triggers a RESET_TYPE_COLD.
894  */
895 void device_cold_reset(DeviceState *dev);
896 
897 /**
898  * bus_cold_reset() - perform a recursive cold reset on a bus
899  * @bus: bus to reset
900  *
901  * Reset bus @bus and perform a recursive processing using the resettable
902  * interface. It triggers a RESET_TYPE_COLD.
903  */
904 void bus_cold_reset(BusState *bus);
905 
906 /**
907  * device_is_in_reset() - check device reset state
908  * @dev: device to check
909  *
910  * Return: true if the device @dev is currently being reset.
911  */
912 bool device_is_in_reset(DeviceState *dev);
913 
914 /**
915  * bus_is_in_reset() - check bus reset state
916  * @bus: bus to check
917  *
918  * Return: true if the bus @bus is currently being reset.
919  */
920 bool bus_is_in_reset(BusState *bus);
921 
922 /* This should go away once we get rid of the NULL bus hack */
923 BusState *sysbus_get_default(void);
924 
925 char *qdev_get_fw_dev_path(DeviceState *dev);
926 char *qdev_get_own_fw_dev_path_from_handler(BusState *bus, DeviceState *dev);
927 
928 /**
929  * device_class_set_props(): add a set of properties to an device
930  * @dc: the parent DeviceClass all devices inherit
931  * @props: an array of properties, terminate by DEFINE_PROP_END_OF_LIST()
932  *
933  * This will add a set of properties to the object. It will fault if
934  * you attempt to add an existing property defined by a parent class.
935  * To modify an inherited property you need to use????
936  */
937 void device_class_set_props(DeviceClass *dc, Property *props);
938 
939 /**
940  * device_class_set_parent_reset() - legacy set device reset handlers
941  * @dc: device class
942  * @dev_reset: function pointer to reset handler
943  * @parent_reset: function pointer to parents reset handler
944  *
945  * Modern code should use the ResettableClass interface to
946  * implement a multi-phase reset instead.
947  *
948  * TODO: remove the function when DeviceClass's reset method
949  * is not used anymore.
950  */
951 void device_class_set_parent_reset(DeviceClass *dc,
952                                    DeviceReset dev_reset,
953                                    DeviceReset *parent_reset);
954 
955 /**
956  * device_class_set_parent_realize() - set up for chaining realize fns
957  * @dc: The device class
958  * @dev_realize: the device realize function
959  * @parent_realize: somewhere to save the parents realize function
960  *
961  * This is intended to be used when the new realize function will
962  * eventually call its parent realization function during creation.
963  * This requires storing the function call somewhere (usually in the
964  * instance structure) so you can eventually call
965  * dc->parent_realize(dev, errp)
966  */
967 void device_class_set_parent_realize(DeviceClass *dc,
968                                      DeviceRealize dev_realize,
969                                      DeviceRealize *parent_realize);
970 
971 
972 /**
973  * device_class_set_parent_unrealize() - set up for chaining unrealize fns
974  * @dc: The device class
975  * @dev_unrealize: the device realize function
976  * @parent_unrealize: somewhere to save the parents unrealize function
977  *
978  * This is intended to be used when the new unrealize function will
979  * eventually call its parent unrealization function during the
980  * unrealize phase. This requires storing the function call somewhere
981  * (usually in the instance structure) so you can eventually call
982  * dc->parent_unrealize(dev);
983  */
984 void device_class_set_parent_unrealize(DeviceClass *dc,
985                                        DeviceUnrealize dev_unrealize,
986                                        DeviceUnrealize *parent_unrealize);
987 
988 const VMStateDescription *qdev_get_vmsd(DeviceState *dev);
989 
990 const char *qdev_fw_name(DeviceState *dev);
991 
992 void qdev_assert_realized_properly(void);
993 Object *qdev_get_machine(void);
994 
995 /**
996  * qdev_get_human_name() - Return a human-readable name for a device
997  * @dev: The device. Must be a valid and non-NULL pointer.
998  *
999  * .. note::
1000  *    This function is intended for user friendly error messages.
1001  *
1002  * Returns: A newly allocated string containing the device id if not null,
1003  * else the object canonical path.
1004  *
1005  * Use g_free() to free it.
1006  */
1007 char *qdev_get_human_name(DeviceState *dev);
1008 
1009 /* FIXME: make this a link<> */
1010 bool qdev_set_parent_bus(DeviceState *dev, BusState *bus, Error **errp);
1011 
1012 extern bool qdev_hot_removed;
1013 
1014 char *qdev_get_dev_path(DeviceState *dev);
1015 
1016 void qbus_set_hotplug_handler(BusState *bus, Object *handler);
1017 void qbus_set_bus_hotplug_handler(BusState *bus);
1018 
1019 static inline bool qbus_is_hotpluggable(BusState *bus)
1020 {
1021     HotplugHandler *plug_handler = bus->hotplug_handler;
1022     bool ret = !!plug_handler;
1023 
1024     if (plug_handler) {
1025         HotplugHandlerClass *hdc;
1026 
1027         hdc = HOTPLUG_HANDLER_GET_CLASS(plug_handler);
1028         if (hdc->is_hotpluggable_bus) {
1029             ret = hdc->is_hotpluggable_bus(plug_handler, bus);
1030         }
1031     }
1032     return ret;
1033 }
1034 
1035 /**
1036  * qbus_mark_full: Mark this bus as full, so no more devices can be attached
1037  * @bus: Bus to mark as full
1038  *
1039  * By default, QEMU will allow devices to be plugged into a bus up
1040  * to the bus class's device count limit. Calling this function
1041  * marks a particular bus as full, so that no more devices can be
1042  * plugged into it. In particular this means that the bus will not
1043  * be considered as a candidate for plugging in devices created by
1044  * the user on the commandline or via the monitor.
1045  * If a machine has multiple buses of a given type, such as I2C,
1046  * where some of those buses in the real hardware are used only for
1047  * internal devices and some are exposed via expansion ports, you
1048  * can use this function to mark the internal-only buses as full
1049  * after you have created all their internal devices. Then user
1050  * created devices will appear on the expansion-port bus where
1051  * guest software expects them.
1052  */
1053 static inline void qbus_mark_full(BusState *bus)
1054 {
1055     bus->full = true;
1056 }
1057 
1058 void device_listener_register(DeviceListener *listener);
1059 void device_listener_unregister(DeviceListener *listener);
1060 
1061 /**
1062  * qdev_should_hide_device() - check if device should be hidden
1063  *
1064  * @opts: options QDict
1065  * @from_json: true if @opts entries are typed, false for all strings
1066  * @errp: pointer to error object
1067  *
1068  * When a device is added via qdev_device_add() this will be called.
1069  *
1070  * Return: if the device should be added now or not.
1071  */
1072 bool qdev_should_hide_device(const QDict *opts, bool from_json, Error **errp);
1073 
1074 typedef enum MachineInitPhase {
1075     /* current_machine is NULL.  */
1076     PHASE_NO_MACHINE,
1077 
1078     /* current_machine is not NULL, but current_machine->accel is NULL.  */
1079     PHASE_MACHINE_CREATED,
1080 
1081     /*
1082      * current_machine->accel is not NULL, but the machine properties have
1083      * not been validated and machine_class->init has not yet been called.
1084      */
1085     PHASE_ACCEL_CREATED,
1086 
1087     /*
1088      * Late backend objects have been created and initialized.
1089      */
1090     PHASE_LATE_BACKENDS_CREATED,
1091 
1092     /*
1093      * machine_class->init has been called, thus creating any embedded
1094      * devices and validating machine properties.  Devices created at
1095      * this time are considered to be cold-plugged.
1096      */
1097     PHASE_MACHINE_INITIALIZED,
1098 
1099     /*
1100      * QEMU is ready to start CPUs and devices created at this time
1101      * are considered to be hot-plugged.  The monitor is not restricted
1102      * to "preconfig" commands.
1103      */
1104     PHASE_MACHINE_READY,
1105 } MachineInitPhase;
1106 
1107 bool phase_check(MachineInitPhase phase);
1108 void phase_advance(MachineInitPhase phase);
1109 
1110 #endif
1111