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

[Eric Blake]

On 08/14/2012 10:27 AM, Michael Roth wrote:
> Signed-off-by: Michael Roth <address@hidden>
> ---
>  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   address@hidden    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature