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