Re: [Qemu-devel] [PATCH 17/22] qidl: add documentation

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2927 bytes --]

On 09/21/2012 08:07 AM, Michael Roth wrote:
> Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
> ---
>  docs/qidl.txt |  347 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 347 insertions(+)
>  create mode 100644 docs/qidl.txt

> +Specifying What/How State Gets Saved
> +---------------------------------

Should the --- match the header length in the previous line?

> +
> +By default, QIDL saves every field in a structure it sees.  This provides
> +maximum correctness by default.  However, device structures generally contain
> +state that reflects state that is in someway duplicated or not guest visible.

s/someway/some way/

> +This more often that not reflects design implementation details.

s/that/than/

> +
> +Since design implementation details change over time, saving this state makes
> +compatibility hard to maintain. The proper solution is to use an intermediate
> +protocol to handle cross-version compatibility (for instance, a QIDL-aware
> +implementation of VMState). But we can reduce churn and streamline the
> +serialization/deserialization process by explicitly marking fields with
> +information that QIDL can use to determine whether or not a particular field
> +will be serialized. However, a serializable device implementation that fails to
> +serialize state that is required to fully guest state is a broken one, so to

s/fully guest/fully restore guest/

> +avoid that there are very strict rules about when this is allowed, and what
> +needs to be done to ensure that this does not impact correctness.
> +
> +There are also occassions where we want to specify *how* a field is

s/occassions/occasions/

> +
> +It can be subtle whether a field is truly immutable.  A good example is a
> +*QEMUTimer*.  Timer's will usually have their timeout modified with a call to

s/Timer's/Timers/

> +
> +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/

> +When reviewing the use of the broken marker, the following things should be
> +considered:
> +
> + 1. What are the ramifications of not sending this data field?
> +
> + 2. If the not sending this data field can cause data corruption or very poor

s/the not/not/

> +    behavior within the guest, the broken marker is not appropriate to use.
> +
> + 3. Assigning a default value to a field can also be used to fix a broken field
> +    without significantly impacting live migration compatibility.
> +
> +### qElsewhere fields
> +
> +In some cases state is saved-off when serializing a seperate device

s/seperate/separate/

-- 
Eric Blake   eblake@redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 617 bytes --]