From nobody Tue Nov 4 22:01:30 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1531424855375183.10751141490323; Thu, 12 Jul 2018 12:47:35 -0700 (PDT) Received: from localhost ([::1]:33759 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhYo-0000Y8-Tu for importer@patchew.org; Thu, 12 Jul 2018 15:47:30 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47787) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhX2-00089H-MW for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fdhX1-0001My-4L for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:40 -0400 Received: from mx1.redhat.com ([209.132.183.28]:48252) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fdhX0-0001MM-N9 for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:39 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id D15B13082146; Thu, 12 Jul 2018 19:45:37 +0000 (UTC) Received: from localhost (ovpn-116-12.gru2.redhat.com [10.97.116.12]) by smtp.corp.redhat.com (Postfix) with ESMTP id 321A71001947; Thu, 12 Jul 2018 19:45:32 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Date: Thu, 12 Jul 2018 16:45:20 -0300 Message-Id: <20180712194522.31063-2-ehabkost@redhat.com> In-Reply-To: <20180712194522.31063-1-ehabkost@redhat.com> References: <20180712194522.31063-1-ehabkost@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.42]); Thu, 12 Jul 2018 19:45:37 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [RFC 1/3] qom: Document reference count ownership rules X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" The documentation for QOM is not clear about who owns references to objects (i.e. who is responsible for calling object_unref() later). This is important considering there are a few inconsistencies in the API (e.g. callers of object_new() need to call object_unref() later, but callers of object_new_with_props() must not do it). Update the documentation so that every mention of object references also mention who exactly owns the reference. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 73 +++++++++++++++++++++++++------------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index f3d2308d56..08a1bbba7d 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -376,7 +376,7 @@ typedef void (ObjectUnparent)(Object *obj); * ObjectFree: * @obj: the object being freed * - * Called when an object's last reference is removed. + * Called when an object's last reference is dropped using object_unref(). */ typedef void (ObjectFree)(void *obj); =20 @@ -601,8 +601,8 @@ struct InterfaceClass * @typename: The name of the type of the object to instantiate. * * This function will initialize a new object using heap allocated memory. - * The returned object has a reference count of 1, and will be freed when - * the last reference is dropped. + * The returned object has a reference count of 1, and the reference will = be + * owned by the caller. * * Returns: The newly allocated and instantiated object. */ @@ -617,8 +617,8 @@ Object *object_new(const char *typename); * @...: list of property names and values * * This function will initialize a new object using heap allocated memory. - * The returned object has a reference count of 1, and will be freed when - * the last reference is dropped. + * The returned object has a reference count of 1, and the reference will + * be owned by the caller. * * The @id parameter will be used when registering the object as a * child of @parent in the composition tree. @@ -652,8 +652,8 @@ Object *object_new(const char *typename); * * * - * The returned object will have one stable reference maintained - * for as long as it is present in the object hierarchy. + * The returned object will have one reference, owned by the + * parent object (not by the caller). * * Returns: The newly allocated, instantiated & initialized object. */ @@ -713,9 +713,6 @@ Object *object_new_with_propv(const char *typename, * * * - * The returned object will have one stable reference maintained - * for as long as it is present in the object hierarchy. - * * Returns: -1 on error, 0 on success */ int object_set_props(Object *obj, @@ -744,7 +741,7 @@ int object_set_propv(Object *obj, * * This function will initialize an object. The memory for the object sho= uld * have already been allocated. The returned object has a reference count= of 1, - * and will be finalized when the last reference is dropped. + * and the reference will be owned by the caller. */ void object_initialize(void *obj, size_t size, const char *typename); =20 @@ -928,8 +925,12 @@ GSList *object_class_get_list_sorted(const char *imple= ments_type, * object_ref: * @obj: the object * - * Increase the reference count of a object. A object cannot be freed as = long - * as its reference count is greater than zero. + * Increase the reference count of a object. A object won't be freed as + * long as its reference count is greater than zero. + * + * The new reference will be owned by the caller, meaning the caller is + * responsible for ensuring object_unref() will be called once the + * reference is not needed anymore. */ void object_ref(Object *obj); =20 @@ -937,8 +938,10 @@ void object_ref(Object *obj); * object_unref: * @obj: the object * - * Decrease the reference count of a object. A object cannot be freed as = long - * as its reference count is greater than zero. + * Drop a reference to a object, decreasing its reference count. This + * function should be called only if the caller owns a reference taken usi= ng + * object_ref() or returned by functions like object_initialize() and + * object_new(). */ void object_unref(Object *obj); =20 @@ -1104,10 +1107,13 @@ char *object_property_get_str(Object *obj, const ch= ar *name, * * Writes an object's canonical path to a property. * - * If the link property was created with - * OBJ_PROP_LINK_STRONG bit, the old target object is - * unreferenced, and a reference is added to the new target object. + * If the link property was created with OBJ_PROP_LINK_STRONG + * bit, the property will take a reference to the object, and drop + * a reference to the old object. * + * If OBJ_PROP_LINK_STRONG was not set for the property, the + * caller is responsible for ensuring the object will stay alive until the + * property is modified or deleted. */ void object_property_set_link(Object *obj, Object *value, const char *name, Error **errp); @@ -1398,7 +1404,10 @@ void object_property_add_child(Object *obj, const ch= ar *name, Object *child, Error **errp); =20 typedef enum { - /* Unref the link pointer when the property is deleted */ + /* + * Property owns a reference to the target object. Unref the link + * pointer when the property is modified or deleted. + */ OBJ_PROP_LINK_STRONG =3D 0x1, } ObjectPropertyLinkFlags; =20 @@ -1433,13 +1442,14 @@ void object_property_allow_set_link(const Object *,= const char *, * link being set. If @check is NULL, the property is read-o= nly * and cannot be set. * - * Ownership of the pointer that @child points to is transferred to the - * link property. The reference count for *@child is - * managed by the property from after the function returns till the - * property is deleted with object_property_del(). If the - * @flags OBJ_PROP_LINK_STRONG bit is set, - * the reference count is decremented when the property is deleted or - * modified. + * If the OBJ_PROP_LINK_STRONG bit is set in @flags, + * ownership of the pointer that @child points to is transferred to the + * link property, and the reference will be dropped when the property is + * modified or deleted with object_property_del(). + * + * If OBJ_PROP_LINK_STRONG is not set in @flags, the caller + * is responsible for ensuring the object pointed by @child will stay alive + * until the property is modified or deleted. */ void object_property_add_link(Object *obj, const char *name, const char *type, Object **child, @@ -1607,7 +1617,8 @@ void object_class_property_add_uint64_ptr(ObjectClass= *klass, const char *name, * Add an alias for a property on an object. This function will add a pro= perty * of the same type as the forwarded property. * - * The caller must ensure that @target_obj stays alive as lon= g as + * The property won't take a reference to @target_obj, so the + * caller must ensure that @target_obj stays alive as long as * this property exists. In the case of a child object or an alias on the= same * object this will be the case. For aliases to other objects the caller = is * responsible for taking a reference. @@ -1626,10 +1637,10 @@ void object_property_add_alias(Object *obj, const c= har *name, * Add an unmodifiable link for a property on an object. This function wi= ll * add a property of type link where TYPE is the type of @target. * - * The caller must ensure that @target stays alive as long as - * this property exists. In the case @target is a child of @obj, - * this will be the case. Otherwise, the caller is responsible for - * taking a reference. + * The property won't take a reference to @target_obj, so the + * caller must ensure that @target stays alive as long as this property + * exists. In the case @target is a child of @obj, this will be the case. + * Otherwise, the caller is responsible for taking a reference. */ void object_property_add_const_link(Object *obj, const char *name, Object *target, Error **errp); --=20 2.18.0.rc1.1.g3f1ff2140 From nobody Tue Nov 4 22:01:30 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1531424966766972.3899055378104; Thu, 12 Jul 2018 12:49:26 -0700 (PDT) Received: from localhost ([::1]:33769 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhab-0001sy-Qg for importer@patchew.org; Thu, 12 Jul 2018 15:49:21 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47842) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhX9-0008D8-Fi for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:48 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fdhX6-0001S2-D8 for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:47 -0400 Received: from mx1.redhat.com ([209.132.183.28]:47178) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fdhX6-0001RC-4c for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:44 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 5328630001DA; Thu, 12 Jul 2018 19:45:43 +0000 (UTC) Received: from localhost (ovpn-116-12.gru2.redhat.com [10.97.116.12]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3C80760F86; Thu, 12 Jul 2018 19:45:39 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Date: Thu, 12 Jul 2018 16:45:21 -0300 Message-Id: <20180712194522.31063-3-ehabkost@redhat.com> In-Reply-To: <20180712194522.31063-1-ehabkost@redhat.com> References: <20180712194522.31063-1-ehabkost@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.41]); Thu, 12 Jul 2018 19:45:43 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [RFC 2/3] qdev: Document ownership rules of qbus_create*() X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" The ownership rules of those functions aren't trivial: the caller owns the new object if parent is NULL, otherwise ownership is transferred to the parent. Clarify that on comments. Signed-off-by: Eduardo Habkost Reviewed-by: Marcel Apfelbaum --- include/hw/qdev-core.h | 24 ++++++++++++++++++++++++ hw/core/bus.c | 5 +++++ 2 files changed, 29 insertions(+) diff --git a/include/hw/qdev-core.h b/include/hw/qdev-core.h index f1fd0f8736..27d1ac3781 100644 --- a/include/hw/qdev-core.h +++ b/include/hw/qdev-core.h @@ -343,8 +343,32 @@ DeviceState *qdev_find_recursive(BusState *bus, const = char *id); typedef int (qbus_walkerfn)(BusState *bus, void *opaque); typedef int (qdev_walkerfn)(DeviceState *dev, void *opaque); =20 +/** + * qbus_create_inplace: + * @bus: A pointer to the memory to be used for the bus object. + * @size: The maximum size available at @bus for the bus object. + * @typename: The name of the type of bus to instantiate. + * @parent: parent device + * @name: name for the new bus + * + * Creates bus in place. + * + * If @parent is not NULL the bus will be owned by @parent, otherwise + * the bus will be owned by the caller. + */ void qbus_create_inplace(void *bus, size_t size, const char *typename, DeviceState *parent, const char *name); +/** + * qbus_create: + * @typename: The name of the type of bus to instantiate. + * @parent: parent device + * @name: name for the new bus + * + * Creates bus object. + * + * If @parent is not NULL the returned object will be owned by @parent, + * otherwise it will be owned by the caller. + */ BusState *qbus_create(const char *typename, DeviceState *parent, const cha= r *name); /* Returns > 0 if either devfn or busfn skip walk somewhere in cursion, * < 0 if either devfn or busfn terminate walk somewhere in cursio= n, diff --git a/hw/core/bus.c b/hw/core/bus.c index 4651f24486..68a0d5b085 100644 --- a/hw/core/bus.c +++ b/hw/core/bus.c @@ -74,6 +74,7 @@ int qbus_walk_children(BusState *bus, return 0; } =20 +/* If @parent is not NULL, ownership of @bus is transferred to @parent */ static void qbus_realize(BusState *bus, DeviceState *parent, const char *n= ame) { const char *typename =3D object_get_typename(OBJECT(bus)); @@ -102,6 +103,10 @@ static void qbus_realize(BusState *bus, DeviceState *p= arent, const char *name) QLIST_INSERT_HEAD(&bus->parent->child_bus, bus, sibling); bus->parent->num_child_bus++; object_property_add_child(OBJECT(bus->parent), bus->name, OBJECT(b= us), NULL); + /* + * object_property_add_child() takes a new reference, drop the + * reference that was transferred to us. + */ object_unref(OBJECT(bus)); } else if (bus !=3D sysbus_get_default()) { /* TODO: once all bus devices are qdevified, --=20 2.18.0.rc1.1.g3f1ff2140 From nobody Tue Nov 4 22:01:30 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1531424875404447.6504688678858; Thu, 12 Jul 2018 12:47:55 -0700 (PDT) Received: from localhost ([::1]:33760 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhZ9-0000oe-5v for importer@patchew.org; Thu, 12 Jul 2018 15:47:51 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47872) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdhXE-0008H7-H3 for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fdhXD-0001a3-Ha for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:52 -0400 Received: from mx1.redhat.com ([209.132.183.28]:44090) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fdhXD-0001ZH-BE for qemu-devel@nongnu.org; Thu, 12 Jul 2018 15:45:51 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 85BA4C03D470; Thu, 12 Jul 2018 19:45:50 +0000 (UTC) Received: from localhost (ovpn-116-12.gru2.redhat.com [10.97.116.12]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9582360910; Thu, 12 Jul 2018 19:45:44 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Date: Thu, 12 Jul 2018 16:45:22 -0300 Message-Id: <20180712194522.31063-4-ehabkost@redhat.com> In-Reply-To: <20180712194522.31063-1-ehabkost@redhat.com> References: <20180712194522.31063-1-ehabkost@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.31]); Thu, 12 Jul 2018 19:45:50 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [RFC 3/3] pci: Document ownership rules of pci_root_bus_new*() X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" The ownership rules of pci_root_bus_new*() aren't trivial: the caller owns the new object if parent is NULL, otherwise ownership is transferred to the parent. Clarify that on comments. Signed-off-by: Eduardo Habkost Reviewed-by: Marcel Apfelbaum --- include/hw/pci/pci.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/include/hw/pci/pci.h b/include/hw/pci/pci.h index 990d6fcbde..5d445c431c 100644 --- a/include/hw/pci/pci.h +++ b/include/hw/pci/pci.h @@ -396,15 +396,30 @@ typedef PCIINTxRoute (*pci_route_irq_fn)(void *opaque= , int pin); =20 bool pci_bus_is_express(PCIBus *bus); bool pci_bus_is_root(PCIBus *bus); + +/** + * pci_root_bus_new_inplace: + * +* If @parent is not NULL the returned object will be owned by @parent, +* otherwise it will be owned by the caller. +*/ void pci_root_bus_new_inplace(PCIBus *bus, size_t bus_size, DeviceState *p= arent, const char *name, MemoryRegion *address_space_mem, MemoryRegion *address_space_io, uint8_t devfn_min, const char *typename); + +/** + * pci_root_bus_new: + * +* If @parent is not NULL the returned object will be owned by @parent, +* otherwise it will be owned by the caller. +*/ PCIBus *pci_root_bus_new(DeviceState *parent, const char *name, MemoryRegion *address_space_mem, MemoryRegion *address_space_io, uint8_t devfn_min, const char *typename); + void pci_bus_irqs(PCIBus *bus, pci_set_irq_fn set_irq, pci_map_irq_fn map_= irq, void *irq_opaque, int nirq); int pci_bus_get_irq_level(PCIBus *bus, int irq_num); --=20 2.18.0.rc1.1.g3f1ff2140