On 08/14/2012 10:27 AM, Michael Roth 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 > > + > +For the rest, of the document, the following simple device will be used as an
s/rest,/rest/
> +
> +Do not include any function declarations in this header file as QIDL does not
> +understand function declarations.
Can QIDL be taught to ignore portions of a file, and stick function
declarations in those portions?
> +### Derived Fields
> +
> +If a field is set based on some other field in the device's structure, then
> its
> +value is derived. Since this is effectively duplicate state, we can avoid
> +sending it and then recompute it when we need to. Derived state requires a
> bit
> +more handling that immutable state.
s/that/than/
> +
> +In our *SerialDevice* example, our *int_pending* flag is really derived from
> +two pieces of state. It is set based on whether interrupts are enabled in
> the
> +*ier* register and whether there is *THRE* flag is not set in the *lsr*
s/there is/the/
> +register.
> +
> +To mark a field as derived, use the **derived** marker. To update our
> +example, we would do:
> +
> + 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 _derived int_pending; // whether we have a pending queued
> interrupt
> + CharDriverState *chr QIDL(immutable);
Why is it marked QIDL(immutable) but only _derived? Wouldn't
QIDL(derived) be more consistent?
> +### Broken State
> +
> +QEMU does migration with a lot of devices today. When applying this
> methodology
> +to these devices, one will quickly discover that there are a lot of fields
> that
> +are not being saved today that are not derived or immutable state.
> +
> +These are all bugs. It just so happens that these bugs are usually not very
> +serious. In many cases, they cause small functionality glitches that so far
> +have not created any problems.
> +
> +Consider our *SerialDevice* example. In QEMU's real *SerialState* device,
> the
> +*thr* register is not saved yet we have not marked it immutable or derived.
s/saved/saved,/
> +
> +The idea behind the broken marker is that we can convert a large number of
> +devices without breaking migration compatibility, and then institute a flag
> day
> +where we go through and remove broken markers en-mass.
s/en-mass/en masse/
> +
> +Below is an update of our example to reflect our real life serial device:
> +
> + QIDL_START(SerialDevice, state)
> + typedef struct SerialDevice {
> + SysBusDevice parent;
> +
> + uint8_t thr QIDL(broken); // transmit holding register
> + uint8_t lsr; // line status register
> + uint8_t ier; // interrupt enable register
> +
> + int _derived int_pending; // whether we have a pending queued
> interrupt
> + CharDriverState _immutable *chr;
Now you've changed the example; before it used QIDL(immutable).
> +Variable Sized, Fixed Capacity Arrays
> +-------------------------------------
> +
> +Sometimes it's desirable to have a variable sized array. QIDL currently
> supported
s/supported/supports/
--
Eric Blake ebl...@redhat.com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
