[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples
From: |
Eduardo Habkost |
Subject: |
[PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples |
Date: |
Thu, 29 Jul 2021 13:55:53 -0400 |
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 <ehabkost@redhat.com>
---
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 <typecasting>`.
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 <OBJECT_DECLARE>` 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
-----------------------
--
2.31.1
- [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level, (continued)
- [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 02/10] docs: qom: Use Sphinx cross references more often, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples,
Eduardo Habkost <=
- [PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples, Eduardo Habkost, 2021/07/29
- [PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section, Eduardo Habkost, 2021/07/29