include/hw/qdev-core.h

14  * DOC: The QEMU Device API
17  * TYPE_DEVICE. The device API introduces the additional methods of
18  * @realize and @unrealize to represent additional stages in a device
27  * 2) device realization via the #DeviceState.realized property
30  * during device introspection already), and the latter may return error
56  * Hiding a device
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
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
66  * other device. Otherwise qdev_device_add() will return early without
67  * adding the device. The guest will not see a "hidden" device until
76 #define TYPE_DEVICE "device"
77 OBJECT_DECLARE_TYPE(DeviceState, DeviceClass, DEVICE)
107  * @sync_config: Callback function invoked when QMP command device-sync-config
108  * is called. Should synchronize device configuration from host to guest part
121      * @categories: device categories device belongs to
125      * @fw_name: name used to identify device to firmware interfaces
129      * @desc: human readable description of device
134      * @props_: properties associated with device, should only be
148      * @user_creatable: Can user instantiate with -device / device_add?
165      * @legacy_reset: deprecated device reset method pointer
178      * @vmsd: device state serialisation description for
221  * struct DeviceState - common device state, accessed with qdev helpers
224  * so that it can be embedded in individual device state structures.
232      * @id: global device id
236      * @canonical_path: canonical path of realized device in the QOM tree
240      * @realized: has device been realized?
252      * @hotplugged: was device added after PHASE_MACHINE_READY?
256      * @allow_unplug_during_migration: can device be unplugged during migration
260      * @parent_bus: bus this device belongs to
264      * @gpios: QLIST of named GPIOs the device provides.
268      * @clocks: QLIST of named clocks the device provides.
280      * @instance_id_alias: device alias for handling legacy migration setups
289      * @reset: ResettableState for the device; handled by Resettable interface.
293      * @unplug_blockers: list of reasons to block unplugging of device
297      * @mem_reentrancy_guard: Is the device currently in mmio/pio/dma?
310      * informs qdev if a device should be visible or hidden.  We can
311      * hide a failover device depending for example on the device
314      * On errors, it returns false and errp is set. Device creation
334      * This callback is used to create Open Firmware device path in accordance
341      * Return whether the device can be added to @bus,
342      * based on the address that was set (via device properties)
372  * @parent: parent Device
410  * @used: Set to true if property was used when initializing a device.
437  * qdev_new: Create a device on the heap
438  * @name: device type to create (we assert() that this type exists)
440  * This only allocates the memory and initializes the device state
442  * The device still needs to be realized.
449  * qdev_try_new: Try to create a device on the heap
450  * @name: device type to create
461  * qdev_is_realized() - check if device is realized
462  * @dev: The device to check.
465  * Return: true if the device has been fully constructed, false otherwise.
474  * @dev: device to realize
478  * "Realize" the device, i.e. perform the second phase of device
493  * @dev: device to realize
508  * If you are embedding the device into some other QOM device and
511  * for the only reference to the child device to be held by the parent
520  * qdev_unrealize: Unrealize a device
521  * @dev: device to unrealize
523  * This function will "unrealize" a device, which is the first phase
524  * of correctly destroying a device that has been realized. It will:
530  * The device can then be freed by causing its reference count to go
547  * qdev_get_hotplug_handler() - Get handler responsible for device wiring
548  * @dev: the device we want the HOTPLUG_HANDLER for.
565  * qdev_add_unplug_blocker: Add an unplug blocker to a device
567  * @dev: Device to be blocked from unplug
573  * qdev_del_unplug_blocker: Remove an unplug blocker from a device
575  * @dev: Device to be unblocked
582  * qdev_unplug_blocked: Confirm if a device is blocked from unplug
584  * @dev: Device to be tested
585  * @errp: The reasons why the device is blocked, if any
587  * Returns: true (also setting @errp) if device is blocked from unplug,
609  * qdev_get_gpio_in: Get one of a device's anonymous input GPIO lines
610  * @dev: Device whose GPIO we want
614  * (which the device has set up with qdev_init_gpio_in()). The index
616  * the total number of anonymous input GPIOs the device has); this
620  * device models to wire up the GPIO lines; usually the return value
622  * connect another device's output GPIO line to this input.
631  * qdev_get_gpio_in_named: Get one of a device's named input GPIO lines
632  * @dev: Device whose GPIO we want
637  * in a named array of input GPIO lines on a device (which the device
640  * the device, and the index @n of the GPIO line must be valid (i.e.
651  * qdev_connect_gpio_out: Connect one of a device's anonymous output GPIO lines
652  * @dev: Device whose GPIO to connect
656  * This function connects an anonymous output GPIO line on a device
657  * up to an arbitrary qemu_irq, so that when the device asserts that
660  * less than the total number of anonymous output GPIOs the device has
664  * case is connecting them to another device's inbound GPIO line, using
671  * Instead, for fan-out you can use the TYPE_SPLIT_IRQ device: connect
672  * a device's outbound GPIO to the splitter's input, and connect each
673  * of the splitter's outputs to a different device.  For fan-in you
674  * can use the TYPE_OR_IRQ device, which is a model of a logical OR
682  * qdev_connect_gpio_out_named: Connect one of a device's named output
684  * @dev: Device whose GPIO to connect
690  * GPIO lines on a device up to an arbitrary qemu_irq, so that when the
691  * device asserts that output GPIO line, the qemu_irq's callback is invoked.
693  * the device, and the index @n of the GPIO line must be valid (i.e.
698  * case is connecting them to another device's inbound GPIO line, using
712  * @dev: Device whose output GPIO we are interested in
720  * IRQ of whichever device the board code has connected up to @dev's
732  * @dev: Device to intercept the outbound GPIO line from
754 /*** Device API.  ***/
758  * @dev: Device to create input GPIOs for
766  * preferable (easier to understand at callsites) unless a device
770  * See qdev_get_gpio_in() for how code that uses such a device can get
777  * @dev: Device to create output GPIOs for
785  * preferable (easier to understand at callsites) unless a device
789  * (if @n == 1) or a "qemu_irq []" array (if @n > 1) in the device's
790  * state structure. The device implementation can then raise and
795  * See qdev_connect_gpio_out() for how code that uses such a device
806  * @dev: Device to create output GPIOs for
812  * with a name. Code using the device can then connect these GPIO lines
820  * @dev: Device to create input GPIOs for
823  * @name: Name of the GPIO input (must be unique for this device)
833  * @dev: device to add array to
835  * @name: Name of the GPIO input (must be unique for this device)
849  * qdev_pass_gpios: create GPIO lines on container which pass through to device
850  * @dev: Device which has GPIO lines
851  * @container: Container device which needs to expose them
855  * "container" QOM device which itself contains other QOM devices and
864  * To users of the container device, the GPIO array created on @container
899  * device_cold_reset() - perform a recursive cold reset on a device
900  * @dev: device to reset.
902  * Reset device @dev and perform a recursive processing using the resettable
917  * device_is_in_reset() - check device reset state
918  * @dev: device to check
920  * Return: true if the device @dev is currently being reset.
939  * device_class_set_props(): add a set of properties to an device
963  * device_class_set_props_n(): add a set of properties to an device
976  * @dc: The device class
977  * @dev_realize: the device realize function
992  * @dc: The device class
1006  * @dc: The device class
1007  * @dev_unrealize: the device realize function
1048  * qdev_get_human_name() - Return a human-readable name for a device
1049  * @dev: The device. Must be a valid and non-NULL pointer.
1054  * Returns: A newly allocated string containing the device id if not null,
1092  * to the bus class's device count limit. Calling this function
1114  * qdev_should_hide_device() - check if device should be hidden
1120  * When a device is added via qdev_device_add() this will be called.
1122  * Return: if the device should be added now or not.