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

[Michael Roth <mdroth@linux.vnet.ibm.com>]

On Tue, Aug 14, 2012 at 08:41:56PM +0100, Peter Maydell wrote:
> On 14 August 2012 17:27, Michael Roth <mdroth@linux.vnet.ibm.com> wrote:
> >
> > Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> > ---
> >  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.

Some kind of inline/embedded input format, or external (like QAPI
schemas)?

In terms of the ugliness of things, Anthony suggested we re-introduce
the simpler form of the annotations by doing something like:

#define _immutable QIDL(immutable)

as syntactic sugar for the more commonly used annotations/macros. This
can all be done in qidl.h, transparently to the parser (thanks to the
fact that we pass the code through the preprocessor prior to parsing).
There's also a few things we can do to replace the QIDL_START/QIDL_END
pairs with a single indicator.

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

QIDL handles properties, and could possibly be used to generate some QOM
boilerplate. We can get as creative as need be really, it's just that
properties/serialization were the primary/initial use-cases.

> 
> -- PMM
>