From 6a0057aa22fedf4d6d39b749923e1d6046803fd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 24 Apr 2023 10:22:47 +0100 Subject: docs/devel: make a statement about includes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit While not explicitly disallowing header macro abuse (because that would make us hypocrites) lets at least address some things to think about. Signed-off-by: Alex Bennée Reviewed-by: Juan Quintela Message-Id: <20230424092249.58552-17-alex.bennee@linaro.org> --- docs/devel/style.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/style.rst b/docs/devel/style.rst index 68aa776..5bc6f2f 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -300,6 +300,20 @@ putting those into qemu/typedefs.h instead of including the header. Cyclic inclusion is forbidden. +Generative Includes +------------------- + +QEMU makes fairly extensive use of the macro pre-processor to +instantiate multiple similar functions. While such abuse of the macro +processor isn't discouraged it can make debugging and code navigation +harder. You should consider carefully if the same effect can be +achieved by making it easy for the compiler to constant fold or using +python scripting to generate grep friendly code. + +If you do use template header files they should be named with the +``.c.inc`` or ``.h.inc`` suffix to make it clear they are being +included for expansion. + C types ======= -- cgit v1.1 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/qom.rst | 2 ++ docs/devel/style.rst | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index 3e34b07..c923795 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 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 From ef46ae67ba9a785cf0cce58b5fc5a36ed3c6c7b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Mon, 24 Apr 2023 10:22:49 +0100 Subject: docs/style: call out the use of GUARD macros MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There use makes our code safer so we should mention them. Signed-off-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé Reviewed-by: Juan Quintela Reviewed-by: Vladimir Sementsov-Ogievskiy Message-Id: <20230424092249.58552-19-alex.bennee@linaro.org> --- docs/devel/style.rst | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/style.rst b/docs/devel/style.rst index ac2ce42..aa5e083 100644 --- a/docs/devel/style.rst +++ b/docs/devel/style.rst @@ -665,6 +665,60 @@ 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. +QEMU GUARD macros +================= + +QEMU provides a number of ``_GUARD`` macros intended to make the +handling of multiple exit paths easier. For example using +``QEMU_LOCK_GUARD`` to take a lock will ensure the lock is released on +exit from the function. + +.. code-block:: c + + static int my_critical_function(SomeState *s, void *data) + { + QEMU_LOCK_GUARD(&s->lock); + do_thing1(data); + if (check_state2(data)) { + return -1; + } + do_thing3(data); + return 0; + } + +will ensure s->lock is released however the function is exited. The +equivalent code without _GUARD macro makes us to carefully put +qemu_mutex_unlock() on all exit points: + +.. code-block:: c + + static int my_critical_function(SomeState *s, void *data) + { + qemu_mutex_lock(&s->lock); + do_thing1(data); + if (check_state2(data)) { + qemu_mutex_unlock(&s->lock); + return -1; + } + do_thing3(data); + qemu_mutex_unlock(&s->lock); + return 0; + } + +There are often ``WITH_`` forms of macros which more easily wrap +around a block inside a function. + +.. code-block:: c + + WITH_RCU_READ_LOCK_GUARD() { + QTAILQ_FOREACH_RCU(kid, &bus->children, sibling) { + err = do_the_thing(kid->child); + if (err < 0) { + return err; + } + } + } + Error handling and reporting ============================ -- cgit v1.1