Re: [Qemu-devel] [RFC] docs: describe QEMU's VMGenID design

[Eric Blake]

On 09/01/2015 04:05 PM, Laszlo Ersek wrote:

> 
> (3) I couldn't decide if this text file should go under docs/, or
> docs/specs. The tricky fact about this specific vmgenid design is that
> the guest will "know" about it, but no *specific* guest code needs to be
> written for it.
> 
> First, the ACPI linker/loader clients in both SeaBIOS and OVMF should
> "just work" (without any changes). In that sense the *specific* design
> here is not guest ABI. The ACPI linker/loader is guest ABI instead; this
> design is just a "clever" application of the ACPI linker/loader. (I can
> call it clever, it's only in part my idea. :))
> 
> Second, guest operating systems will need drivers for this device
> (obviously), but those drivers are ACPI based, and will have to consult
> the Microsoft spec only, not this file.
> 
> Given the above two (ie. neither guest firmare developers nor guest OS
> developers need read this text file), I'd say this is not guest ABI. It
> is (detailed) documentation / specification for some QEMU internals.
> 
> Do you think the file should go under docs/, not docs/specs?

I don't know if there is a strong explanation for why we have the
separation, but given your argument, docs/ (all qemu-related
documentation that has no more specific location) indeed sounds slightly
better than docs/specs/ (files that independent implementations must pay
attention to).

>>> +migration. Quoting the spec,
>>

>>> +    The virtual machine generation ID is a feature whereby the virtual 
>>> machines
>>
>> s/machines/machine's/ [oh wait, you're quoting Microsoft's poor grammar]
> 
> Yep :) I noticed that. I resisted the urge to fix it. :)

A pedantic editor might write "machines [sic] BIOS", but that just calls
attention to the blunder with an intent to appear snobbish.  You could
possibly get away with "whereby the virtual [machine's] BIOS" to make
the sentence grammatically correct while still marking your deviations
from the original, and without calling as much attention to the mistake,
but even that feels overboard.  So I agree with your decision to leave
it alone (we've already called enough attention to it in this thread
without needing any further time spent on it).

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

signature.asc
Description: OpenPGP digital signature