From d2ab529ec559df57dc142d24ea3ec0a629a23657 Mon Sep 17 00:00:00 2001 From: Ani Sinha Date: Fri, 30 Jun 2023 19:03:49 +0100 Subject: docs/devel: remind developers to run CI container pipeline when updating images MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When new dependencies and packages are added to containers, its important to run CI container generation pipelines on gitlab to make sure that there are no obvious conflicts between packages that are being added and those that are already present. Running CI container pipelines will make sure that there are no such breakages before we commit the change updating the containers. Add a line in the documentation reminding developers to run the pipeline before submitting the change. It will also ease the life of the maintainers. Signed-off-by: Ani Sinha Reviewed-by: Daniel P. Berrangé Message-Id: <20230506072012.10350-1-anisinha@redhat.com> Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Alex Bennée Message-Id: <20230630180423.558337-5-alex.bennee@linaro.org> --- docs/devel/testing.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index e85e26c..fb651ea 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -485,6 +485,12 @@ first to contribute the mapping to the ``libvirt-ci`` project: `CI `__ documentation page on how to trigger gitlab CI pipelines on your change. + * Please also trigger gitlab container generation pipelines on your change + for as many OS distros as practical to make sure that there are no + obvious breakages when adding the new pre-requisite. Please see + `CI `__ documentation + page on how to trigger gitlab CI pipelines on your change. + For enterprise distros that default to old, end-of-life versions of the Python runtime, QEMU uses a separate set of mappings that work with more recent versions. These can be found in ``tests/lcitool/mappings.yml``. -- cgit v1.1 From 8b4528c829a787533359de5550796e87070c9bba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 30 Jun 2023 19:04:07 +0100 Subject: docs/devel: add some front matter to the devel index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Give an overview of the most useful bits of the devel documentation to read depending on what the developer wants to do. Reviewed-by: Peter Maydell Reviewed-by: Richard Henderson Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Alex Bennée Message-Id: <20230630180423.558337-23-alex.bennee@linaro.org> --- docs/devel/index-process.rst | 2 ++ docs/devel/index-tcg.rst | 2 ++ docs/devel/index.rst | 24 ++++++++++++++++++++++-- docs/devel/tcg.rst | 2 ++ 4 files changed, 28 insertions(+), 2 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/index-process.rst b/docs/devel/index-process.rst index d50dd74..362f97e 100644 --- a/docs/devel/index-process.rst +++ b/docs/devel/index-process.rst @@ -1,3 +1,5 @@ +.. _development_process: + QEMU Community Processes ------------------------ diff --git a/docs/devel/index-tcg.rst b/docs/devel/index-tcg.rst index b44ff8b..a992844 100644 --- a/docs/devel/index-tcg.rst +++ b/docs/devel/index-tcg.rst @@ -1,3 +1,5 @@ +.. _tcg: + TCG Emulation ------------- diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 09cfb32..abf6045 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -2,10 +2,30 @@ Developer Information --------------------- -This section of the manual documents various parts of the internals of QEMU. -You only need to read it if you are interested in reading or +This section of the manual documents various parts of the internals of +QEMU. You only need to read it if you are interested in reading or modifying QEMU's source code. +QEMU is a large and mature project with a number of complex subsystems +that can be overwhelming to understand. The development documentation +is not comprehensive but hopefully presents enough to get you started. +If there are areas that are unclear please reach out either via the +IRC channel or mailing list and hopefully we can improve the +documentation for future developers. + +All developers will want to familiarise themselves with +:ref:`development_process` and how the community interacts. Please pay +particular attention to the :ref:`coding-style` and +:ref:`submitting-a-patch` sections to avoid common pitfalls. + +If you wish to implement a new hardware model you will want to read +through the :ref:`qom` documentation to understand how QEMU's object +model works. + +Those wishing to enhance or add new CPU emulation capabilities will +want to read our :ref:`tcg` documentation, especially the overview of +the :ref:`tcg_internals`. + .. toctree:: :maxdepth: 1 diff --git a/docs/devel/tcg.rst b/docs/devel/tcg.rst index b4096a1..2786f2f 100644 --- a/docs/devel/tcg.rst +++ b/docs/devel/tcg.rst @@ -1,3 +1,5 @@ +.. _tcg_internals: + ==================== Translator Internals ==================== -- cgit v1.1 From 307c0a4ac9c7acb7937ef663b2369f081ba94cd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Fri, 30 Jun 2023 19:04:10 +0100 Subject: docs/devel/qom.rst: Correct code style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per commit 067109a11c ("docs/devel: mention the spacing requirement for QOM"): For a storage structure the first declaration should always be called “parent_obj” and for a class structure the first member should always be called “parent_class” Adapt the QOM rST document accordingly. Reported-by: BALATON Zoltan Signed-off-by: Philippe Mathieu-Daudé Message-Id: <20230622101717.70468-1-philmd@linaro.org> Signed-off-by: Alex Bennée Message-Id: <20230630180423.558337-26-alex.bennee@linaro.org> --- docs/devel/qom.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index c923795..2828843 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -26,7 +26,7 @@ features: typedef DeviceClass MyDeviceClass; typedef struct MyDevice { - DeviceState parent; + DeviceState parent_obj; int reg0, reg1, reg2; } MyDevice; @@ -147,7 +147,7 @@ will also have a wrapper function to call it easily: typedef struct MyDeviceClass { - DeviceClass parent; + DeviceClass parent_class; void (*frobnicate) (MyDevice *obj); } MyDeviceClass; -- cgit v1.1 From da966a8a7ccb3811546bf141e17e928ea291256e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 30 Jun 2023 19:04:11 +0100 Subject: docs/devel: split qom-api reference into new file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lets try and keep the overview of the sub-system digestible by splitting the core API stuff into a separate file. As QOM and QDEV work together we should also try and enumerate the qdev_ functions. Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Alex Bennée Message-Id: <20230630180423.558337-27-alex.bennee@linaro.org> --- docs/devel/index-api.rst | 2 ++ docs/devel/qdev-api.rst | 7 +++++++ docs/devel/qom-api.rst | 9 +++++++++ docs/devel/qom.rst | 3 ++- 4 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 docs/devel/qdev-api.rst create mode 100644 docs/devel/qom-api.rst (limited to 'docs/devel') diff --git a/docs/devel/index-api.rst b/docs/devel/index-api.rst index 7108821..539ad29 100644 --- a/docs/devel/index-api.rst +++ b/docs/devel/index-api.rst @@ -11,5 +11,7 @@ generated from in-code annotations to function prototypes. loads-stores memory modules + qom-api + qdev-api ui zoned-storage diff --git a/docs/devel/qdev-api.rst b/docs/devel/qdev-api.rst new file mode 100644 index 0000000..3f35eea --- /dev/null +++ b/docs/devel/qdev-api.rst @@ -0,0 +1,7 @@ +.. _qdev-api: + +================================ +QEMU Device (qdev) API Reference +================================ + +.. kernel-doc:: include/hw/qdev-core.h diff --git a/docs/devel/qom-api.rst b/docs/devel/qom-api.rst new file mode 100644 index 0000000..ed1f17e --- /dev/null +++ b/docs/devel/qom-api.rst @@ -0,0 +1,9 @@ +.. _qom-api: + +===================================== +QEMU Object Model (QOM) API Reference +===================================== + +This is the complete API documentation for :ref:`qom`. + +.. kernel-doc:: include/qom/object.h diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 2828843..c342ce1 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -387,4 +387,5 @@ OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: API Reference ------------- -.. kernel-doc:: include/qom/object.h +See the :ref:`QOM API` and :ref:`QDEV API` +documents for the complete API description. -- cgit v1.1 From 43398409ce1a7fa83856f6141204aa103f0fe72c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 30 Jun 2023 19:04:12 +0100 Subject: docs/devel: introduce some key concepts for QOM development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Philippe Mathieu-Daudé Signed-off-by: Alex Bennée Message-Id: <20230630180423.558337-28-alex.bennee@linaro.org> --- docs/devel/qom.rst | 58 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 6 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index c342ce1..0b50642 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` and :ref:`QDEV API` documents for the complete API description. -- cgit v1.1