| Message ID | 20230424092249.58552-18-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | testing/next: avocado, docs (pre-PR) | expand |
On 24/04/2023 10:22, Alex Bennée wrote: > 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 > +============================== Accidental repetition here :) > +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 > ============================ Otherwise: Reviewed-by: Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk> ATB, Mark.
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 ============================