[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 17/18] docs/devel: mention the spacing requirement for QOM
From: |
Alex Bennée |
Subject: |
[PATCH 17/18] docs/devel: mention the spacing requirement for QOM |
Date: |
Mon, 24 Apr 2023 10:22:48 +0100 |
We have a more complete document on QOM but we should at least mention
the style requirements in the style guide.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Cc: Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Message-Id: <20230420155723.1711048-9-alex.bennee@linaro.org>
---
vppr:
- use Mark's formulation, briefly mention property separation.
---
docs/devel/qom.rst | 2 ++
docs/devel/style.rst | 40 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 42 insertions(+)
diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 3e34b07c98..c9237950d0 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -1,3 +1,5 @@
+.. _qom:
+
===========================
The QEMU Object Model (QOM)
===========================
diff --git a/docs/devel/style.rst b/docs/devel/style.rst
index 5bc6f2f095..e9fce0fc69 100644
--- a/docs/devel/style.rst
+++ b/docs/devel/style.rst
@@ -628,6 +628,46 @@ are still some caveats to beware of
QEMU Specific Idioms
********************
+QEMU Object Model Declarations
+==============================
+
+QEMU Object Model Declarations
+==============================
+
+The QEMU Object Model (QOM) provides a framework for handling objects
+in the base C language. The first declaration of a storage or class
+structure should always be the parent and leave a visual space between
+that declaration and the new code. It is also useful to separate
+backing for properties (options driven by the user) and internal state
+to make navigation easier.
+
+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" as below:
+
+.. code-block:: c
+
+ struct MyDeviceState {
+ DeviceState parent_obj;
+
+ /* Properties */
+ int prop_a;
+ char *prop_b;
+ /* Other stuff */
+ int internal_state;
+ };
+
+ struct MyDeviceClass {
+ DeviceClass parent_class;
+
+ void (*new_fn1)(void);
+ bool (*new_fn2)(CPUState *);
+ };
+
+Note that there is no need to provide typedefs for QOM structures
+since these are generated automatically by the QOM declaration macros.
+See :ref:`qom` for more details.
+
Error handling and reporting
============================
--
2.39.2
- [PATCH 01/18] tests/requirements.txt: bump up avocado-framework version to 101.0, (continued)
- [PATCH 01/18] tests/requirements.txt: bump up avocado-framework version to 101.0, Alex Bennée, 2023/04/24
- [PATCH 04/18] gitlab-ci: Avoid to re-run "configure" in the device-crash-test jobs, Alex Bennée, 2023/04/24
- [PATCH 02/18] tests/avocado: use the new snapshots for testing, Alex Bennée, 2023/04/24
- [PATCH 08/18] tests/avocado: Make ssh_command_output_contains() globally available, Alex Bennée, 2023/04/24
- [PATCH 03/18] tests/avocado: Add set of boot tests on SBSA-ref, Alex Bennée, 2023/04/24
- [PATCH 07/18] .gitlab-ci.d/cirrus: Drop the CI job for compiling with FreeBSD 12, Alex Bennée, 2023/04/24
- [PATCH 09/18] tests/avocado/machine_aspeed: Fix the broken ast2[56]00_evb_sdk tests, Alex Bennée, 2023/04/24
- [PATCH 11/18] avocado_qemu/__init__.py: factor out the qemu-img finding, Alex Bennée, 2023/04/24
- [PATCH 10/18] MAINTAINERS: Cover tests/avocado/machine_aspeed.py, Alex Bennée, 2023/04/24
- [PATCH 17/18] docs/devel: mention the spacing requirement for QOM,
Alex Bennée <=
- [PATCH 06/18] qemu-options: finesse the recommendations around -blockdev, Alex Bennée, 2023/04/24
- [PATCH 14/18] qemu-options.hx: Update descriptions of memory options for NUMA node, Alex Bennée, 2023/04/24
- [PATCH 15/18] docs/system: remove excessive punctuation from guest-loader docs, Alex Bennée, 2023/04/24
- [PATCH 05/18] scripts/device-crash-test: Add a parameter to run with TCG only, Alex Bennée, 2023/04/24
- [PATCH 12/18] tests/avocado/tuxrun_baselines.py: improve code coverage for ppc64, Alex Bennée, 2023/04/24
- [PATCH 13/18] tests/tcg: limit the scope of the plugin tests, Alex Bennée, 2023/04/24
- [PATCH 16/18] docs/devel: make a statement about includes, Alex Bennée, 2023/04/24
- [PATCH 18/18] docs/style: call out the use of GUARD macros, Alex Bennée, 2023/04/24