From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([208.118.235.92]:47677) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T1MMh-0001Q8-6n for qemu-devel@nongnu.org; Tue, 14 Aug 2012 15:01:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1T1MMf-00016U-O5 for qemu-devel@nongnu.org; Tue, 14 Aug 2012 15:01:19 -0400 Received: from mx1.redhat.com ([209.132.183.28]:44525) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1T1MMf-00016O-Fa for qemu-devel@nongnu.org; Tue, 14 Aug 2012 15:01:17 -0400 Message-ID: <502AA075.5010409@redhat.com> Date: Tue, 14 Aug 2012 13:01:09 -0600 From: Eric Blake MIME-Version: 1.0 References: <1344961646-21194-1-git-send-email-mdroth@linux.vnet.ibm.com> <1344961646-21194-17-git-send-email-mdroth@linux.vnet.ibm.com> In-Reply-To: <1344961646-21194-17-git-send-email-mdroth@linux.vnet.ibm.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------enig69A009C46F1CC64AF8CB871B" Subject: Re: [Qemu-devel] [PATCH 16/20] qidl: Add documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Michael Roth Cc: blauwirbel@gmail.com, aliguori@us.ibm.com, qemu-devel@nongnu.org This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enig69A009C46F1CC64AF8CB871B Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable On 08/14/2012 10:27 AM, Michael Roth wrote: > Signed-off-by: Michael Roth > --- > docs/qidl.txt | 343 +++++++++++++++++++++++++++++++++++++++++++++++++= ++++++++ > 1 file changed, 343 insertions(+) > create mode 100644 docs/qidl.txt >=20 > + > +For the rest, of the document, the following simple device will be use= d as an s/rest,/rest/ > + > +Do not include any function declarations in this header file as QIDL d= oes 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 a= void > +sending it and then recompute it when we need to. Derived state requi= res a bit > +more handling that immutable state. s/that/than/ > + > +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/ > +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; > + =20 > + uint8_t thr; // transmit holding register > + uint8_t lsr; // line status register > + uint8_t ier; // interrupt enable register > + =20 > + 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 m= ethodology > +to these devices, one will quickly discover that there are a lot of fi= elds 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 no= t 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* dev= ice, the > +*thr* register is not saved yet we have not marked it immutable or der= ived. s/saved/saved,/ > + > +The idea behind the broken marker is that we can convert a large numbe= r 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 devi= ce: > + > + QIDL_START(SerialDevice, state) > + typedef struct SerialDevice { > + SysBusDevice parent; > + =20 > + uint8_t thr QIDL(broken); // transmit holding register > + uint8_t lsr; // line status register > + uint8_t ier; // interrupt enable register > + =20 > + 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 current= ly supported s/supported/supports/ --=20 Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --------------enig69A009C46F1CC64AF8CB871B 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://enigmail.mozdev.org/ iQEcBAEBCAAGBQJQKqB1AAoJEKeha0olJ0NqMeUH/1bs+Qj6yN8utT/iJuXAAMZd P4aq0c2aBN/0WNxVU+bqocCLKX7pTxHSta0GPq4RyjLIC9bl8t0waOjNC0H7AyYd mELWDk6N/FNBZrJiYarHEE3vhaSCr0aqfYY9ie/ypWFgZFtiuIuEcXzZIXw6OJt+ jaV56aBVJ4dgsKbx3cGG3XB9VqG4yE1HItmYgtIDUMWmdG/vtcsljKgdLZbti0Ch 9yOg6ZkbeypLE2rnw7BtrKQoVbzP/mtmBs5EiWoZtYfKY/YWLxvzKcDv+eeIveOZ EHrZpfS8j6hJefHIecx4obLj5zSzDcmExNPS/ewaJDD98JBYcko8t6wyc8GzkKg= =yFaz -----END PGP SIGNATURE----- --------------enig69A009C46F1CC64AF8CB871B--