On 14 August 2012 17:27, Michael Roth <mdr...@linux.vnet.ibm.com> wrote:
>
> Signed-off-by: Michael Roth <mdr...@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.
We could also use this to autogenerate a lot of the QOM required boilerplate,
qdev Property arrays, etc etc.
-- PMM
