From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:41287) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TFCSZ-000502-AW for qemu-devel@nongnu.org; Fri, 21 Sep 2012 19:16:36 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TFCSY-0006jW-4a for qemu-devel@nongnu.org; Fri, 21 Sep 2012 19:16:35 -0400 Received: from mx1.redhat.com ([209.132.183.28]:8518) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TFCSX-0006jS-S4 for qemu-devel@nongnu.org; Fri, 21 Sep 2012 19:16:34 -0400 Message-ID: <505CF54B.5060002@redhat.com> Date: Fri, 21 Sep 2012 17:16:27 -0600 From: Eric Blake MIME-Version: 1.0 References: <1348236465-23124-1-git-send-email-mdroth@linux.vnet.ibm.com> <1348236465-23124-18-git-send-email-mdroth@linux.vnet.ibm.com> In-Reply-To: <1348236465-23124-18-git-send-email-mdroth@linux.vnet.ibm.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------enig4E60772F166395A25F10E7F2" Subject: Re: [Qemu-devel] [PATCH 17/22] qidl: add documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Michael Roth Cc: blauwirbel@gmail.com, peter.maydell@linaro.org, aliguori@us.ibm.com, qemu-devel@nongnu.org This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enig4E60772F166395A25F10E7F2 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On 09/21/2012 08:07 AM, Michael Roth wrote: > Signed-off-by: Michael Roth > --- > 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 provi= des > +maximum correctness by default. However, device structures generally = contain > +state that reflects state that is in someway duplicated or not guest v= isible. 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 stat= e makes > +compatibility hard to maintain. The proper solution is to use an inter= mediate > +protocol to handle cross-version compatibility (for instance, a QIDL-a= ware > +implementation of VMState). But we can reduce churn and streamline the= > +serialization/deserialization process by explicitly marking fields wit= h > +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 i= s 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 derive= d from > +two pieces of state. It is set based on whether interrupts are enable= d 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 shou= ld 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 ve= ry 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 bro= ken field > + without significantly impacting live migration compatibility. > + > +### qElsewhere fields > + > +In some cases state is saved-off when serializing a seperate device s/seperate/separate/ --=20 Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --------------enig4E60772F166395A25F10E7F2 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Mozilla - http://www.enigmail.net/ iQEcBAEBCAAGBQJQXPVLAAoJEKeha0olJ0NqZoMH/0y/USFuLA82j9Fkt3hnNls8 f0ia+nQp2LaIOVTAOcnvpEncqK9Zucxo4S/9xCxyKdxO+4PyUAf/23P8gLZ9cYqw 6AQFioL0NgfTbuNVQi+r+7/GDqNoxCHd7kVFYPUhxaEh/to2kXJwiL7JBoZ1IKlE 417JiBP3jM+6JEXtD7Ix/f2FNmU/nZU2iyG0W4uhtZC8biSb15Got5laxrKT2vEf fHkA4a0u0p32XCu4dmCnysuTYwKILZr+E5rV6VWx9Yy++KIQtTLyvgfvlleMzzCy a4BEum1uMbv8UUC4HNxWzGq2BB4DErnetrR7ImrqSkJQCouRfC3wJZybJVh6PcI= =EnZl -----END PGP SIGNATURE----- --------------enig4E60772F166395A25F10E7F2--