[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH 17/22] qidl: add documentation
From: |
Eric Blake |
Subject: |
Re: [Qemu-devel] [PATCH 17/22] qidl: add documentation |
Date: |
Fri, 21 Sep 2012 17:16:27 -0600 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:15.0) Gecko/20120828 Thunderbird/15.0 |
On 09/21/2012 08:07 AM, Michael Roth wrote:
> Signed-off-by: Michael Roth <address@hidden>
> ---
> 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 address@hidden +1-919-301-3266
Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
- [Qemu-devel] [PATCH 08/22] qapi: add visitor interfaces for C arrays, (continued)
- [Qemu-devel] [PATCH 08/22] qapi: add visitor interfaces for C arrays, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 07/22] qapi: qapi_visit.py, support for visiting non-pointer/embedded structs, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 06/22] qapi: qapi_visit.py, support generating static functions, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 05/22] qapi: qapi_visit.py, support arrays and complex qapi definitions, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 11/22] qapi: qapi.py, make json parser more robust, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 10/22] qapi: QmpInputVisitor, implement array handling, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 13/22] qom-fuse: force single-threaded mode to avoid QMP races, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 12/22] qapi: add open-coded visitor for struct tm types, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 15/22] module additions for schema registration, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 17/22] qidl: add documentation, Michael Roth, 2012/09/21
- Re: [Qemu-devel] [PATCH 17/22] qidl: add documentation,
Eric Blake <=
- [Qemu-devel] [PATCH 14/22] qom-fuse: workaround for truncated properties > 4096, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 20/22] qidl: add QAPI-based code generator, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 22/22] qidl: unit tests and build infrastructure, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 21/22] qidl: qidl.h, definitions for qidl annotations, Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 19/22] qidl: add C parser (based on QC parser), Michael Roth, 2012/09/21
- [Qemu-devel] [PATCH 18/22] qidl: add lexer library (based on QC parser), Michael Roth, 2012/09/21