From 067109a11c83e0b461d7a1a9b531b4c738323477 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 24 Apr 2023 10:22:48 +0100 Subject: docs/devel: mention the spacing requirement for QOM MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Juan Quintela Reviewed-by: Mark Cave-Ayland Message-Id: <20230424092249.58552-18-alex.bennee@linaro.org> --- docs/devel/style.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs/devel/style.rst') diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 5bc6f2f..ac2ce42 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -628,6 +628,43 @@ are still some caveats to beware of QEMU Specific Idioms ******************** +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 ============================ -- cgit v1.1