From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776339; cv=none; d=zohomail.com; s=zohoarc; b=LZ+0cZe4c4Cqtl6g0cmWHgmEEcx7qs127h7X2jCwY/V9NuJ6zQEThPFVbSwRq3QYeVPq+WDQD+UIgtHCWifrGkdhRTvdveG1GbJ1tTa4S20pmFGJmpPZxJ0xXc/W9RoL/bUWvKoZcacwHx3lsXw8qRUMZA/pH2ImJfI8+8J/ws8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776339; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=60kJRWsv9vXT2j/z3MQG9A7zs7ChKkqbd7xOBFxgyCY=; b=Ie9T5F/L8LVpS/Apl9fH30meQmDAASRvY+rZelTPGInueGChq8+Do6Wt3H0VzHFukZ6klK4ideGXmQ/KwlRzV5qnc73iqJ54LwFepBcAozGxoaWRlNbIFfoMOTBMPYqGHLGWaZ5kjsIE0X8NLMFdWH65jqh2eea2uE5YWWWXH7Y= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776339111717.003920397082; Thu, 10 Sep 2020 15:18:59 -0700 (PDT) Received: from localhost ([::1]:51466 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGUu9-0006hM-TM for importer@patchew.org; Thu, 10 Sep 2020 18:18:57 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58596) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUqs-0001N1-Q7 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:55758) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqq-0002Y6-K1 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:34 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-422-4tHtf9T2N8SVd7_jIjDE8A-1; Thu, 10 Sep 2020 18:15:29 -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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3905A1084C83; Thu, 10 Sep 2020 22:15:28 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id ED4F260BF1; Thu, 10 Sep 2020 22:15:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776131; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=60kJRWsv9vXT2j/z3MQG9A7zs7ChKkqbd7xOBFxgyCY=; b=O0wiLpLcWExXzfqF0U11/gYfG9DJhU2Ajq27JUNMgAd1HifSFpcvTY93Y++yYCptpSLD6m Q6ilYrqcPvDP7bb/DcBvZmqan6yJD73527ShbaTjoHI/gBEdmW/6ouKGChasyqWF8E8yiZ TQezU43Sd5sNT1OLcnWQPh1l/ILEQ7o= X-MC-Unique: 4tHtf9T2N8SVd7_jIjDE8A-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 1/9] qom: Document all function parameters in doc comments Date: Thu, 10 Sep 2020 18:15:18 -0400 Message-Id: <20200910221526.10041-2-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.001 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=63.128.21.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:31 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" kernel-doc requires all function parameters to be documented, so document them all. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 47 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index 056f67ab3b..ad2b91ec6c 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -1176,6 +1176,11 @@ Object *object_dynamic_cast(Object *obj, const char = *typename); =20 /** * object_dynamic_cast_assert: + * @obj: The object to cast. + * @typename: The @typename to cast to. + * @file: Source code file where function was called + * @line: Source code line where function was called + * @func: Name of function where this function was called * * See object_dynamic_cast() for a description of the parameters of this * function. The only difference in behavior is that this function asserts @@ -1252,6 +1257,9 @@ type_init(do_qemu_init_ ## type_array) * object_class_dynamic_cast_assert: * @klass: The #ObjectClass to attempt to cast. * @typename: The QOM typename of the class to cast to. + * @file: Source code file where function was called + * @line: Source code line where function was called + * @func: Name of function where this function was called * * See object_class_dynamic_cast() for a description of the parameters * of this function. The only difference in behavior is that this function @@ -1403,6 +1411,23 @@ ObjectProperty *object_property_try_add(Object *obj,= const char *name, * object_property_add: * Same as object_property_try_add() with @errp hardcoded to * &error_abort. + * + * @obj: the object to add a property to + * @name: the name of the property. This can contain any character except= for + * a forward slash. In general, you should use hyphens '-' instead of + * underscores '_' when naming properties. + * @type: the type name of the property. This namespace is pretty loosely + * defined. Sub namespaces are constructed by using a prefix and then + * to angle brackets. For instance, the type 'virtio-net-pci' in the + * 'link' namespace would be 'link'. + * @get: The getter to be called to read a property. If this is NULL, then + * the property cannot be read. + * @set: the setter to be called to write a property. If this is NULL, + * then the property cannot be written. + * @release: called when the property is removed from the object. This is + * meant to allow a property to free its opaque upon object + * destruction. This may be NULL. + * @opaque: an opaque pointer to pass to the callbacks for the property */ ObjectProperty *object_property_add(Object *obj, const char *name, const char *type, @@ -1476,6 +1501,7 @@ typedef struct ObjectPropertyIterator { =20 /** * object_property_iter_init: + * @iter: the iterator instance * @obj: the object * * Initializes an iterator for traversing all properties @@ -1504,6 +1530,7 @@ void object_property_iter_init(ObjectPropertyIterator= *iter, =20 /** * object_class_property_iter_init: + * @iter: the iterator instance * @klass: the class * * Initializes an iterator for traversing all properties @@ -1551,6 +1578,7 @@ bool object_property_get(Object *obj, const char *nam= e, Visitor *v, =20 /** * object_property_set_str: + * @obj: the object * @name: the name of the property * @value: the value to be written to the property * @errp: returns an error if this function fails @@ -1577,6 +1605,7 @@ char *object_property_get_str(Object *obj, const char= *name, =20 /** * object_property_set_link: + * @obj: the object * @name: the name of the property * @value: the value to be written to the property * @errp: returns an error if this function fails @@ -1607,6 +1636,7 @@ Object *object_property_get_link(Object *obj, const c= har *name, =20 /** * object_property_set_bool: + * @obj: the object * @name: the name of the property * @value: the value to be written to the property * @errp: returns an error if this function fails @@ -1632,6 +1662,7 @@ bool object_property_get_bool(Object *obj, const char= *name, =20 /** * object_property_set_int: + * @obj: the object * @name: the name of the property * @value: the value to be written to the property * @errp: returns an error if this function fails @@ -1657,6 +1688,7 @@ int64_t object_property_get_int(Object *obj, const ch= ar *name, =20 /** * object_property_set_uint: + * @obj: the object * @name: the name of the property * @value: the value to be written to the property * @errp: returns an error if this function fails @@ -1780,6 +1812,7 @@ Object *object_get_internal_root(void); =20 /** * object_get_canonical_path_component: + * @obj: the object * * Returns: The final component in the object's canonical path. The canon= ical * path is the path within the composition tree starting from the root. @@ -1789,6 +1822,7 @@ const char *object_get_canonical_path_component(const= Object *obj); =20 /** * object_get_canonical_path: + * @obj: the object * * Returns: The canonical path for a object, newly allocated. This is * the path within the composition tree starting from the root. Use @@ -1878,6 +1912,10 @@ ObjectProperty *object_property_try_add_child(Object= *obj, const char *name, =20 /** * object_property_add_child: + * @obj: the object to add a property to + * @name: the name of the property + * @child: the child object + * * Same as object_property_try_add_child() with @errp hardcoded to * &error_abort */ @@ -1895,13 +1933,17 @@ typedef enum { =20 /** * object_property_allow_set_link: + * @obj: the object to add a property to + * @name: the name of the property + * @child: the child object + * @errp: pointer to error object * * The default implementation of the object_property_add_link() check() * callback function. It allows the link property to be set and never ret= urns * an error. */ -void object_property_allow_set_link(const Object *, const char *, - Object *, Error **); +void object_property_allow_set_link(const Object *obj, const char *name, + Object *child, Error **errp); =20 /** * object_property_add_link: @@ -1995,6 +2037,7 @@ ObjectProperty *object_class_property_add_bool(Object= Class *klass, * @obj: the object to add a property to * @name: the name of the property * @typename: the name of the enum data type + * @lookup: enum value namelookup table * @get: the getter or %NULL if the property is write-only. * @set: the setter or %NULL if the property is read-only * --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776207; cv=none; d=zohomail.com; s=zohoarc; b=Xcbx8TZ1MzZt1xdpZzBNlkg87d1Uh3z66GatSHwHb0kxVRNiq9qO8I/VTEVXSGV+kLoLOf/Ny0v5oXhyl/tjvZKGXAzZgAgPz0oXEyMpL7LCu4kAACe+bs7oQc8+yG8q3HOTH+cKmRSHxTn6hcpZMptvC8vU5g16qa5Z+Fc/XaQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776207; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Trsx+5dgEASnNuR5fwYeUcB1oxxfhTXSWD+sGULyDps=; b=FvrSqA9MZ6Z1jxdnM2A/gBA+A6h84f07FEZYPEKz62bTBQzfNHdxQsBiRH7wwu+Wb6zIEsIy0abLDegiMe3OVY2Wkpqq8CNCtrKu5Unfz4bGKcmn5GJap3F9ADiQkQQ+sdpatjLhNnlC/QqTpVmZS4LQinmbs+11SoD8HjNETOo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776207255190.31007797046323; Thu, 10 Sep 2020 15:16:47 -0700 (PDT) Received: from localhost ([::1]:41834 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGUs0-0002kO-Tq for importer@patchew.org; Thu, 10 Sep 2020 18:16:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58606) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUqu-0001Pe-43 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:36 -0400 Received: from us-smtp-delivery-1.mimecast.com ([205.139.110.120]:59447 helo=us-smtp-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqs-0002YF-G0 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:35 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-576-IGM-7aSlPgGR6bLcMF2y-Q-1; Thu, 10 Sep 2020 18:15:30 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D55FD1084C92; Thu, 10 Sep 2020 22:15:29 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8F19C7E8F8; Thu, 10 Sep 2020 22:15:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776133; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Trsx+5dgEASnNuR5fwYeUcB1oxxfhTXSWD+sGULyDps=; b=R4h1BbHnGTpETs1LSHpIRCxjupPteTJ7urOh758kShcbojV3ace07HYMsOV0MTYybB54vN c29On1OQClOjv+ZT6SF7kVQTeUW+5sA7xsqOTi3KTYC2hMOXy7JkIP3zRNAekhGQjXegsm mTFai08e0+AlfXJoSVfV1Pt6jIH8F08= X-MC-Unique: IGM-7aSlPgGR6bLcMF2y-Q-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 2/9] qom: Use kernel-doc private/public tags in structs Date: Thu, 10 Sep 2020 18:15:19 -0400 Message-Id: <20200910221526.10041-3-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=205.139.110.120; envelope-from=ehabkost@redhat.com; helo=us-smtp-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:30 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Use kernel-doc syntax for indicating private and public struct fields. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index ad2b91ec6c..f85718380d 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -520,7 +520,7 @@ typedef void (ObjectFree)(void *obj); */ struct ObjectClass { - /*< private >*/ + /* private: */ Type type; GSList *interfaces; =20 @@ -546,7 +546,7 @@ struct ObjectClass */ struct Object { - /*< private >*/ + /* private: */ ObjectClass *class; ObjectFree *free; GHashTable *properties; @@ -905,7 +905,7 @@ struct InterfaceInfo { struct InterfaceClass { ObjectClass parent_class; - /*< private >*/ + /* private: */ ObjectClass *concrete_class; Type interface_type; }; --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776786; cv=none; d=zohomail.com; s=zohoarc; b=A72Dbf0jMTo8JgVLMe4YxkBl5546U/Ya6Fih6XPCVa7aASd9z546VYh3xLdmWYwGOvMoWGE1eG3pT50M/aXOLPpXb23KDUI5Lj+/DcQCENQL6kqBdB7q9jNpQ6kbBChYSu7corcp4q8PV9ImrLdbcAzV/9DmKQymKiy0ce/Gshs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776786; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Tq9FPTvOzwqmtyJO3lm5hMX0keRuf9hRnQp8ycw0bEQ=; b=Vk/cUAn+O8hzJUbQZyOte3MQOE73R6zl3IC6a6hcJXXSS310S3ffgt7mrIYo0CRjqs3ev9hriBWcdjZczIyTr5b28+7XJs5wB+Tz5yH187mFnMVYRwgb0iGaMUoHZVYsSqhaFlByEhDsHQlo7RLoGN7vn969zRFG9FcfntSI6t0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776786617895.263647941273; Thu, 10 Sep 2020 15:26:26 -0700 (PDT) Received: from localhost ([::1]:35940 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGV1N-0003wj-5w for importer@patchew.org; Thu, 10 Sep 2020 18:26:25 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58628) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUqw-0001Tz-AT for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:38 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:25633) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqu-0002YR-QI for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:38 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-537-pqmtxGl-OySjvI7IeIFOtw-1; Thu, 10 Sep 2020 18:15:32 -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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 40E79802B78; Thu, 10 Sep 2020 22:15:31 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id 05BE660BF1; Thu, 10 Sep 2020 22:15:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776136; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Tq9FPTvOzwqmtyJO3lm5hMX0keRuf9hRnQp8ycw0bEQ=; b=jC1dpwf4fy06z+Ji7lMiMf95DS+OYlIaWSRyMR95W39buEX0eBFQBLT8KTBOq/Dx5yrIGj ywk5el10rHgUr5QsMXzxRnoiIFwuGx4cc6FZ6VBBJEOt3hlL5BNmY63Kpiu/zhcaZa0RpX 7Inc9Hs7NzMl93qlckM3HkSlxZMxVKg= X-MC-Unique: pqmtxGl-OySjvI7IeIFOtw-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 3/9] qom: Use ``code`` Sphinx syntax where appropriate Date: Thu, 10 Sep 2020 18:15:20 -0400 Message-Id: <20200910221526.10041-4-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.002 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:36 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Replace gtkdoc markup with Sphinx ``code`` syntax. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index f85718380d..4fb528d841 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -203,8 +203,8 @@ typedef struct InterfaceInfo InterfaceInfo; * an interface instance should always be of incomplete type in order to be * sure it cannot be dereferenced. That is, you should define the * 'typedef struct SomethingIf SomethingIf' so that you can pass around - * 'SomethingIf *si' arguments, but not define a 'struct SomethingIf { ...= }'. - * The only things you can validly do with a 'SomethingIf *' are to pass i= t as + * ``SomethingIf *si`` arguments, but not define a ``struct SomethingIf { = ... }``. + * The only things you can validly do with a ``SomethingIf *`` are to pass= it as * an argument to a method on its corresponding SomethingIfClass, or to * dynamically cast it to an object that implements the interface. * @@ -301,7 +301,7 @@ typedef struct InterfaceInfo InterfaceInfo; * * Alternatively, object_class_by_name() can be used to obtain the class a= nd * its non-overridden methods for a specific type. This would correspond to - * |[ MyClass::method(...) ]| in C++. + * ``MyClass::method(...)`` in C++. * * The first example of such a QOM method was #CPUClass.reset, * another example is #DeviceClass.realize. --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776405; cv=none; d=zohomail.com; s=zohoarc; b=gsyw8NkpHY5KaCJsAAcbqdMegmUnEA5yViIX/9j3+loYpo1YyQt9SbFpJFfUYn84pi/s46YEflncAbFh7Zv6XSaPperTIqNyl15kcxAvKLbQMeJNBuam6q0n/MqUhc4P9GReDGHsXHx4B+fsbiKzDHnMSaqNuX7+ANOvBEkyKHc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776405; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=4b6Sl8gKu7Y6j7Vbe64mIkWlAGphqX+tesIHdB1ai9M=; b=OLqzrwQGzZ8VUsRXU2WRo8yhgegPyzqNEi8aUBrv4XtNFARIPTnd4haxKQwyt5zsawXYSRtB+qWn5wwYNDVG6nI0PsyNUD243bfLJV/p1H1nE6+vYF/cHqttfR6pTlMWjtUKnhNmVScyEUSxz5gSRoNUNOnAdU+AYNg+beDm/e0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776405687775.6630696809003; Thu, 10 Sep 2020 15:20:05 -0700 (PDT) Received: from localhost ([::1]:53728 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGUvE-0007iJ-Ad for importer@patchew.org; Thu, 10 Sep 2020 18:20:04 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58640) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUqx-0001Vn-44 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:39 -0400 Received: from us-smtp-2.mimecast.com ([207.211.31.81]:38411 helo=us-smtp-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqv-0002YV-GD for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:38 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-15-pCzOknzwOZ2vEwD5EK8D5A-1; Thu, 10 Sep 2020 18:15:34 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3C663802B78; Thu, 10 Sep 2020 22:15:33 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id 058D67512C; Thu, 10 Sep 2020 22:15:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776136; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=4b6Sl8gKu7Y6j7Vbe64mIkWlAGphqX+tesIHdB1ai9M=; b=Cnc8eE1bkNo1X8JyU4iCrm63U/xs3wOB401D5Zmd3338Gooc174jjS+hzJYF1RPLjN+KoJ A9gn/gLtpTpibUt//OtLkwyml/ojOel25ywk2PkdcPf6w6pJCWnlEQ0fPqSru7X6SlZ3ju OZEZNEdQJh9tWvLAg6dT3eC6CmulJ/E= X-MC-Unique: pCzOknzwOZ2vEwD5EK8D5A-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 4/9] qom: Add kernel-doc markup to introduction doc comment Date: Thu, 10 Sep 2020 18:15:21 -0400 Message-Id: <20200910221526.10041-5-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=207.211.31.81; envelope-from=ehabkost@redhat.com; helo=us-smtp-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:36 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Add DOC: section keyword to introduction doc comment, so it will be rendered by kernel-doc. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index 4fb528d841..d2eecdf872 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -29,9 +29,7 @@ typedef struct InterfaceInfo InterfaceInfo; #define TYPE_OBJECT "object" =20 /** - * SECTION:object.h - * @title:Base Object Type System - * @short_description: interfaces for creating new types and objects + * DOC: * * The QEMU Object Model provides a framework for registering user creatab= le * types and instantiating objects from those types. QOM provides the fol= lowing --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776209; cv=none; d=zohomail.com; s=zohoarc; b=Uikkn7jT/SghO+ykyF4u+1gdfU1fFuaVqGci7nY4DdK3H1/8LmXRJKlfJsj8HNrciGvIpTtkfXIpc9aPekBRHxXPxAulgFGeM9yh66L0aVnaWa5kMC4H26jVIOa1DXQpnN3dG2Z4UDdQjGDBa1Q7n5L+jFCwy3pxcf3qbv0Qw38= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776209; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qXS3/olQEWE6olehVY6G/wq941xe6izMFWQeRubt6Cg=; b=iX54E1zCCC5XhWvMHNNMEQq/AYnKu51jL63JC1dWpJksLWTbBhhwJWZlxXu3RD5Cv5OoqoSAO61CS7DF4fV04jP9Ip6SndQl0N7dTjFI9XSmpPejuZxUyIKp2x6VHv7ho3B/J1T6ZCZ15He/j/DC6f9f5LGL3MAf5b/1ATxQ+y4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776209495827.9567708001663; Thu, 10 Sep 2020 15:16:49 -0700 (PDT) Received: from localhost ([::1]:42158 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGUs4-0002sN-0W for importer@patchew.org; Thu, 10 Sep 2020 18:16:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58642) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUqx-0001XD-P5 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:39 -0400 Received: from us-smtp-1.mimecast.com ([205.139.110.61]:22371 helo=us-smtp-delivery-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqw-0002Yc-3d for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:39 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-156-Tchw8kHqORabR0tVmEbyZg-1; Thu, 10 Sep 2020 18:15:35 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4348D1084C83; Thu, 10 Sep 2020 22:15:34 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0C13675121; Thu, 10 Sep 2020 22:15:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776137; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=qXS3/olQEWE6olehVY6G/wq941xe6izMFWQeRubt6Cg=; b=eQNVB1E4IzFPdlO6j4VVu6YK7u0TwrKvTyhqMytcu2CBD8/K6wJ3ufxR043mcc6Da1uMSO y7N681BZ7sJr4WBnlOKBiqOeWYaprZnxZCz0u1d1sMCanPEHlVu2AUccFfZaZS03+FHV1w OEtjFW4hej2xtiW95k5qBeF4yTS75Io= X-MC-Unique: Tchw8kHqORabR0tVmEbyZg-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 5/9] qom: Reformat section titles using Sphinx syntax Date: Thu, 10 Sep 2020 18:15:22 -0400 Message-Id: <20200910221526.10041-6-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=205.139.110.61; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:37 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Signed-off-by: Eduardo Habkost --- include/qom/object.h | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index d2eecdf872..da9ecb310f 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -120,7 +120,8 @@ typedef struct InterfaceInfo InterfaceInfo; * * * - * # Class Initialization # + * Class Initialization + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D * * Before an object is initialized, the class for the object must be * initialized. There is only one class object for all instance objects @@ -193,7 +194,8 @@ typedef struct InterfaceInfo InterfaceInfo; * * * - * # Interfaces # + * Interfaces + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D * * Interfaces allow a limited form of multiple inheritance. Instances are * similar to normal types except for the fact that are only defined by @@ -206,7 +208,8 @@ typedef struct InterfaceInfo InterfaceInfo; * an argument to a method on its corresponding SomethingIfClass, or to * dynamically cast it to an object that implements the interface. * - * # Methods # + * Methods + * =3D=3D=3D=3D=3D=3D=3D * * A method is a function within the namespace scope = of * a class. It usually operates on the object instance by passing it as a @@ -304,7 +307,8 @@ typedef struct InterfaceInfo InterfaceInfo; * The first example of such a QOM method was #CPUClass.reset, * another example is #DeviceClass.realize. * - * # Standard type declaration and definition macros # + * Standard type declaration and definition macros + * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D * * A lot of the code outlined above follows a standard pattern and naming * convention. To reduce the amount of boilerplate code that needs to be --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776482; cv=none; d=zohomail.com; s=zohoarc; b=UTC406xp2YLhYnXsQODRwrFbRrmt/uIP1DQDs8WtARUiDfmJ3PHvhV2Yt0o27fnZEkbf1NSSccv4b4y9+foW8f/7RsY1pjM5Hv8xCike+FiwpeA9N3gTvn7AqYBFixFpDCCEh3ZxrfNJd1Ey4X5D6FXZV9XfFHr0/Jifl1y1KoU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776482; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=JAOZ1frciEpUdXRUZJbDOCmWberBqBZnqPDiNgyYKkw=; b=BkmAMgpVeGLfhu8SVgnq/OlD54acg0lZ6AmGUp4b/ZtwrEMSrHGJo6e0+s6u/LnNTEP/B4OBamq9WzyM1MURhub/6u6267BGJPNsIjmaqlsc0Xe628OaOxYvCogltSVSON+PJQ0mriMhGD78EzxDDWdErCxKq/tjch2O2+MXmvc= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776482284619.9751428531304; Thu, 10 Sep 2020 15:21:22 -0700 (PDT) Received: from localhost ([::1]:58066 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGUwS-0001AK-TL for importer@patchew.org; Thu, 10 Sep 2020 18:21:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58676) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUr0-0001eG-Uf for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:42 -0400 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:48293) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqy-0002Yz-KF for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:42 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-200-0pGeX8ITNsyzQlaQLu5zVA-1; Thu, 10 Sep 2020 18:15:36 -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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 47849802B79; Thu, 10 Sep 2020 22:15:35 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id EFE9960BF1; Thu, 10 Sep 2020 22:15:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776139; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JAOZ1frciEpUdXRUZJbDOCmWberBqBZnqPDiNgyYKkw=; b=iyudjlyTtIr+rYcngsPasthywU/QbVikBWxvjFZ9SdsPix8yew5D4DOlaaQCaPmOHU8DO1 L5oHOqltmxyl8d4KM+f474cXRlgBQrUVzRszR+3O1Sq5K6ZqspOBjwGQXoK1ySXgFIp9+F TNgMpTBtM3tPl0t+KyQwUiBdZ6sYFBk= X-MC-Unique: 0pGeX8ITNsyzQlaQLu5zVA-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 6/9] qom: Indent existing code examples Date: Thu, 10 Sep 2020 18:15:23 -0400 Message-Id: <20200910221526.10041-7-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.001 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=63.128.21.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:31 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" This indents existing code examples that are not indented yet, just to make future conversion to Sphinx markup easier to review. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 376 +++++++++++++++++++++---------------------- 1 file changed, 188 insertions(+), 188 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index da9ecb310f..5d22ec95b2 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -41,34 +41,34 @@ typedef struct InterfaceInfo InterfaceInfo; * * * Creating a minimal type - * - * #include "qdev.h" - * - * #define TYPE_MY_DEVICE "my-device" - * - * // No new virtual functions: we can reuse the typedef for the - * // superclass. - * typedef DeviceClass MyDeviceClass; - * typedef struct MyDevice - * { - * DeviceState parent; - * - * int reg0, reg1, reg2; - * } MyDevice; - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * }; - * - * static void my_device_register_types(void) - * { - * type_register_static(&my_device_info); - * } - * - * type_init(my_device_register_types) - * + * + * #include "qdev.h" + * + * #define TYPE_MY_DEVICE "my-device" + * + * // No new virtual functions: we can reuse the typedef for the + * // superclass. + * typedef DeviceClass MyDeviceClass; + * typedef struct MyDevice + * { + * DeviceState parent; + * + * int reg0, reg1, reg2; + * } MyDevice; + * + * static const TypeInfo my_device_info =3D { + * .name =3D TYPE_MY_DEVICE, + * .parent =3D TYPE_DEVICE, + * .instance_size =3D sizeof(MyDevice), + * }; + * + * static void my_device_register_types(void) + * { + * type_register_static(&my_device_info); + * } + * + * type_init(my_device_register_types) + * * * * In the above example, we create a simple type that is described by #Typ= eInfo. @@ -79,22 +79,22 @@ typedef struct InterfaceInfo InterfaceInfo; * DEFINE_TYPES() * * - * - * static const TypeInfo device_types_info[] =3D { - * { - * .name =3D TYPE_MY_DEVICE_A, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDeviceA), - * }, - * { - * .name =3D TYPE_MY_DEVICE_B, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDeviceB), - * }, - * }; - * - * DEFINE_TYPES(device_types_info) - * + * + * static const TypeInfo device_types_info[] =3D { + * { + * .name =3D TYPE_MY_DEVICE_A, + * .parent =3D TYPE_DEVICE, + * .instance_size =3D sizeof(MyDeviceA), + * }, + * { + * .name =3D TYPE_MY_DEVICE_B, + * .parent =3D TYPE_DEVICE, + * .instance_size =3D sizeof(MyDeviceB), + * }, + * }; + * + * DEFINE_TYPES(device_types_info) + * * * * Every type has an #ObjectClass associated with it. #ObjectClass deriva= tives @@ -143,22 +143,22 @@ typedef struct InterfaceInfo InterfaceInfo; * * * Overriding a virtual function - * - * #include "qdev.h" - * - * void my_device_class_init(ObjectClass *klass, void *class_data) - * { - * DeviceClass *dc =3D DEVICE_CLASS(klass); - * dc->reset =3D my_device_reset; - * } - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * .class_init =3D my_device_class_init, - * }; - * + * + * #include "qdev.h" + * + * void my_device_class_init(ObjectClass *klass, void *class_data) + * { + * DeviceClass *dc =3D DEVICE_CLASS(klass); + * dc->reset =3D my_device_reset; + * } + * + * static const TypeInfo my_device_info =3D { + * .name =3D TYPE_MY_DEVICE, + * .parent =3D TYPE_DEVICE, + * .instance_size =3D sizeof(MyDevice), + * .class_init =3D my_device_class_init, + * }; + * * * * Introducing new virtual methods requires a class to define its own @@ -167,31 +167,31 @@ typedef struct InterfaceInfo InterfaceInfo; * * * Defining an abstract class - * - * #include "qdev.h" - * - * typedef struct MyDeviceClass - * { - * DeviceClass parent; - * - * void (*frobnicate) (MyDevice *obj); - * } MyDeviceClass; - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * .abstract =3D true, // or set a default in my_device_class_init - * .class_size =3D sizeof(MyDeviceClass), - * }; - * - * void my_device_frobnicate(MyDevice *obj) - * { - * MyDeviceClass *klass =3D MY_DEVICE_GET_CLASS(obj); - * - * klass->frobnicate(obj); - * } - * + * + * #include "qdev.h" + * + * typedef struct MyDeviceClass + * { + * DeviceClass parent; + * + * void (*frobnicate) (MyDevice *obj); + * } MyDeviceClass; + * + * static const TypeInfo my_device_info =3D { + * .name =3D TYPE_MY_DEVICE, + * .parent =3D TYPE_DEVICE, + * .instance_size =3D sizeof(MyDevice), + * .abstract =3D true, // or set a default in my_device_class_init + * .class_size =3D sizeof(MyDeviceClass), + * }; + * + * void my_device_frobnicate(MyDevice *obj) + * { + * MyDeviceClass *klass =3D MY_DEVICE_GET_CLASS(obj); + * + * klass->frobnicate(obj); + * } + * * * * Interfaces @@ -236,68 +236,68 @@ typedef struct InterfaceInfo InterfaceInfo; * * * Overriding a virtual method - * - * typedef struct MyState MyState; - * - * typedef void (*MyDoSomething)(MyState *obj); - * - * typedef struct MyClass { - * ObjectClass parent_class; - * - * MyDoSomething do_something; - * } MyClass; - * - * static void my_do_something(MyState *obj) - * { - * // do something - * } - * - * static void my_class_init(ObjectClass *oc, void *data) - * { - * MyClass *mc =3D MY_CLASS(oc); - * - * mc->do_something =3D my_do_something; - * } - * - * static const TypeInfo my_type_info =3D { - * .name =3D TYPE_MY, - * .parent =3D TYPE_OBJECT, - * .instance_size =3D sizeof(MyState), - * .class_size =3D sizeof(MyClass), - * .class_init =3D my_class_init, - * }; - * - * typedef struct DerivedClass { - * MyClass parent_class; - * - * MyDoSomething parent_do_something; - * } DerivedClass; - * - * static void derived_do_something(MyState *obj) - * { - * DerivedClass *dc =3D DERIVED_GET_CLASS(obj); - * - * // do something here - * dc->parent_do_something(obj); - * // do something else here - * } - * - * static void derived_class_init(ObjectClass *oc, void *data) - * { - * MyClass *mc =3D MY_CLASS(oc); - * DerivedClass *dc =3D DERIVED_CLASS(oc); - * - * dc->parent_do_something =3D mc->do_something; - * mc->do_something =3D derived_do_something; - * } - * - * static const TypeInfo derived_type_info =3D { - * .name =3D TYPE_DERIVED, - * .parent =3D TYPE_MY, - * .class_size =3D sizeof(DerivedClass), - * .class_init =3D derived_class_init, - * }; - * + * + * typedef struct MyState MyState; + * + * typedef void (*MyDoSomething)(MyState *obj); + * + * typedef struct MyClass { + * ObjectClass parent_class; + * + * MyDoSomething do_something; + * } MyClass; + * + * static void my_do_something(MyState *obj) + * { + * // do something + * } + * + * static void my_class_init(ObjectClass *oc, void *data) + * { + * MyClass *mc =3D MY_CLASS(oc); + * + * mc->do_something =3D my_do_something; + * } + * + * static const TypeInfo my_type_info =3D { + * .name =3D TYPE_MY, + * .parent =3D TYPE_OBJECT, + * .instance_size =3D sizeof(MyState), + * .class_size =3D sizeof(MyClass), + * .class_init =3D my_class_init, + * }; + * + * typedef struct DerivedClass { + * MyClass parent_class; + * + * MyDoSomething parent_do_something; + * } DerivedClass; + * + * static void derived_do_something(MyState *obj) + * { + * DerivedClass *dc =3D DERIVED_GET_CLASS(obj); + * + * // do something here + * dc->parent_do_something(obj); + * // do something else here + * } + * + * static void derived_class_init(ObjectClass *oc, void *data) + * { + * MyClass *mc =3D MY_CLASS(oc); + * DerivedClass *dc =3D DERIVED_CLASS(oc); + * + * dc->parent_do_something =3D mc->do_something; + * mc->do_something =3D derived_do_something; + * } + * + * static const TypeInfo derived_type_info =3D { + * .name =3D TYPE_DERIVED, + * .parent =3D TYPE_MY, + * .class_size =3D sizeof(DerivedClass), + * .class_init =3D derived_class_init, + * }; + * * * * Alternatively, object_class_by_name() can be used to obtain the class a= nd @@ -981,24 +981,24 @@ Object *object_new(const char *typename); * * * Creating an object with properties - * - * Error *err =3D NULL; - * Object *obj; - * - * obj =3D object_new_with_props(TYPE_MEMORY_BACKEND_FILE, - * object_get_objects_root(), - * "hostmem0", - * &err, - * "share", "yes", - * "mem-path", "/dev/shm/somefile", - * "prealloc", "yes", - * "size", "1048576", - * NULL); - * - * if (!obj) { - * error_reportf_err(err, "Cannot create memory backend: "); - * } - * + * + * Error *err =3D NULL; + * Object *obj; + * + * obj =3D object_new_with_props(TYPE_MEMORY_BACKEND_FILE, + * object_get_objects_root(), + * "hostmem0", + * &err, + * "share", "yes", + * "mem-path", "/dev/shm/somefile", + * "prealloc", "yes", + * "size", "1048576", + * NULL); + * + * if (!obj) { + * error_reportf_err(err, "Cannot create memory backend: "); + * } + * * * * The returned object will have one stable reference maintained @@ -1050,20 +1050,20 @@ void object_apply_compat_props(Object *obj); * * * Update an object's properties - * - * Error *err =3D NULL; - * Object *obj =3D ...get / create object...; - * - * if (!object_set_props(obj, - * &err, - * "share", "yes", - * "mem-path", "/dev/shm/somefile", - * "prealloc", "yes", - * "size", "1048576", - * NULL)) { - * error_reportf_err(err, "Cannot set properties: "); - * } - * + * + * Error *err =3D NULL; + * Object *obj =3D ...get / create object...; + * + * if (!object_set_props(obj, + * &err, + * "share", "yes", + * "mem-path", "/dev/shm/somefile", + * "prealloc", "yes", + * "size", "1048576", + * NULL)) { + * error_reportf_err(err, "Cannot set properties: "); + * } + * * * * The returned object will have one stable reference maintained @@ -1516,15 +1516,15 @@ typedef struct ObjectPropertyIterator { * * * Using object property iterators - * - * ObjectProperty *prop; - * ObjectPropertyIterator iter; - * - * object_property_iter_init(&iter, obj); - * while ((prop =3D object_property_iter_next(&iter))) { - * ... do something with prop ... - * } - * + * + * ObjectProperty *prop; + * ObjectPropertyIterator iter; + * + * object_property_iter_init(&iter, obj); + * while ((prop =3D object_property_iter_next(&iter))) { + * ... do something with prop ... + * } + * * */ void object_property_iter_init(ObjectPropertyIterator *iter, --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776836; cv=none; d=zohomail.com; s=zohoarc; b=FiOLkcIikQ0PQttUf+R89PdGOPEaYdOv+JPJkfwu17IGUzD4tmJAwzgCv8lq6qdM4YuuPdrPw9v89mcpU3/zBYnXZfE80GW2HQU1tCZXFg1vBm+HmjWRWbI025OwaycxckaqTuOPF3SmJs/Zj6zgNzMsZlk1f7iDVyusPQJKFZs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776836; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=FrTuC4pCOjSVubxkREqLU1XmJmDqUMdSxDfM4YAiRVE=; b=nIjAvgg/xykS7JaG40aQ0yg45OvrsbKYvdzd/pPOIekK16sSF2pM5GTxLhGjRAFzdsqWyZ6fE2EoBkn0rALkinF1S5p6P2XDVgeR5pchYb/8E3TLr0AgjMfV7Il35u8lk1Eq1DnbG0smzBeicKrzgzWZSjGOOp+xv/D+UpxgJHs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776836401105.2917353961102; Thu, 10 Sep 2020 15:27:16 -0700 (PDT) Received: from localhost ([::1]:37980 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGV2A-0004n4-UC for importer@patchew.org; Thu, 10 Sep 2020 18:27:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58670) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUr0-0001df-Lb for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:42 -0400 Received: from us-smtp-delivery-1.mimecast.com ([205.139.110.120]:43209 helo=us-smtp-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqy-0002Ys-7r for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:42 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-272-7y-AJYIRNE2DSJ3yPriJWQ-1; Thu, 10 Sep 2020 18:15:37 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 38C24100746B; Thu, 10 Sep 2020 22:15:36 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id E79647E8F9; Thu, 10 Sep 2020 22:15:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776139; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=FrTuC4pCOjSVubxkREqLU1XmJmDqUMdSxDfM4YAiRVE=; b=NuXTpjjMZkeRKmdDNGnpHEJ2/SuYYDz2b7qoFI+a6uGxX/gzOO2vM4oVUDBFi9xE44Mmt5 FHjJ2/+pWIRxYwNaRjIaE4JNS5+qXdrOfETjMYZSkLD3qVnctqw8WPY4O049BNZuJu8+OJ ivWBsjNvnWwB8DzMjTlSU5g4cy13pDc= X-MC-Unique: 7y-AJYIRNE2DSJ3yPriJWQ-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 7/9] qom: Add code block markup to all code blocks Date: Thu, 10 Sep 2020 18:15:24 -0400 Message-Id: <20200910221526.10041-8-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.001 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=205.139.110.120; envelope-from=ehabkost@redhat.com; helo=us-smtp-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:30 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Convert all example/codelisting markup to Sphinx code-block. There are a few sections where backslashes at the end of lines break code formatting. A comment was added noting that this is an issue. Signed-off-by: Eduardo Habkost --- include/qom/object.h | 135 ++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 79 deletions(-) diff --git a/include/qom/object.h b/include/qom/object.h index 5d22ec95b2..75ef97da31 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -31,6 +31,8 @@ typedef struct InterfaceInfo InterfaceInfo; /** * DOC: * + * .. highlight:: c + * * The QEMU Object Model provides a framework for registering user creatab= le * types and instantiating objects from those types. QOM provides the fol= lowing * features: @@ -39,9 +41,9 @@ typedef struct InterfaceInfo InterfaceInfo; * - Support for single-inheritance of types * - Multiple inheritance of stateless interfaces * - * - * Creating a minimal type - * + * .. code-block:: + * :caption: Creating a minimal type + * * #include "qdev.h" * * #define TYPE_MY_DEVICE "my-device" @@ -68,8 +70,6 @@ typedef struct InterfaceInfo InterfaceInfo; * } * * type_init(my_device_register_types) - * - * * * In the above example, we create a simple type that is described by #Typ= eInfo. * #TypeInfo describes information about the type including what it inheri= ts @@ -78,8 +78,8 @@ typedef struct InterfaceInfo InterfaceInfo; * Alternatively several static types could be registered using helper mac= ro * DEFINE_TYPES() * - * - * + * .. code-block:: + * * static const TypeInfo device_types_info[] =3D { * { * .name =3D TYPE_MY_DEVICE_A, @@ -94,8 +94,6 @@ typedef struct InterfaceInfo InterfaceInfo; * }; * * DEFINE_TYPES(device_types_info) - * - * * * Every type has an #ObjectClass associated with it. #ObjectClass deriva= tives * are instantiated dynamically but there is only ever one instance for any @@ -108,17 +106,19 @@ typedef struct InterfaceInfo InterfaceInfo; * OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to= a * specific type: * - * - * Typecasting macros - * + * .. kernel-doc messes up with the code block below because of the + * backslash at the end of lines. This will be fixes if we move this + * content to qom.rst. + * + * .. code-block:: + * :caption: Typecasting macros + * * #define MY_DEVICE_GET_CLASS(obj) \ * OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) * #define MY_DEVICE_CLASS(klass) \ * OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) * #define MY_DEVICE(obj) \ * OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) - * - * * * Class Initialization * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -141,9 +141,9 @@ typedef struct InterfaceInfo InterfaceInfo; * its virtual functions. Here is how the above example might be modified * to introduce an overridden virtual function: * - * - * Overriding a virtual function - * + * .. code-block:: + * :caption: Overriding a virtual function + * * #include "qdev.h" * * void my_device_class_init(ObjectClass *klass, void *class_data) @@ -158,16 +158,14 @@ typedef struct InterfaceInfo InterfaceInfo; * .instance_size =3D sizeof(MyDevice), * .class_init =3D my_device_class_init, * }; - * - * * * Introducing new virtual methods requires a class to define its own * struct and to add a .class_size member to the #TypeInfo. Each method * will also have a wrapper function to call it easily: * - * - * Defining an abstract class - * + * .. code-block:: + * :caption: Defining an abstract class + * * #include "qdev.h" * * typedef struct MyDeviceClass @@ -191,8 +189,6 @@ typedef struct InterfaceInfo InterfaceInfo; * * klass->frobnicate(obj); * } - * - * * * Interfaces * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -230,13 +226,13 @@ typedef struct InterfaceInfo InterfaceInfo; * * To invoke the method being overridden, the preferred solution is to sto= re * the original value in the overriding class before overriding the method. - * This corresponds to |[ {super,base}.method(...) ]| in Java and C# + * This corresponds to ``{super,base}.method(...)`` in Java and C# * respectively; this frees the overriding class from hardcoding its parent * class, which someone might choose to change at some point. * - * - * Overriding a virtual method - * + * .. code-block:: + * :caption: Overriding a virtual method + * * typedef struct MyState MyState; * * typedef void (*MyDoSomething)(MyState *obj); @@ -297,8 +293,6 @@ typedef struct InterfaceInfo InterfaceInfo; * .class_size =3D sizeof(DerivedClass), * .class_init =3D derived_class_init, * }; - * - * * * Alternatively, object_class_by_name() can be used to obtain the class a= nd * its non-overridden methods for a specific type. This would correspond to @@ -320,18 +314,16 @@ typedef struct InterfaceInfo InterfaceInfo; * OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed * in the header file: * - * - * Declaring a simple type - * + * .. code-block:: + * :caption: Declaring a simple type + * * OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - * - * * * This is equivalent to the following: * - * - * Expansion from declaring a simple type - * + * .. code-block:: + * :caption: Expansion from declaring a simple type + * * typedef struct MyDevice MyDevice; * typedef struct MyDeviceClass MyDeviceClass; * @@ -347,8 +339,6 @@ typedef struct InterfaceInfo InterfaceInfo; * struct MyDeviceClass { * DeviceClass parent_class; * }; - * - * * * The 'struct MyDevice' needs to be declared separately. * If the type requires virtual functions to be declared in the class @@ -359,18 +349,16 @@ typedef struct InterfaceInfo InterfaceInfo; * To implement the type, the OBJECT_DEFINE macro family is available. * In the simple case the OBJECT_DEFINE_TYPE macro is suitable: * - * - * Defining a simple type - * + * .. code-block:: + * :caption: Defining a simple type + * * OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - * - * * * This is equivalent to the following: * - * - * Expansion from defining a simple type - * + * .. code-block:: + * :caption: Expansion from defining a simple type + * * static void my_device_finalize(Object *obj); * static void my_device_class_init(ObjectClass *oc, void *data); * static void my_device_init(Object *obj); @@ -391,8 +379,6 @@ typedef struct InterfaceInfo InterfaceInfo; * type_register_static(&my_device_info); * } * type_init(my_device_register_types); - * - * * * This is sufficient to get the type registered with the type * system, and the three standard methods now need to be implemented @@ -402,24 +388,20 @@ typedef struct InterfaceInfo InterfaceInfo; * OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead. * This accepts an array of interface type names. * - * - * Defining a simple type implementing interfaces - * + * .. code-block:: + * :caption: Defining a simple type implementing interfaces + * * OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device, * MY_DEVICE, DEVICE, * { TYPE_USER_CREATABLE }, { NULL = }) - * - * * * If the type is not intended to be instantiated, then then * the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: * - * - * Defining a simple type - * + * .. code-block:: + * :caption: Defining a simple abstract type + * * OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - * - * */ =20 =20 @@ -979,9 +961,9 @@ Object *object_new(const char *typename); * object will be marked complete once all the properties have been * processed. * - * - * Creating an object with properties - * + * .. code-block:: + * :caption: Creating an object with properties + * * Error *err =3D NULL; * Object *obj; * @@ -998,8 +980,6 @@ Object *object_new(const char *typename); * if (!obj) { * error_reportf_err(err, "Cannot create memory backend: "); * } - * - * * * The returned object will have one stable reference maintained * for as long as it is present in the object hierarchy. @@ -1048,9 +1028,9 @@ void object_apply_compat_props(Object *obj); * strings. The propname of %NULL indicates the end of the property * list. * - * - * Update an object's properties - * + * .. code-block:: + * :caption: Update an object's properties + * * Error *err =3D NULL; * Object *obj =3D ...get / create object...; * @@ -1063,8 +1043,6 @@ void object_apply_compat_props(Object *obj); * NULL)) { * error_reportf_err(err, "Cannot set properties: "); * } - * - * * * The returned object will have one stable reference maintained * for as long as it is present in the object hierarchy. @@ -1152,10 +1130,11 @@ bool object_initialize_child_with_propsv(Object *pa= rentobj, * object. * @type: The name of the type of the object to instantiate. * - * This is like - * object_initialize_child_with_props(parent, propname, - * child, sizeof(*child), type, - * &error_abort, NULL) + * This is like:: + * + * object_initialize_child_with_props(parent, propname, + * child, sizeof(*child), type, + * &error_abort, NULL) */ #define object_initialize_child(parent, propname, child, type) \ object_initialize_child_internal((parent), (propname), \ @@ -1514,9 +1493,9 @@ typedef struct ObjectPropertyIterator { * * Typical usage pattern would be * - * - * Using object property iterators - * + * .. code-block:: c + * :caption: Using object property iterators + * * ObjectProperty *prop; * ObjectPropertyIterator iter; * @@ -1524,8 +1503,6 @@ typedef struct ObjectPropertyIterator { * while ((prop =3D object_property_iter_next(&iter))) { * ... do something with prop ... * } - * - * */ void object_property_iter_init(ObjectPropertyIterator *iter, Object *obj); --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776897; cv=none; d=zohomail.com; s=zohoarc; b=JjBSQPWDv/ERBvpgTOPZy0Nx1SlAASZ63CsWcnxhz2mP60bF7DPQ69yNrTymCnzA7Lzi0SvyFOAMW/O3aaPIU2yRfJ8s5ax7LYahKT9TkgTtas6hral9lcEol4ebFmohQC4JJeaK+ichl1Gqp2qdLTQNaS1Blr6njUKU0URdVEI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776897; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=fmwDN3Od7TIxOLT6rZuXjwWjKq2mx8rElfFpX37Okgk=; b=kwiO7XjqU7XdnoPD/TDKxeI/juykMH2ixCjV5x1MrhL0sI7hig5vtx87ynQQewipwU064vGtUIMFeuSmbM/WCLDVMQD8hcXFB9hUXeVRm4LIuwxZyXEmX2Cw5tHjpcfngZalYQZVonh90bt7JHaivAn1+gIT0RRPEGAAyeDmoLo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776897104745.1486983003005; Thu, 10 Sep 2020 15:28:17 -0700 (PDT) Received: from localhost ([::1]:40020 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGV39-0005ef-JZ for importer@patchew.org; Thu, 10 Sep 2020 18:28:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58692) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUr1-0001gW-TI for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:43 -0400 Received: from us-smtp-delivery-1.mimecast.com ([207.211.31.120]:45539 helo=us-smtp-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUqz-0002Z4-CD for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:43 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-175-GF7Zy9JjM9qtxco2jKCBEQ-1; Thu, 10 Sep 2020 18:15:38 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4275D1084C85; Thu, 10 Sep 2020 22:15:37 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0D67C75121; Thu, 10 Sep 2020 22:15:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776140; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=fmwDN3Od7TIxOLT6rZuXjwWjKq2mx8rElfFpX37Okgk=; b=Cx5c8LPjS116GVSiSCdw+p1+Y+GYYV0CsKg3310QVIppgbXDpsTSIk7/aBFDUJCmvuvcOV gTNoBGzXfIw+UqH2wpvuszlo9B2a5y8Wv+HANtu9QBlQxrjA+559LJR+iI13HOj4eS3qNZ bzzoC6a/e1KSkHcibw/TVf8dSeaG80Y= X-MC-Unique: GF7Zy9JjM9qtxco2jKCBEQ-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 8/9] docs: Create docs/devel/qom.rst Date: Thu, 10 Sep 2020 18:15:25 -0400 Message-Id: <20200910221526.10041-9-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=207.211.31.120; envelope-from=ehabkost@redhat.com; helo=us-smtp-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:40 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Signed-off-by: Eduardo Habkost --- docs/devel/index.rst | 1 + docs/devel/qom.rst | 5 +++++ 2 files changed, 6 insertions(+) create mode 100644 docs/devel/qom.rst diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 04773ce076..c34b43ec28 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -31,3 +31,4 @@ Contents: reset s390-dasd-ipl clocks + qom diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst new file mode 100644 index 0000000000..dc5be79a4a --- /dev/null +++ b/docs/devel/qom.rst @@ -0,0 +1,5 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D +The QEMU Object Model (QOM) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D + +.. kernel-doc:: include/qom/object.h --=20 2.26.2 From nobody Sun May 5 19:46:28 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1599776956; cv=none; d=zohomail.com; s=zohoarc; b=eoMS5ILxFCofFm8H+ozzXzz5b8AYvql1b5xLP4Rp/hkotYufLNbM9HxdGqUiSKEbn4+/zfIz6vdCdlKgcNUfisnx2YIetZdEVd3rTQlR+MA1Lqn83FcchzTQJc9qE5GI0ZY2DfwZ9osoq2ff8vESY0KMgcFk5yUfpZyRCRZtGP8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1599776956; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=tG/pW3vTJTnW+q+g1akUTFpCvWQ55Kt6koedwJ/Vv1E=; b=k9kmm6B+xsP8GYVlpk1H5mBhFGwXWWW3/n92vXNOJHq9bd9lZ5wnUNdL/8VF+ZU7OcpoH8NBLykLlGuftUoip5Hu+oRbV8mBUmA5L5wXDugj0dIEGn/scfJFeqIV2c4JkA2WNEdV4Hq5/OFRZGCJRnqEwcq5eFgUplv1Q+zRFo8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1599776956288828.7422647218633; Thu, 10 Sep 2020 15:29:16 -0700 (PDT) Received: from localhost ([::1]:42048 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kGV46-0006W9-TU for importer@patchew.org; Thu, 10 Sep 2020 18:29:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58704) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kGUr3-0001jt-MR for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:45 -0400 Received: from us-smtp-1.mimecast.com ([205.139.110.61]:54325 helo=us-smtp-delivery-1.mimecast.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kGUr0-0002ZE-94 for qemu-devel@nongnu.org; Thu, 10 Sep 2020 18:15:45 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-424-rS97hnP7O7KWnrCsTh1emA-1; Thu, 10 Sep 2020 18:15: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 mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8C345802B78; Thu, 10 Sep 2020 22:15:38 +0000 (UTC) Received: from localhost (ovpn-66-226.rdu2.redhat.com [10.10.66.226]) by smtp.corp.redhat.com (Postfix) with ESMTP id F26E51002D57; Thu, 10 Sep 2020 22:15:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1599776141; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=tG/pW3vTJTnW+q+g1akUTFpCvWQ55Kt6koedwJ/Vv1E=; b=KUUFLOdE/uthW7TcsR3/+LC/0zCaLOiEYahNV+T+nsYAE14Aj+rMLf+AcxVoM5QBJZZO9W SxPrGoXCARud7s0jWmRxKPnGuW+ABtKARfkwbMGmfbJk/HAdJ66TGfcJfc8m3nZjzoqGqW +FaeoU+glBy635vVoykXJ3oYXNtrB/E= X-MC-Unique: rS97hnP7O7KWnrCsTh1emA-1 From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH 9/9] docs: Move object.h overview doc comment to qom.rst Date: Thu, 10 Sep 2020 18:15:26 -0400 Message-Id: <20200910221526.10041-10-ehabkost@redhat.com> In-Reply-To: <20200910221526.10041-1-ehabkost@redhat.com> References: <20200910221526.10041-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0.003 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=205.139.110.61; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-1.mimecast.com X-detected-operating-system: by eggs.gnu.org: First seen = 2020/09/10 18:15:37 X-ACL-Warn: Detected OS = Linux 2.2.x-3.x [generic] [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eduardo Habkost , Peter Maydell Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Move the whole contents of the overview doc comment from object.h to qom.rst. This makes the documentation source easier to read and edit, and also solves the backslash escaping issue at the typecasting macro examples. Signed-off-by: Eduardo Habkost --- docs/devel/qom.rst | 373 ++++++++++++++++++++++++++++++++++++++++++ include/qom/object.h | 377 ------------------------------------------- 2 files changed, 373 insertions(+), 377 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index dc5be79a4a..2070a2ced4 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -2,4 +2,377 @@ The QEMU Object Model (QOM) =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 +.. highlight:: c + +The QEMU Object Model provides a framework for registering user creatable +types and instantiating objects from those types. QOM provides the follow= ing +features: + + - System for dynamically registering types + - Support for single-inheritance of types + - Multiple inheritance of stateless interfaces + +.. code-block:: + :caption: Creating a minimal type + + #include "qdev.h" + + #define TYPE_MY_DEVICE "my-device" + + // No new virtual functions: we can reuse the typedef for the + // superclass. + typedef DeviceClass MyDeviceClass; + typedef struct MyDevice + { + DeviceState parent; + + int reg0, reg1, reg2; + } MyDevice; + + static const TypeInfo my_device_info =3D { + .name =3D TYPE_MY_DEVICE, + .parent =3D TYPE_DEVICE, + .instance_size =3D sizeof(MyDevice), + }; + + static void my_device_register_types(void) + { + type_register_static(&my_device_info); + } + + type_init(my_device_register_types) + +In the above example, we create a simple type that is described by #TypeIn= fo. +#TypeInfo describes information about the type including what it inherits +from, the instance and class size, and constructor/destructor hooks. + +Alternatively several static types could be registered using helper macro +DEFINE_TYPES() + +.. code-block:: + + static const TypeInfo device_types_info[] =3D { + { + .name =3D TYPE_MY_DEVICE_A, + .parent =3D TYPE_DEVICE, + .instance_size =3D sizeof(MyDeviceA), + }, + { + .name =3D TYPE_MY_DEVICE_B, + .parent =3D TYPE_DEVICE, + .instance_size =3D sizeof(MyDeviceB), + }, + }; + + DEFINE_TYPES(device_types_info) + +Every type has an #ObjectClass associated with it. #ObjectClass derivativ= es +are instantiated dynamically but there is only ever one instance for any +given type. The #ObjectClass typically holds a table of function pointers +for the virtual methods implemented by this type. + +Using object_new(), a new #Object derivative will be instantiated. You can +cast an #Object to a subclass (or base-class) type using +object_dynamic_cast(). You typically want to define macro wrappers around +OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a +specific type: + +.. code-block:: + :caption: Typecasting macros + +#define MY_DEVICE_GET_CLASS(obj) \ + OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) + #define MY_DEVICE_CLASS(klass) \ + OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) + #define MY_DEVICE(obj) \ + OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) + +Class Initialization +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Before an object is initialized, the class for the object must be +initialized. There is only one class object for all instance objects +that is created lazily. + +Classes are initialized by first initializing any parent classes (if +necessary). After the parent class object has initialized, it will be +copied into the current class object and any additional storage in the +class object is zero filled. + +The effect of this is that classes automatically inherit any virtual +function pointers that the parent class has already initialized. All +other fields will be zero filled. + +Once all of the parent classes have been initialized, #TypeInfo::class_init +is called to let the class being instantiated provide default initialize f= or +its virtual functions. Here is how the above example might be modified +to introduce an overridden virtual function: + +.. code-block:: + :caption: Overriding a virtual function + + #include "qdev.h" + + void my_device_class_init(ObjectClass *klass, void *class_data) + { + DeviceClass *dc =3D DEVICE_CLASS(klass); + dc->reset =3D my_device_reset; + } + + static const TypeInfo my_device_info =3D { + .name =3D TYPE_MY_DEVICE, + .parent =3D TYPE_DEVICE, + .instance_size =3D sizeof(MyDevice), + .class_init =3D my_device_class_init, + }; + +Introducing new virtual methods requires a class to define its own +struct and to add a .class_size member to the #TypeInfo. Each method +will also have a wrapper function to call it easily: + +.. code-block:: + :caption: Defining an abstract class + + #include "qdev.h" + + typedef struct MyDeviceClass + { + DeviceClass parent; + + void (*frobnicate) (MyDevice *obj); + } MyDeviceClass; + + static const TypeInfo my_device_info =3D { + .name =3D TYPE_MY_DEVICE, + .parent =3D TYPE_DEVICE, + .instance_size =3D sizeof(MyDevice), + .abstract =3D true, // or set a default in my_device_class_init + .class_size =3D sizeof(MyDeviceClass), + }; + + void my_device_frobnicate(MyDevice *obj) + { + MyDeviceClass *klass =3D MY_DEVICE_GET_CLASS(obj); + + klass->frobnicate(obj); + } + +Interfaces +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Interfaces allow a limited form of multiple inheritance. Instances are +similar to normal types except for the fact that are only defined by +their classes and never carry any state. As a consequence, a pointer to +an interface instance should always be of incomplete type in order to be +sure it cannot be dereferenced. That is, you should define the +'typedef struct SomethingIf SomethingIf' so that you can pass around +``SomethingIf *si`` arguments, but not define a ``struct SomethingIf { ...= }``. +The only things you can validly do with a ``SomethingIf *`` are to pass it= as +an argument to a method on its corresponding SomethingIfClass, or to +dynamically cast it to an object that implements the interface. + +Methods +=3D=3D=3D=3D=3D=3D=3D + +A method is a function within the namespace scope of +a class. It usually operates on the object instance by passing it as a +strongly-typed first argument. +If it does not operate on an object instance, it is dubbed +class method. + +Methods cannot be overloaded. That is, the #ObjectClass and method name +uniquely identity the function to be called; the signature does not vary +except for trailing varargs. + +Methods are always virtual. Overriding a method in +#TypeInfo.class_init of a subclass leads to any user of the class obtained +via OBJECT_GET_CLASS() accessing the overridden function. +The original function is not automatically invoked. It is the responsibili= ty +of the overriding class to determine whether and when to invoke the method +being overridden. + +To invoke the method being overridden, the preferred solution is to store +the original value in the overriding class before overriding the method. +This corresponds to ``{super,base}.method(...)`` in Java and C# +respectively; this frees the overriding class from hardcoding its parent +class, which someone might choose to change at some point. + +.. code-block:: + :caption: Overriding a virtual method + + typedef struct MyState MyState; + + typedef void (*MyDoSomething)(MyState *obj); + + typedef struct MyClass { + ObjectClass parent_class; + + MyDoSomething do_something; + } MyClass; + + static void my_do_something(MyState *obj) + { + // do something + } + + static void my_class_init(ObjectClass *oc, void *data) + { + MyClass *mc =3D MY_CLASS(oc); + + mc->do_something =3D my_do_something; + } + + static const TypeInfo my_type_info =3D { + .name =3D TYPE_MY, + .parent =3D TYPE_OBJECT, + .instance_size =3D sizeof(MyState), + .class_size =3D sizeof(MyClass), + .class_init =3D my_class_init, + }; + + typedef struct DerivedClass { + MyClass parent_class; + + MyDoSomething parent_do_something; + } DerivedClass; + + static void derived_do_something(MyState *obj) + { + DerivedClass *dc =3D DERIVED_GET_CLASS(obj); + + // do something here + dc->parent_do_something(obj); + // do something else here + } + + static void derived_class_init(ObjectClass *oc, void *data) + { + MyClass *mc =3D MY_CLASS(oc); + DerivedClass *dc =3D DERIVED_CLASS(oc); + + dc->parent_do_something =3D mc->do_something; + mc->do_something =3D derived_do_something; + } + + static const TypeInfo derived_type_info =3D { + .name =3D TYPE_DERIVED, + .parent =3D TYPE_MY, + .class_size =3D sizeof(DerivedClass), + .class_init =3D derived_class_init, + }; + +Alternatively, object_class_by_name() can be used to obtain the class and +its non-overridden methods for a specific type. This would correspond to +``MyClass::method(...)`` in C++. + +The first example of such a QOM method was #CPUClass.reset, +another example is #DeviceClass.realize. + +Standard type declaration and definition macros +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +A lot of the code outlined above follows a standard pattern and naming +convention. To reduce the amount of boilerplate code that needs to be +written for a new type there are two sets of macros to generate the +common parts in a standard format. + +A type is declared using the OBJECT_DECLARE macro family. In types +which do not require any virtual functions in the class, the +OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed +in the header file: + +.. code-block:: + :caption: Declaring a simple type + + OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) + +This is equivalent to the following: + +.. code-block:: + :caption: Expansion from declaring a simple type + + typedef struct MyDevice MyDevice; + typedef struct MyDeviceClass MyDeviceClass; + + G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref) + + #define MY_DEVICE_GET_CLASS(void *obj) \ + OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) + #define MY_DEVICE_CLASS(void *klass) \ + OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) + #define MY_DEVICE(void *obj) + OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) + + struct MyDeviceClass { + DeviceClass parent_class; + }; + +The 'struct MyDevice' needs to be declared separately. +If the type requires virtual functions to be declared in the class +struct, then the alternative OBJECT_DECLARE_TYPE() macro can be +used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without +the 'struct MyDeviceClass' definition. + +To implement the type, the OBJECT_DEFINE macro family is available. +In the simple case the OBJECT_DEFINE_TYPE macro is suitable: + +.. code-block:: + :caption: Defining a simple type + + OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) + +This is equivalent to the following: + +.. code-block:: + :caption: Expansion from defining a simple type + + static void my_device_finalize(Object *obj); + static void my_device_class_init(ObjectClass *oc, void *data); + static void my_device_init(Object *obj); + + static const TypeInfo my_device_info =3D { + .parent =3D TYPE_DEVICE, + .name =3D TYPE_MY_DEVICE, + .instance_size =3D sizeof(MyDevice), + .instance_init =3D my_device_init, + .instance_finalize =3D my_device_finalize, + .class_size =3D sizeof(MyDeviceClass), + .class_init =3D my_device_class_init, + }; + + static void + my_device_register_types(void) + { + type_register_static(&my_device_info); + } + type_init(my_device_register_types); + +This is sufficient to get the type registered with the type +system, and the three standard methods now need to be implemented +along with any other logic required for the type. + +If the type needs to implement one or more interfaces, then the +OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead. +This accepts an array of interface type names. + +.. code-block:: + :caption: Defining a simple type implementing interfaces + + OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device, + MY_DEVICE, DEVICE, + { TYPE_USER_CREATABLE }, { NULL }) + +If the type is not intended to be instantiated, then then +the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: + +.. code-block:: + :caption: Defining a simple abstract type + + OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) + + + +API Reference +------------- + .. kernel-doc:: include/qom/object.h diff --git a/include/qom/object.h b/include/qom/object.h index 75ef97da31..8632484cc0 100644 --- a/include/qom/object.h +++ b/include/qom/object.h @@ -28,383 +28,6 @@ typedef struct InterfaceInfo InterfaceInfo; =20 #define TYPE_OBJECT "object" =20 -/** - * DOC: - * - * .. highlight:: c - * - * The QEMU Object Model provides a framework for registering user creatab= le - * types and instantiating objects from those types. QOM provides the fol= lowing - * features: - * - * - System for dynamically registering types - * - Support for single-inheritance of types - * - Multiple inheritance of stateless interfaces - * - * .. code-block:: - * :caption: Creating a minimal type - * - * #include "qdev.h" - * - * #define TYPE_MY_DEVICE "my-device" - * - * // No new virtual functions: we can reuse the typedef for the - * // superclass. - * typedef DeviceClass MyDeviceClass; - * typedef struct MyDevice - * { - * DeviceState parent; - * - * int reg0, reg1, reg2; - * } MyDevice; - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * }; - * - * static void my_device_register_types(void) - * { - * type_register_static(&my_device_info); - * } - * - * type_init(my_device_register_types) - * - * In the above example, we create a simple type that is described by #Typ= eInfo. - * #TypeInfo describes information about the type including what it inheri= ts - * from, the instance and class size, and constructor/destructor hooks. - * - * Alternatively several static types could be registered using helper mac= ro - * DEFINE_TYPES() - * - * .. code-block:: - * - * static const TypeInfo device_types_info[] =3D { - * { - * .name =3D TYPE_MY_DEVICE_A, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDeviceA), - * }, - * { - * .name =3D TYPE_MY_DEVICE_B, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDeviceB), - * }, - * }; - * - * DEFINE_TYPES(device_types_info) - * - * Every type has an #ObjectClass associated with it. #ObjectClass deriva= tives - * are instantiated dynamically but there is only ever one instance for any - * given type. The #ObjectClass typically holds a table of function point= ers - * for the virtual methods implemented by this type. - * - * Using object_new(), a new #Object derivative will be instantiated. You= can - * cast an #Object to a subclass (or base-class) type using - * object_dynamic_cast(). You typically want to define macro wrappers aro= und - * OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to= a - * specific type: - * - * .. kernel-doc messes up with the code block below because of the - * backslash at the end of lines. This will be fixes if we move this - * content to qom.rst. - * - * .. code-block:: - * :caption: Typecasting macros - * - * #define MY_DEVICE_GET_CLASS(obj) \ - * OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) - * #define MY_DEVICE_CLASS(klass) \ - * OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) - * #define MY_DEVICE(obj) \ - * OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) - * - * Class Initialization - * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - * - * Before an object is initialized, the class for the object must be - * initialized. There is only one class object for all instance objects - * that is created lazily. - * - * Classes are initialized by first initializing any parent classes (if - * necessary). After the parent class object has initialized, it will be - * copied into the current class object and any additional storage in the - * class object is zero filled. - * - * The effect of this is that classes automatically inherit any virtual - * function pointers that the parent class has already initialized. All - * other fields will be zero filled. - * - * Once all of the parent classes have been initialized, #TypeInfo::class_= init - * is called to let the class being instantiated provide default initializ= e for - * its virtual functions. Here is how the above example might be modified - * to introduce an overridden virtual function: - * - * .. code-block:: - * :caption: Overriding a virtual function - * - * #include "qdev.h" - * - * void my_device_class_init(ObjectClass *klass, void *class_data) - * { - * DeviceClass *dc =3D DEVICE_CLASS(klass); - * dc->reset =3D my_device_reset; - * } - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * .class_init =3D my_device_class_init, - * }; - * - * Introducing new virtual methods requires a class to define its own - * struct and to add a .class_size member to the #TypeInfo. Each method - * will also have a wrapper function to call it easily: - * - * .. code-block:: - * :caption: Defining an abstract class - * - * #include "qdev.h" - * - * typedef struct MyDeviceClass - * { - * DeviceClass parent; - * - * void (*frobnicate) (MyDevice *obj); - * } MyDeviceClass; - * - * static const TypeInfo my_device_info =3D { - * .name =3D TYPE_MY_DEVICE, - * .parent =3D TYPE_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * .abstract =3D true, // or set a default in my_device_class_init - * .class_size =3D sizeof(MyDeviceClass), - * }; - * - * void my_device_frobnicate(MyDevice *obj) - * { - * MyDeviceClass *klass =3D MY_DEVICE_GET_CLASS(obj); - * - * klass->frobnicate(obj); - * } - * - * Interfaces - * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - * - * Interfaces allow a limited form of multiple inheritance. Instances are - * similar to normal types except for the fact that are only defined by - * their classes and never carry any state. As a consequence, a pointer to - * an interface instance should always be of incomplete type in order to be - * sure it cannot be dereferenced. That is, you should define the - * 'typedef struct SomethingIf SomethingIf' so that you can pass around - * ``SomethingIf *si`` arguments, but not define a ``struct SomethingIf { = ... }``. - * The only things you can validly do with a ``SomethingIf *`` are to pass= it as - * an argument to a method on its corresponding SomethingIfClass, or to - * dynamically cast it to an object that implements the interface. - * - * Methods - * =3D=3D=3D=3D=3D=3D=3D - * - * A method is a function within the namespace scope = of - * a class. It usually operates on the object instance by passing it as a - * strongly-typed first argument. - * If it does not operate on an object instance, it is dubbed - * class method. - * - * Methods cannot be overloaded. That is, the #ObjectClass and method name - * uniquely identity the function to be called; the signature does not vary - * except for trailing varargs. - * - * Methods are always virtual. Overriding a method in - * #TypeInfo.class_init of a subclass leads to any user of the class obtai= ned - * via OBJECT_GET_CLASS() accessing the overridden function. - * The original function is not automatically invoked. It is the responsib= ility - * of the overriding class to determine whether and when to invoke the met= hod - * being overridden. - * - * To invoke the method being overridden, the preferred solution is to sto= re - * the original value in the overriding class before overriding the method. - * This corresponds to ``{super,base}.method(...)`` in Java and C# - * respectively; this frees the overriding class from hardcoding its parent - * class, which someone might choose to change at some point. - * - * .. code-block:: - * :caption: Overriding a virtual method - * - * typedef struct MyState MyState; - * - * typedef void (*MyDoSomething)(MyState *obj); - * - * typedef struct MyClass { - * ObjectClass parent_class; - * - * MyDoSomething do_something; - * } MyClass; - * - * static void my_do_something(MyState *obj) - * { - * // do something - * } - * - * static void my_class_init(ObjectClass *oc, void *data) - * { - * MyClass *mc =3D MY_CLASS(oc); - * - * mc->do_something =3D my_do_something; - * } - * - * static const TypeInfo my_type_info =3D { - * .name =3D TYPE_MY, - * .parent =3D TYPE_OBJECT, - * .instance_size =3D sizeof(MyState), - * .class_size =3D sizeof(MyClass), - * .class_init =3D my_class_init, - * }; - * - * typedef struct DerivedClass { - * MyClass parent_class; - * - * MyDoSomething parent_do_something; - * } DerivedClass; - * - * static void derived_do_something(MyState *obj) - * { - * DerivedClass *dc =3D DERIVED_GET_CLASS(obj); - * - * // do something here - * dc->parent_do_something(obj); - * // do something else here - * } - * - * static void derived_class_init(ObjectClass *oc, void *data) - * { - * MyClass *mc =3D MY_CLASS(oc); - * DerivedClass *dc =3D DERIVED_CLASS(oc); - * - * dc->parent_do_something =3D mc->do_something; - * mc->do_something =3D derived_do_something; - * } - * - * static const TypeInfo derived_type_info =3D { - * .name =3D TYPE_DERIVED, - * .parent =3D TYPE_MY, - * .class_size =3D sizeof(DerivedClass), - * .class_init =3D derived_class_init, - * }; - * - * Alternatively, object_class_by_name() can be used to obtain the class a= nd - * its non-overridden methods for a specific type. This would correspond to - * ``MyClass::method(...)`` in C++. - * - * The first example of such a QOM method was #CPUClass.reset, - * another example is #DeviceClass.realize. - * - * Standard type declaration and definition macros - * =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - * - * A lot of the code outlined above follows a standard pattern and naming - * convention. To reduce the amount of boilerplate code that needs to be - * written for a new type there are two sets of macros to generate the - * common parts in a standard format. - * - * A type is declared using the OBJECT_DECLARE macro family. In types - * which do not require any virtual functions in the class, the - * OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed - * in the header file: - * - * .. code-block:: - * :caption: Declaring a simple type - * - * OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - * - * This is equivalent to the following: - * - * .. code-block:: - * :caption: Expansion from declaring a simple type - * - * typedef struct MyDevice MyDevice; - * typedef struct MyDeviceClass MyDeviceClass; - * - * G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref) - * - * #define MY_DEVICE_GET_CLASS(void *obj) \ - * OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) - * #define MY_DEVICE_CLASS(void *klass) \ - * OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE) - * #define MY_DEVICE(void *obj) - * OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) - * - * struct MyDeviceClass { - * DeviceClass parent_class; - * }; - * - * The 'struct MyDevice' needs to be declared separately. - * If the type requires virtual functions to be declared in the class - * struct, then the alternative OBJECT_DECLARE_TYPE() macro can be - * used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without - * the 'struct MyDeviceClass' definition. - * - * To implement the type, the OBJECT_DEFINE macro family is available. - * In the simple case the OBJECT_DEFINE_TYPE macro is suitable: - * - * .. code-block:: - * :caption: Defining a simple type - * - * OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - * - * This is equivalent to the following: - * - * .. code-block:: - * :caption: Expansion from defining a simple type - * - * static void my_device_finalize(Object *obj); - * static void my_device_class_init(ObjectClass *oc, void *data); - * static void my_device_init(Object *obj); - * - * static const TypeInfo my_device_info =3D { - * .parent =3D TYPE_DEVICE, - * .name =3D TYPE_MY_DEVICE, - * .instance_size =3D sizeof(MyDevice), - * .instance_init =3D my_device_init, - * .instance_finalize =3D my_device_finalize, - * .class_size =3D sizeof(MyDeviceClass), - * .class_init =3D my_device_class_init, - * }; - * - * static void - * my_device_register_types(void) - * { - * type_register_static(&my_device_info); - * } - * type_init(my_device_register_types); - * - * This is sufficient to get the type registered with the type - * system, and the three standard methods now need to be implemented - * along with any other logic required for the type. - * - * If the type needs to implement one or more interfaces, then the - * OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead. - * This accepts an array of interface type names. - * - * .. code-block:: - * :caption: Defining a simple type implementing interfaces - * - * OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device, - * MY_DEVICE, DEVICE, - * { TYPE_USER_CREATABLE }, { NULL = }) - * - * If the type is not intended to be instantiated, then then - * the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: - * - * .. code-block:: - * :caption: Defining a simple abstract type - * - * OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) - */ - - typedef struct ObjectProperty ObjectProperty; =20 /** --=20 2.26.2