[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v4 27/38] docs/devel: introduce some key concepts for QOM develop
From: |
Alex Bennée |
Subject: |
[PATCH v4 27/38] docs/devel: introduce some key concepts for QOM development |
Date: |
Fri, 30 Jun 2023 19:04:12 +0100 |
Using QOM correctly is increasingly important to maintaining a modern
code base. However the current documentation skips some important
concepts before launching into a simple example. Lets:
- at least mention properties
- mention TYPE_OBJECT and TYPE_DEVICE
- talk about why we have realize/unrealize
- mention the QOM tree
- lightly re-arrange the order we mention things
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-Id: <20230619171437.357374-6-alex.bennee@linaro.org>
---
v3
- moved around as per Paolo's review
---
docs/devel/qom.rst | 58 +++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 52 insertions(+), 6 deletions(-)
diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index c342ce18e3..0b506426d7 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -13,6 +13,24 @@ features:
- System for dynamically registering types
- Support for single-inheritance of types
- Multiple inheritance of stateless interfaces
+- Mapping internal members to publicly exposed properties
+
+The root object class is TYPE_OBJECT which provides for the basic
+object methods.
+
+The QOM tree
+============
+
+The QOM tree is a composition tree which represents all of the objects
+that make up a QEMU "machine". You can view this tree by running
+``info qom-tree`` in the :ref:`QEMU monitor`. It will contain both
+objects created by the machine itself as well those created due to
+user configuration.
+
+Creating a QOM class
+====================
+
+A simple minimal device implementation may look something like bellow:
.. code-block:: c
:caption: Creating a minimal type
@@ -48,6 +66,12 @@ 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.
+The TYPE_DEVICE class is the parent class for all modern devices
+implemented in QEMU and adds some specific methods to handle QEMU
+device model. This includes managing the lifetime of devices from
+creation through to when they become visible to the guest and
+eventually unrealized.
+
Alternatively several static types could be registered using helper macro
DEFINE_TYPES()
@@ -98,7 +122,7 @@ when the object is needed.
module_obj(TYPE_MY_DEVICE);
Class Initialization
-====================
+--------------------
Before an object is initialized, the class for the object must be
initialized. There is only one class object for all instance objects
@@ -168,7 +192,7 @@ will also have a wrapper function to call it easily:
}
Interfaces
-==========
+----------
Interfaces allow a limited form of multiple inheritance. Instances are
similar to normal types except for the fact that are only defined by
@@ -182,7 +206,7 @@ an argument to a method on its corresponding
SomethingIfClass, or to
dynamically cast it to an object that implements the interface.
Methods
-=======
+-------
A *method* is a function within the namespace scope of
a class. It usually operates on the object instance by passing it as a
@@ -275,8 +299,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.
+One example of such methods is ``DeviceClass.reset``. More examples
+can be found at :ref:`device-life-cycle`.
Standard type declaration and definition macros
===============================================
@@ -382,10 +406,32 @@ OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device,
MY_DEVICE, DEVICE)
+.. _device-life-cycle:
+
+Device Life-cycle
+=================
+
+As class initialisation cannot fail devices have an two additional
+methods to handle the creation of dynamic devices. The ``realize``
+function is called with ``Error **`` pointer which should be set if
+the device cannot complete its setup. Otherwise on successful
+completion of the ``realize`` method the device object is added to the
+QOM tree and made visible to the guest.
+
+The reverse function is ``unrealize`` and should be were clean-up
+code lives to tidy up after the system is done with the device.
+
+All devices can be instantiated by C code, however only some can
+created dynamically via the command line or monitor.
+Likewise only some can be unplugged after creation and need an
+explicit ``unrealize`` implementation. This is determined by the
+``user_creatable`` variable in the root ``DeviceClass`` structure.
+Devices can only be unplugged if their ``parent_bus`` has a registered
+``HotplugHandler``.
API Reference
--------------
+=============
See the :ref:`QOM API<qom-api>` and :ref:`QDEV API<qdev-api>`
documents for the complete API description.
--
2.39.2
- [PATCH v4 11/38] tests/lcitool: update to latest version, (continued)
- [PATCH v4 11/38] tests/lcitool: update to latest version, Alex Bennée, 2023/06/30
- [PATCH v4 38/38] tests/tcg: Add a test for info proc mappings, Alex Bennée, 2023/06/30
- [PATCH v4 14/38] tests/lcitool: introduce qemu-minimal, Alex Bennée, 2023/06/30
- [PATCH v4 13/38] tests/lcitool: add an explicit gcc-native package, Alex Bennée, 2023/06/30
- [PATCH v4 30/38] gdbstub: clean-up vcont handling to avoid goto, Alex Bennée, 2023/06/30
- [PATCH v4 32/38] linux-user: Add "safe" parameter to do_guest_openat(), Alex Bennée, 2023/06/30
- [PATCH v4 20/38] plugins: fix memory leak while parsing options, Alex Bennée, 2023/06/30
- [PATCH v4 37/38] docs: Document security implications of debugging, Alex Bennée, 2023/06/30
- [PATCH v4 28/38] gdbstub: lightly refactor connection to avoid snprintf, Alex Bennée, 2023/06/30
- [PATCH v4 26/38] docs/devel: split qom-api reference into new file, Alex Bennée, 2023/06/30
- [PATCH v4 27/38] docs/devel: introduce some key concepts for QOM development,
Alex Bennée <=
- [PATCH v4 21/38] plugins: update lockstep to use g_memdup2, Alex Bennée, 2023/06/30
- [PATCH v4 36/38] gdbstub: Add support for info proc mappings, Alex Bennée, 2023/06/30
- [PATCH v4 33/38] linux-user: Emulate /proc/self/smaps, Alex Bennée, 2023/06/30
- [PATCH v4 34/38] gdbstub: Expose gdb_get_process() and gdb_get_first_cpu_in_process(), Alex Bennée, 2023/06/30
- [PATCH v4 31/38] linux-user: Expose do_guest_openat() and do_guest_readlink(), Alex Bennée, 2023/06/30
- [PATCH v4 16/38] tests/avocado: update firmware to enable sbsa-ref/max, Alex Bennée, 2023/06/30
- [PATCH v4 25/38] docs/devel/qom.rst: Correct code style, Alex Bennée, 2023/06/30
- [PATCH v4 29/38] gdbstub: Permit reverse step/break to provide stop response, Alex Bennée, 2023/06/30
- [PATCH v4 17/38] tests/avocado: Make the test_arm_bpim2u_gmac test more reliable, Alex Bennée, 2023/06/30
- [PATCH v4 35/38] gdbstub: Report the actual qemu-user pid, Alex Bennée, 2023/06/30