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

[Laszlo Ersek]

On 09/01/15 21:47, Eric Blake wrote:
> On 08/28/2015 02:18 PM, Laszlo Ersek wrote:
>> Cc: Paolo Bonzini <address@hidden>
>> Cc: Gal Hammer <address@hidden>
>> Cc: Igor Mammedov <address@hidden>
>> Cc: "Michael S. Tsirkin" <address@hidden>
>> Signed-off-by: Laszlo Ersek <address@hidden>
>> ---
>>
>> Notes:
>>     This is based on the super long private email discussion we had two
>>     months ago, plus on the IRL discussion between Michael and myself @ the
>>     KVM Forum 2015.
>>
>>  docs/specs/vmgenid.txt | 343 
>> +++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 343 insertions(+)
>>  create mode 100644 docs/specs/vmgenid.txt
>>
> 
> Grammar review; I may miss some technical details.
> 
>> diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt
>> new file mode 100644
>> index 0000000..d4bf132
>> --- /dev/null
>> +++ b/docs/specs/vmgenid.txt
>> @@ -0,0 +1,343 @@
>> +Virtual Machine Generation ID Device
>> +====================================
> 
> Is it worth a preamble giving a specific copyright/license for this
> file? Without one, it inherits the default GPLv2+ from the top-level,
> and there are some people (although I'm not one) that worry that an
> independent implementation of a GPL'd spec must itself be GPL (that is,
> specifically choosing a looser license for the spec may make it more
> amenable to the OVMF folks).

(1) Like you, I don't believe that the copyright license covering a
specification would automatically cover the source code written based on
the specification.

(2) If necessary I (wearing my red fedora) could just relicense this
stuff on the spot, as copyright holder, if the greater edk2 community
had concerns. But, OVMF patches will not be necessary at all, because...
see (3).

(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?

> 
>> +
>> +The Microsoft specification entitled "Virtual Machine Generation ID",
>> +maintained at <http://go.microsoft.com/fwlink/?LinkId=260709>, defines an 
>> ACPI
>> +feature that allows the guest OSPM to recognize when it has been returned 
>> "to
>> +an earlier point in time", eg. by restoral from snapshot, or by incoming
> 
> s/eg./e.g./

Good catch!

> s/restoral/restoring/

Okay.

> 
>> +migration. Quoting the spec,
> 
> [I'm not sure that incoming migration is necessarily returning to an
> earlier point in time; although I can certainly see that being the case
> when repeatedly doing incoming migration from the same file]

Yeah, I thought the same. The MS spec uses the word "replay" or some
such IIRC. I kinda accepted that this part wasn't going to be 100%
precise. :)

> 
>> +
>> +    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. :)

> 
>> +    BIOS will expose a new ID. This is a 128-bit, cryptographically random
>> +    integer value identifier that will be different every time the virtual
>> +    machine executes from a different configuration file-such as executing 
>> from
>> +    a recovered snapshot, or executing after restoring from backup. [...]
>> +
>> +The document you are reading now extracts the requirements set forth by the
>> +VMGenID spec for hypervisors that intend to provide the feature, and 
>> describes
>> +QEMU's implementation. The design below targets both SeaBIOS and OVMF as
>> +compatible guest firmwares, without any changes to either of them.
>> +
> 
> Otherwise, I didn't spot any obvious wording problems.

Thanks for the review!
Laszlo

>