On 09/21/2012 08:07 AM, Michael Roth wrote: > Signed-off-by: Michael Roth <mdr...@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 ebl...@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
