Re: [PATCH 17/18] docs/devel: mention the spacing requirement for QOM

[Mark Cave-Ayland]

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.