Re: [Qemu-devel] [PATCH 16/20] qidl: Add documentation

[Peter Maydell]

On 14 August 2012 17:27, Michael Roth <address@hidden> wrote:
>
> Signed-off-by: Michael Roth <address@hidden>
> ---
>  docs/qidl.txt |  343 
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 343 insertions(+)
>  create mode 100644 docs/qidl.txt
>
> diff --git a/docs/qidl.txt b/docs/qidl.txt
> new file mode 100644
> index 0000000..19976d9
> --- /dev/null
> +++ b/docs/qidl.txt
> @@ -0,0 +1,343 @@
> +How to Serialize Device State with QIDL
> +======================================
> +
> +This document describes how to implement save/restore of a device in QEMU 
> using
> +the QIDL compiler.  The QIDL compiler makes it easier to support live
> +migration in devices by converging the serialization description with the
> +device type declaration.  It has the following features:
> +
> + 1. Single description of device state and how to serialize
> +
> + 2. Fully inclusive serialization description--fields that aren't serialized
> +    are explicitly marked as such including the reason why.
> +
> + 3. Optimized for the common case.  Even without any special annotations,
> +    many devices will Just Work out of the box.
> +
> + 4. Build time schema definition.  Since QIDL runs at build time, we have 
> full
> +    access to the schema during the build which means we can fail the build 
> if
> +    the schema breaks.
> +
> +For the rest, of the document, the following simple device will be used as an
> +example.
> +
> +    typedef struct SerialDevice {
> +        SysBusDevice parent;
> +
> +        uint8_t thr;            // transmit holding register
> +        uint8_t lsr;            // line status register
> +        uint8_t ier;            // interrupt enable register
> +
> +        int int_pending;        // whether we have a pending queued interrupt
> +        CharDriverState *chr;   // backend
> +    } SerialDevice;

"//" style comments are a breach of the QEMU coding style so we shouldn't
be using them in documentation examples...

> +
> +In our *SerialDevice* example, the *CharDriverState* pointer reflects the 
> host
> +backend that we use to send serial output to the user.  This is only assigned
> +during device construction and never changes.  This means we can add an
> +**immutable** marker to it:
> +
> +    QIDL_START(SerialDevice, state)
> +    typedef struct SerialDevice {
> +        SysBusDevice parent;
> +
> +        uint8_t thr;            // transmit holding register
> +        uint8_t lsr;            // line status register
> +        uint8_t ier;            // interrupt enable register
> +
> +        int int_pending;        // whether we have a pending queued interrupt
> +        CharDriverState *chr QIDL(immutable);
> +    } SerialDevice;
> +    QIDL_END(SerialDevice)

I think it would be nicer to have a QIDL input format from which the structure
is generated as one of the outputs; that would avoid having to have some of
this ugly QIDL() markup.

We could also use this to autogenerate a lot of the QOM required boilerplate,
qdev Property arrays, etc etc.

-- PMM