From patchwork Thu Jul 29 17:55:45 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511358 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=PbRJk+XJ; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJDm3Sdrz9sS8 for ; Fri, 30 Jul 2021 03:58:48 +1000 (AEST) Received: from localhost ([::1]:51680 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AIw-0003en-6m for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 13:58:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52446) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGN-0006T5-PY for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:07 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:54367) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGI-0007t4-2k for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:07 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581360; 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=85ErR7+WiEu/O4u03QCNLmaS5ihB7R0FWBSKyVW3dKQ=; b=PbRJk+XJ9idFTWNeoa5Zx2SKG/3e+DZJL23XQ2nDAzQlpToQ1VuxoLIXA+ex55lCtfHdrY PACXImiVKZRd4nNbku242thRMEOPi2rRhoPo4OHb4zY1h9JfgJ0i/Uf0qqHruxSOMTAZNi UTUsWlK9g+0/B3T4gmqENX/Q2jAVM+0= 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-522-33NwiUv_Ml2fRdJ6cSSfyQ-1; Thu, 29 Jul 2021 13:55:56 -0400 X-MC-Unique: 33NwiUv_Ml2fRdJ6cSSfyQ-1 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 E51AEC73A1 for ; Thu, 29 Jul 2021 17:55:55 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id AE1CD5D6B1; Thu, 29 Jul 2021 17:55:55 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` Date: Thu, 29 Jul 2021 13:55:45 -0400 Message-Id: <20210729175554.686474-2-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-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 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Replace leftover of GTK-Doc #name syntax with `name`, and use default-role:: any, so we can add references to other functions, types, and macros. There are 3 cases that required extra care: - #TypeInfo.class_init: kernel-doc doesn't generate c:member:: directives, so references to C struct members are not possible yet. This was replaced with `TypeInfo`.class_init. - #CPUClass.reset and #DeviceClass.realize: cpu.h and qdev docs are not rendered using Sphinx yet, so use ``code`` syntax for those. Signed-off-by: Eduardo Habkost --- docs/devel/qom.rst | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index e5fe3597cd8..9c1be5d7fc2 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -3,6 +3,7 @@ The QEMU Object Model (QOM) =========================== .. highlight:: c +.. default-role:: any The QEMU Object Model provides a framework for registering user creatable types and instantiating objects from those types. QOM provides the following @@ -42,8 +43,8 @@ features: type_init(my_device_register_types) -In the above example, we create a simple type that is described by #TypeInfo. -#TypeInfo describes information about the type including what it inherits +In the above example, we create a simple type that is described by `TypeInfo`. +`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 @@ -66,13 +67,13 @@ DEFINE_TYPES() DEFINE_TYPES(device_types_info) -Every type has an #ObjectClass associated with it. #ObjectClass derivatives +Every type has an `ObjectClass` associated with it. `ObjectClass` derivatives are instantiated dynamically but there is only ever one instance for any -given type. The #ObjectClass typically holds a table of function pointers +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 +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: @@ -111,7 +112,7 @@ 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 +Once all of the parent classes have been initialized, `TypeInfo`::class_init is called to let the class being instantiated provide default initialize for its virtual functions. Here is how the above example might be modified to introduce an overridden virtual function: @@ -135,7 +136,7 @@ to introduce an overridden virtual function: }; Introducing new virtual methods requires a class to define its own -struct and to add a .class_size member to the #TypeInfo. Each method +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:: c @@ -188,12 +189,12 @@ 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 +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 +`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 responsibility of the overriding class to determine whether and when to invoke the method @@ -273,8 +274,8 @@ 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. +The first example of such a QOM method was ``CPUClass.reset``, +another example is ``DeviceClass.realize``. Standard type declaration and definition macros =============================================== From patchwork Thu Jul 29 17:55:46 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511359 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=R1ura1P0; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJDp3ZtVz9sRf for ; Fri, 30 Jul 2021 03:58:50 +1000 (AEST) Received: from localhost ([::1]:51848 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AIy-0003l3-6a for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 13:58:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52416) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGM-0006Rv-25 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:07 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:50433) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGH-0007rx-4V for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:05 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581359; 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=ivaE5S9bKA3xHrbRd64RrA4HNkbsfH8TsdenqyMEYjU=; b=R1ura1P0ziCiQMCAuL17ZnLEmzlGplJqI9NPNcn0JHxtqVJXxbrbDQrDZJxiyO8i9J3wDs 2H1a3h60apGSpULG7L76Yr0hDYrjyICja6UkeqrOY1qH/oYwB6B9xROKavGAc1aXKvZQih CvC9i38KOigQ35/h4O+Sc+UTPmvIxQM= 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-349-3Xb9MFQ3P5mRnuvmFkl4nQ-1; Thu, 29 Jul 2021 13:55:57 -0400 X-MC-Unique: 3Xb9MFQ3P5mRnuvmFkl4nQ-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D81CE8799E0 for ; Thu, 29 Jul 2021 17:55:56 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id A16C45C1D1; Thu, 29 Jul 2021 17:55:56 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 02/10] docs: qom: Use Sphinx cross references more often Date: Thu, 29 Jul 2021 13:55:46 -0400 Message-Id: <20210729175554.686474-3-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, 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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" To make the document easier to navigate, use `reference` syntax more often when mentioning other types, functions, and macros. Signed-off-by: Eduardo Habkost --- docs/devel/qom.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 9c1be5d7fc2..3499a8ca3b6 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -48,7 +48,7 @@ In the above example, we create a simple type that is described by `TypeInfo`. from, the instance and class size, and constructor/destructor hooks. Alternatively several static types could be registered using helper macro -DEFINE_TYPES() +`DEFINE_TYPES()`: .. code-block:: c @@ -72,10 +72,10 @@ 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 +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 +`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:: c @@ -195,7 +195,7 @@ 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. +via `OBJECT_GET_CLASS()` accessing the overridden function. The original function is not automatically invoked. It is the responsibility of the overriding class to determine whether and when to invoke the method being overridden. @@ -270,7 +270,7 @@ class, which someone might choose to change at some point. .class_init = derived_class_init, }; -Alternatively, object_class_by_name() can be used to obtain the class and +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++. @@ -285,9 +285,9 @@ 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 +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 +`OBJECT_DECLARE_SIMPLE_TYPE` macro is suitable, and is commonly placed in the header file: .. code-block:: c @@ -319,12 +319,12 @@ This is equivalent to the following: 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 +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: +To implement the type, the ``OBJECT_DEFINE`` macro family is available. +In the simple case the `OBJECT_DEFINE_TYPE()` macro is suitable: .. code-block:: c :caption: Defining a simple type @@ -362,7 +362,7 @@ 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. +`OBJECT_DEFINE_TYPE_WITH_INTERFACES()` macro can be used instead. This accepts an array of interface type names. .. code-block:: c @@ -374,7 +374,7 @@ This accepts an array of interface type names. { NULL }) If the type is not intended to be instantiated, then then -the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: +the `OBJECT_DEFINE_ABSTRACT_TYPE()` macro can be used instead: .. code-block:: c :caption: Defining a simple abstract type From patchwork Thu Jul 29 17:55:47 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511357 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=WkpK/gPB; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJDl6Vqsz9sRf for ; Fri, 30 Jul 2021 03:58:47 +1000 (AEST) Received: from localhost ([::1]:51708 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AIv-0003fE-JJ for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 13:58:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52360) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGI-0006Lf-6L for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:02 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:39005) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGG-0007sJ-7I for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:01 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581359; 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=edC1pJilsnl1UQRSlIlaG7i1yibsPNWYr3Vhj3h9MxA=; b=WkpK/gPBeFLvNN/3/xHavQR9d2nTVkA0goV2I9xsOjDua7lCrH9z3609DbPH365Up52eRl PM8NuXrgfZ7IzvySM6uCTDH5DwquxC3yNc+L2gzq9Q1/Nreic6iY2skiMn0IQOMjxrLN3M /W896ldPtG7EaJ/Ft8aWHSwHJ8li3/E= 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-262-qq8O0wxUMkerD6_MFrOWdA-1; Thu, 29 Jul 2021 13:55:58 -0400 X-MC-Unique: qq8O0wxUMkerD6_MFrOWdA-1 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 9CA558799EB for ; Thu, 29 Jul 2021 17:55:57 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6CEA25D6B1; Thu, 29 Jul 2021 17:55:57 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 03/10] docs: qom: Fix autoptr expansion example Date: Thu, 29 Jul 2021 13:55:47 -0400 Message-Id: <20210729175554.686474-4-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-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 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The wrong type name was being used. The autoptr cleanup function will be declared for the instance type, not the class type. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 3499a8ca3b6..7ef16d92ca6 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -304,7 +304,7 @@ This is equivalent to the following: typedef struct MyDevice MyDevice; typedef struct MyDeviceClass MyDeviceClass; - G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref) + G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref) #define MY_DEVICE_GET_CLASS(void *obj) \ OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE) From patchwork Thu Jul 29 17:55:48 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511356 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=QdWOX4Lx; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJBG2FPyz9sRf for ; Fri, 30 Jul 2021 03:56:38 +1000 (AEST) Received: from localhost ([::1]:43324 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AGq-0006Sn-26 for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 13:56:36 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52396) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGK-0006Od-1R for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:04 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:42141) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGH-0007tM-TM for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:03 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581360; 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=aiUhVtMvjNr132nzP9uQICM1A/zGo5kPsRVLDthVcso=; b=QdWOX4LxIlS4os2swYf6EIGm10aiFJD+AiF2/HpmPmnouzxqGjSZhMrwElnQQxGPOKccL8 L6kszgDtmLLETqarGxM1SeFqwcNQHauuWfI1PemSMqLb/NFIG1vgoZwCVtwwyBrsxl3ie7 1hqbDj1wk2rXcKh74Ws/ydrDH0p8rXs= 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-463-8fPqjlYbPECzeYmA5Y57Ng-1; Thu, 29 Jul 2021 13:55:59 -0400 X-MC-Unique: 8fPqjlYbPECzeYmA5Y57Ng-1 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 647DF1006C83 for ; Thu, 29 Jul 2021 17:55:58 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3795960BF1; Thu, 29 Jul 2021 17:55:58 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level Date: Thu, 29 Jul 2021 13:55:48 -0400 Message-Id: <20210729175554.686474-5-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-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 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, 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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The API reference section was being rendered as a subsection of the "Standard type declaration and definition macros" subsection. Fix that. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 7ef16d92ca6..3f48016aa8f 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -385,6 +385,6 @@ the `OBJECT_DEFINE_ABSTRACT_TYPE()` macro can be used instead: API Reference -------------- +============= .. kernel-doc:: include/qom/object.h From patchwork Thu Jul 29 17:55:49 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511361 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=IKx9DLuT; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJH45xqsz9sRf for ; Fri, 30 Jul 2021 04:00:48 +1000 (AEST) Received: from localhost ([::1]:59174 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AKs-0000BJ-Hi for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:00:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52454) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGO-0006VO-Vs for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:09 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:28350) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGL-0007vj-Sb for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:08 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581364; 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=ONvZn/eqpVhDcFV+idKq4az2nOISBx6LR+BPKVwnOls=; b=IKx9DLuTLOzcuMS7KoKzjc4PzMZKnCq/SZCn+PvZ0tm7I3EzIzaTlBYWUn32CjBsB7yYvx YzQnSQqrzaAJFkK44Z0QwwvH2AGPkL0mtCk6PQgRKwTWnQKURy/lYjJ3P/1+rXzYImXjax qC1G3FNaLhiBzeV3V+M0U34JQhW72xk= 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-313-Oi-Vmm3NNAGwKJs8bn1X3Q-1; Thu, 29 Jul 2021 13:56:03 -0400 X-MC-Unique: Oi-Vmm3NNAGwKJs8bn1X3Q-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 3F2E2800D55 for ; Thu, 29 Jul 2021 17:56:02 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 130EE60875; Thu, 29 Jul 2021 17:55:58 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section Date: Thu, 29 Jul 2021 13:55:49 -0400 Message-Id: <20210729175554.686474-6-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, 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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Add two new subsection headings to make the separation between "declaration macros" and "definition macros" more visible. Signed-off-by: Eduardo Habkost Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 3f48016aa8f..05d045bf570 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -285,6 +285,9 @@ 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. +Type declaration macros +----------------------- + 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 @@ -323,6 +326,9 @@ 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. +Type definition macros +---------------------- + To implement the type, the ``OBJECT_DEFINE`` macro family is available. In the simple case the `OBJECT_DEFINE_TYPE()` macro is suitable: From patchwork Thu Jul 29 17:55:50 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511360 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=AfSpXdKE; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJH31ZZNz9sRf for ; Fri, 30 Jul 2021 04:00:47 +1000 (AEST) Received: from localhost ([::1]:59042 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AKq-00005p-Fi for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:00:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52486) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGR-0006bd-Af for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:11 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:40467) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGP-0007yh-MY for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581369; 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=S860YdtNoc77PfMKfZoGPzVURCkoaFO2STQSDN5Val8=; b=AfSpXdKEb2f/AO9pNbvwu2qsHtLv8alB3LALVexowgDiFrX3cSLWAyRX6vnhEqYIyXKGPK J5Dkcl4SJXShQT6cSu0aHjY24nJaS4nPqVtW6BguYYct3Xu1bgOPMhYstkmPv8Kj/JBbtq KxeMC3AAawIUQ4RxPQO8NfLQm0yYW6A= 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-338-1xmUPN_7OzGfh70rRs8DWw-1; Thu, 29 Jul 2021 13:56:07 -0400 X-MC-Unique: 1xmUPN_7OzGfh70rRs8DWw-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id DC0891006C80 for ; Thu, 29 Jul 2021 17:56:06 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id E9EB326DF1; Thu, 29 Jul 2021 17:56:02 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example Date: Thu, 29 Jul 2021 13:55:50 -0400 Message-Id: <20210729175554.686474-7-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" When there's no specific class struct used for a QOM type, we normally don't define a typedef for it. Remove the typedef from the minimal example, as it is unnecessary. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 05d045bf570..dee60a64c0a 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -20,9 +20,6 @@ features: #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; From patchwork Thu Jul 29 17:55:51 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511363 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=Hut+FUts; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJJs5zmkz9sV8 for ; Fri, 30 Jul 2021 04:02:21 +1000 (AEST) Received: from localhost ([::1]:36426 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AMM-0003wP-Jt for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:02:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52492) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGS-0006eh-1B for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:12 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:44728) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGQ-0007yw-B9 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:11 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581369; 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=VrwOXZjoMlSOSd1gS8VgEIBNr3crQj9rqLjxxiRwGag=; b=Hut+FUtsu+Mc0UfzTtnSHwJvcnjOC8qevqZtQ8kUdghY9a3McwDZDlPfACopp2cb63W/h7 WDBp4pYjGJd7F17kj2fLb5vG9DvPzoMx3+nHGp0E+fSFRqjVscnKrybCPFUGquKB+qGcsb BV+LQ09X8YkOnEtNSWxEeduPR3I7UR8= 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-324-HvwbxB85MPKwoNEBqTzuUw-1; Thu, 29 Jul 2021 13:56:08 -0400 X-MC-Unique: HvwbxB85MPKwoNEBqTzuUw-1 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 AAF4E8799EB for ; Thu, 29 Jul 2021 17:56:07 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7462810016F5; Thu, 29 Jul 2021 17:56:07 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation Date: Thu, 29 Jul 2021 13:55:51 -0400 Message-Id: <20210729175554.686474-8-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-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 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The OBJECT_DECLARE_SIMPLE_TYPE documentation was inaccurate: it doesn't define a class struct or class type checking helpers. OBJECT_DECLARE_TYPE expansion looks very similar to the existing example, though. Rewrite that section to show both both OBJECT_DECLARE_SIMPLE_TYPE and OBJECT_DECLARE_TYPE. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index dee60a64c0a..aa1f672efbe 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -301,6 +301,27 @@ This is equivalent to the following: .. code-block:: c :caption: Expansion from declaring a simple type + typedef struct MyDevice MyDevice; + G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref) + #define MY_DEVICE(void *obj) + OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) + +The 'struct MyDevice' needs to be declared separately. + +If the type requires virtual functions to be declared in a class +struct, then the alternative `OBJECT_DECLARE_TYPE()` macro can be +used: + +.. code-block:: c + :caption: Declaring a type with custom class struct + + OBJECT_DECLARE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE) + +This is equivalent to the following: + +.. code-block:: c + :caption: Expansion from declaring a type with custom class struct + typedef struct MyDevice MyDevice; typedef struct MyDeviceClass MyDeviceClass; @@ -313,16 +334,6 @@ This is equivalent to the following: #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. - Type definition macros ---------------------- From patchwork Thu Jul 29 17:55:52 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511362 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=FOVeBK/p; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJJs5M6Sz9sT6 for ; Fri, 30 Jul 2021 04:02:21 +1000 (AEST) Received: from localhost ([::1]:36448 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AMM-0003x0-7C for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:02:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52520) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGV-0006s7-CH for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:15 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:39666) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGT-00081V-Kn for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:15 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581372; 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=W9T+GXXBUzKf6Acq+ENzctJe/hvCuPWDINxzhQcrxDE=; b=FOVeBK/p4nWZiWQJH6yVkcazhjpmmcCiGmV1ch1ZSaQ+KwDxu9F3TiRJT1SrNT0V3v+vtq 8CJroRv5UV7SnIfxPrdTUfSjG77U1xDeOw05M3DAFy7yu32poZIYzwBkvHTJ4XVjxpdrML VrcWVB4+ayeLuyxRA2JMol5xMJecMRM= 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-371-OTiRZR-aOTOt36v367JFwg-1; Thu, 29 Jul 2021 13:56:09 -0400 X-MC-Unique: OTiRZR-aOTOt36v367JFwg-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8541A1006C81 for ; Thu, 29 Jul 2021 17:56:08 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 535845C1D1; Thu, 29 Jul 2021 17:56:08 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples Date: Thu, 29 Jul 2021 13:55:52 -0400 Message-Id: <20210729175554.686474-9-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=216.205.24.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, 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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" For clarity and to avoid encouraging people to copy the examples, show the actual typecast functions being defined by OBJECT_DECLARE* macros in the examples. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index aa1f672efbe..3ae6f75a1a2 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -303,8 +303,10 @@ This is equivalent to the following: typedef struct MyDevice MyDevice; G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref) - #define MY_DEVICE(void *obj) - OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE) + static inline MyDevice *MY_DEVICE(void *obj) + { + return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE); + } The 'struct MyDevice' needs to be declared separately. @@ -327,12 +329,18 @@ This is equivalent to the following: G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, 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) + static inline MyDeviceClass *MY_DEVICE_GET_CLASS(void *obj) + { + return OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE); + } + static inline MyDeviceClass *MY_DEVICE_CLASS(void *klass) + { + return OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE); + } + static inline MyDevice *MY_DEVICE(void *obj) + { + return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE); + } Type definition macros ---------------------- From patchwork Thu Jul 29 17:55:53 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511364 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=NGG1+kDb; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJLp735kz9sRf for ; Fri, 30 Jul 2021 04:04:02 +1000 (AEST) Received: from localhost ([::1]:40700 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AO0-0006o9-Oq for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:04:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52510) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGU-0006nu-3l for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:14 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:24889) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGS-00080j-B3 for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:13 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581371; 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=PFauT1gi4Um7HvJ1OXpmVPNsZptBn73opwaZb9cI1hE=; b=NGG1+kDbmM23L1UEH7lPIKI1zp81X5VKT/p+AIDhkDcYdDjnqPLpJUyIGvZccVhXB58DLI pnSR5Ux+S/KWSm0ELVAh6HUBectlYyftabJvfiQuLabGBwT2GUQojryCb45tS2WRC1q83g sEcvYhg/QtGde/okSJtI1xLlu22V/KA= 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-544-sOrFrnvOOZS8gpLSfk_KoQ-1; Thu, 29 Jul 2021 13:56:10 -0400 X-MC-Unique: sOrFrnvOOZS8gpLSfk_KoQ-1 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 730861006C85 for ; Thu, 29 Jul 2021 17:56:09 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 2F65D60BF1; Thu, 29 Jul 2021 17:56:09 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples Date: Thu, 29 Jul 2021 13:55:53 -0400 Message-Id: <20210729175554.686474-10-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-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 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" We shouldn't encourage people to keep defining typecast macros manually, when we have the OBJECT_DECLARE* macros. Remove the section showing how to define them, and replace with a section explaining how typecasting works. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- docs/devel/qom.rst | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 3ae6f75a1a2..0f222555019 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -69,21 +69,10 @@ 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:: c - :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) +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()` or :ref:`typecast +wrappers `. In case the ObjectClass implementation can be built as module a module_obj() line must be added to make sure qemu loads the module @@ -93,6 +82,31 @@ when the object is needed. module_obj(TYPE_MY_DEVICE); +.. _typecasting: + +Typecasting +=========== + +The `OBJECT_DECLARE macros ` automatically define +typecasting functions having signatures like these: + +.. code-block:: c + + static inline MyDevice *MY_DEVICE(const void *obj); + static inline MyDeviceClass *MY_DEVICE_GET_CLASS(const void *obj); + static inline MyDeviceClass *MY_DEVICE_CLASS(const void *klass); + +These typecasting functions are wrappers around `OBJECT_CHECK`, +`OBJECT_GET_CLASS`, and `OBJECT_CLASS_CHECK`. Example usage: + +.. code-block:: c + + Object *obj = object_new("my-device"); + MyDevice *my_dev = MY_DEVICE(obj); + DeviceState *dev = DEVICE(my_dev); + MyDeviceClass *mdc = MY_DEVICE_GET_CLASS(my_dev); + DeviceClass *dc = DEVICE_CLASS(mdc); + Class Initialization ==================== @@ -282,6 +296,8 @@ 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. +.. _OBJECT_DECLARE: + Type declaration macros ----------------------- From patchwork Thu Jul 29 17:55:54 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eduardo Habkost X-Patchwork-Id: 1511365 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=T8UrnZFj; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4GbJLw0YBCz9sRf for ; Fri, 30 Jul 2021 04:04:08 +1000 (AEST) Received: from localhost ([::1]:40702 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m9AO5-0006oF-7G for incoming@patchwork.ozlabs.org; Thu, 29 Jul 2021 14:04:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52544) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGZ-00079Z-Iy for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:19 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:23528) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m9AGY-00084A-0I for qemu-devel@nongnu.org; Thu, 29 Jul 2021 13:56:19 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1627581377; 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=IXRH/3F3pGyMEXw517FWJVKxJJkdIlHbSaukBYqY7YY=; b=T8UrnZFjTTLIjKfv+rjOyJUAUys7kyOJxqfFz73RXgYiLQIxpaAowgATsQMWL0P4Z5ieka D65VHhUYSB0VudnBMFld5udhHIbnhAJxcc/rfo8/rDM1CggSQPJw5p6T+FfY+i39wEKWXC Z7wjZ2Djlxp3yTlLvdcoYPG1xHx2qKA= 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-196-_NQHPLQjOz6L9x76PAYeqw-1; Thu, 29 Jul 2021 13:56:11 -0400 X-MC-Unique: _NQHPLQjOz6L9x76PAYeqw-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4F7BD8799E0 for ; Thu, 29 Jul 2021 17:56:10 +0000 (UTC) Received: from localhost (unknown [10.22.18.227]) by smtp.corp.redhat.com (Postfix) with ESMTP id 193AC60875; Thu, 29 Jul 2021 17:56:10 +0000 (UTC) From: Eduardo Habkost To: qemu-devel@nongnu.org Subject: [PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section Date: Thu, 29 Jul 2021 13:55:54 -0400 Message-Id: <20210729175554.686474-11-ehabkost@redhat.com> In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com> References: <20210729175554.686474-1-ehabkost@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=ehabkost@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Received-SPF: pass client-ip=170.10.133.124; envelope-from=ehabkost@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -34 X-Spam_score: -3.5 X-Spam_bar: --- X-Spam_report: (-3.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.717, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=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_P=2E_Berrang=C3=A9?= , Eduardo Habkost Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Add qom.rst to the QOM section of MAINTAINERS. Signed-off-by: Eduardo Habkost Reviewed-by: Peter Maydell --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index 42ac45c3e50..dc3f04242eb 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2651,6 +2651,7 @@ M: Paolo Bonzini R: Daniel P. Berrange R: Eduardo Habkost S: Supported +F: docs/devel/qom.rst F: docs/qdev-device-use.txt F: hw/core/qdev* F: hw/core/bus.c