diff options
| -rw-r--r-- | hw/core/qdev.c | 33 | ||||
| -rw-r--r-- | include/hw/qdev-core.h | 57 | ||||
| -rw-r--r-- | include/hw/qdev-properties.h | 13 |
3 files changed, 70 insertions, 33 deletions
diff --git a/hw/core/qdev.c b/hw/core/qdev.c index 01796823b4..96772a15bd 100644 --- a/hw/core/qdev.c +++ b/hw/core/qdev.c @@ -128,13 +128,6 @@ void qdev_set_parent_bus(DeviceState *dev, BusState *bus) } } -/* - * Create a device on the heap. - * A type @name must exist. - * This only initializes the device state structure and allows - * properties to be set. The device still needs to be realized. See - * qdev-core.h. - */ DeviceState *qdev_new(const char *name) { if (!object_class_by_name(name)) { @@ -143,11 +136,6 @@ DeviceState *qdev_new(const char *name) return DEVICE(object_new(name)); } -/* - * Try to create a device on the heap. - * This is like qdev_new(), except it returns %NULL when type @name - * does not exist. - */ DeviceState *qdev_try_new(const char *name) { if (!module_object_class_by_name(name)) { @@ -378,14 +366,6 @@ void qdev_simple_device_unplug_cb(HotplugHandler *hotplug_dev, qdev_unrealize(dev); } -/* - * Realize @dev. - * @dev must not be plugged into a bus. - * If @bus, plug @dev into @bus. This takes a reference to @dev. - * If @dev has no QOM parent, make one up, taking another reference. - * On success, return true. - * On failure, store an error through @errp and return false. - */ bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp) { assert(!dev->realized && !dev->parent_bus); @@ -399,16 +379,6 @@ bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp) return object_property_set_bool(OBJECT(dev), "realized", true, errp); } -/* - * Realize @dev and drop a reference. - * This is like qdev_realize(), except the caller must hold a - * (private) reference, which is dropped on return regardless of - * success or failure. Intended use: - * dev = qdev_new(); - * [...] - * qdev_realize_and_unref(dev, bus, errp); - * Now @dev can go away without further ado. - */ bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp) { bool ret; @@ -814,9 +784,6 @@ static void qdev_class_add_property(DeviceClass *klass, Property *prop) prop->info->description); } -/* @qdev_alias_all_properties - Add alias properties to the source object for - * all qdev properties on the target DeviceState. - */ void qdev_alias_all_properties(DeviceState *target, Object *source) { ObjectClass *class; diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h index fe78073c70..2d441d1fb2 100644 --- a/include/hw/qdev-core.h +++ b/include/hw/qdev-core.h @@ -320,9 +320,66 @@ compat_props_add(GPtrArray *arr, /*** Board API. This should go away once we have a machine config file. ***/ +/** + * qdev_new: Create a device on the heap + * @name: device type to create (we assert() that this type exists) + * + * This only allocates the memory and initializes the device state + * structure, ready for the caller to set properties if they wish. + * The device still needs to be realized. + * The returned object has a reference count of 1. + */ DeviceState *qdev_new(const char *name); +/** + * qdev_try_new: Try to create a device on the heap + * @name: device type to create + * + * This is like qdev_new(), except it returns %NULL when type @name + * does not exist, rather than asserting. + */ DeviceState *qdev_try_new(const char *name); +/** + * qdev_realize: Realize @dev. + * @dev: device to realize + * @bus: bus to plug it into (may be NULL) + * @errp: pointer to error object + * + * "Realize" the device, i.e. perform the second phase of device + * initialization. + * @dev must not be plugged into a bus already. + * If @bus, plug @dev into @bus. This takes a reference to @dev. + * If @dev has no QOM parent, make one up, taking another reference. + * On success, return true. + * On failure, store an error through @errp and return false. + * + * If you created @dev using qdev_new(), you probably want to use + * qdev_realize_and_unref() instead. + */ bool qdev_realize(DeviceState *dev, BusState *bus, Error **errp); +/** + * qdev_realize_and_unref: Realize @dev and drop a reference + * @dev: device to realize + * @bus: bus to plug it into (may be NULL) + * @errp: pointer to error object + * + * Realize @dev and drop a reference. + * This is like qdev_realize(), except the caller must hold a + * (private) reference, which is dropped on return regardless of + * success or failure. Intended use:: + * + * dev = qdev_new(); + * [...] + * qdev_realize_and_unref(dev, bus, errp); + * + * Now @dev can go away without further ado. + * + * If you are embedding the device into some other QOM device and + * initialized it via some variant on object_initialize_child() then + * do not use this function, because that family of functions arrange + * for the only reference to the child device to be held by the parent + * via the child<> property, and so the reference-count-drop done here + * would be incorrect. For that use case you want qdev_realize(). + */ bool qdev_realize_and_unref(DeviceState *dev, BusState *bus, Error **errp); void qdev_unrealize(DeviceState *dev); void qdev_set_legacy_instance_id(DeviceState *dev, int alias_id, diff --git a/include/hw/qdev-properties.h b/include/hw/qdev-properties.h index 587e5b7d31..8f3a98cba6 100644 --- a/include/hw/qdev-properties.h +++ b/include/hw/qdev-properties.h @@ -282,6 +282,19 @@ void error_set_from_qdev_prop_error(Error **errp, int ret, DeviceState *dev, */ void qdev_property_add_static(DeviceState *dev, Property *prop); +/** + * qdev_alias_all_properties: Create aliases on source for all target properties + * @target: Device which has properties to be aliased + * @source: Object to add alias properties to + * + * Add alias properties to the @source object for all qdev properties on + * the @target DeviceState. + * + * This is useful when @target is an internal implementation object + * owned by @source, and you want to expose all the properties of that + * implementation object as properties on the @source object so that users + * of @source can set them. + */ void qdev_alias_all_properties(DeviceState *target, Object *source); /** |