[v2,1/6] docs: vm generation id device's description

Commit Message

[e-mail] Jan. 16, 2017, 7:20 p.m. UTC

From: Ben Warren <[e-mail]>

Signed-off-by: Ben Warren <[e-mail]>
Cc: Gal Hammer <[e-mail]>
---
 docs/specs/vmgenid.txt | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
 create mode 100644 docs/specs/vmgenid.txt

Comments

Eric Blake Jan. 16, 2017, 7:51 p.m. UTC | #1

On 01/16/2017 01:20 PM, [e-mail] wrote:
> From: Ben Warren <[e-mail]>

meta-comment: This message was sent with headers:
> Message-Id: <[e-mail]>
> In-Reply-To: <[e-mail]>
> References: <[e-mail]>
> In-Reply-To: <[e-mail]>
> References: <[e-mail]>

while your cover letter's actual headers included:
> Message-Id: <[e-mail]>

I don't know how you got your sending side to use two different sets of
In-Reply-To, but it breaks at least Thunderbird's abilities to rethread
the messages (thunderbird apparently only pays attention to the last
header, while only the first one would cause correct threading).


> 
> Signed-off-by: Ben Warren <[e-mail]>
> Cc: Gal Hammer <[e-mail]>

If you are basing this patch off of earlier work (for example, you
mentioned Igor's work), you may need additional S-o-b lines for work you
copied from the earlier versions.

> ---
>  docs/specs/vmgenid.txt | 38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>  create mode 100644 docs/specs/vmgenid.txt
> 
> diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt
> new file mode 100644
> index 0000000..afc1717
> --- /dev/null
> +++ b/docs/specs/vmgenid.txt
> @@ -0,0 +1,38 @@
> +VIRTUAL MACHINE GENERATION ID
> +=============================
> +
> +Copyright (C) 2016 Red Hat, Inc.

Claiming Red Hat copyright makes it sound like you are basing this off
an earlier version.  That is the correct thing to do if you indeed
copied something with Red Hat copyright, but seems weird if you wrote it
from scratch.

> +Copyright (C) 2016 Skyport Systems, Inc.

Do you want to claim 2017 as well?


> +
> +The vmgenid device is a sysbus device with the ACPI ID "QEMU_Gen_Counter_V1".
> +
> +The device has one properties, which can be set using the command line

s/properties/property/

> +argument or the QMP interface:
> + guid - sets the value of the GUID
> +For example:
> +QEMU  -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
> +

[e-mail] Jan. 16, 2017, 8:08 p.m. UTC | #2

> On Jan 16, 2017, at 11:51 AM, Eric Blake <[e-mail]> wrote:
> 
> On 01/16/2017 01:20 PM, [e-mail] <mailto:[e-mail]> wrote:
>> From: Ben Warren <[e-mail] <mailto:[e-mail]>>
> 
> meta-comment: This message was sent with headers:
>> Message-Id: <[e-mail] <mailto:[e-mail]>>
>> In-Reply-To: <[e-mail] <mailto:[e-mail]>>
>> References: <[e-mail] <mailto:[e-mail]>>
>> In-Reply-To: <[e-mail] <mailto:[e-mail]>>
>> References: <[e-mail] <mailto:[e-mail]>>
> 
> while your cover letter's actual headers included:
>> Message-Id: <[e-mail] <mailto:[e-mail]>>
> 
> I don't know how you got your sending side to use two different sets of
> In-Reply-To, but it breaks at least Thunderbird's abilities to rethread
> the messages (thunderbird apparently only pays attention to the last
> header, while only the first one would cause correct threading).
> 
Hmm, I created the patches using “git format-patch” with the —thread switch, then ‘git send-email’, which is usually a solid combination.  I’ll dry-run it next time to make sure things are threaded properly.  Sorry.
> 
>> 
>> Signed-off-by: Ben Warren <[e-mail] <mailto:[e-mail]>>
>> Cc: Gal Hammer <[e-mail] <mailto:[e-mail]>>
> 
> If you are basing this patch off of earlier work (for example, you
> mentioned Igor's work), you may need additional S-o-b lines for work you
> copied from the earlier versions.
> 
yes, I used a previous patch set as a baseline and want to make sure credit goes to whoever did the real work.  In this case, Gal Hammer was the original author, so I CC’d Him (or her) hoping to get an SOB.  Should that be handled out-of-band?
>> ---
>> docs/specs/vmgenid.txt | 38 ++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 38 insertions(+)
>> create mode 100644 docs/specs/vmgenid.txt
>> 
>> diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt
>> new file mode 100644
>> index 0000000..afc1717
>> --- /dev/null
>> +++ b/docs/specs/vmgenid.txt
>> @@ -0,0 +1,38 @@
>> +VIRTUAL MACHINE GENERATION ID
>> +=============================
>> +
>> +Copyright (C) 2016 Red Hat, Inc.
> 
> Claiming Red Hat copyright makes it sound like you are basing this off
> an earlier version.  That is the correct thing to do if you indeed
> copied something with Red Hat copyright, but seems weird if you wrote it
> from scratch.
Same as above, I reworked much of this document, but a great deal is not my original.  Guidance on the right way to do this is appreciated.
> 
>> +Copyright (C) 2016 Skyport Systems, Inc.
> 
> Do you want to claim 2017 as well?
> 
Good catch, I haven’t touched the file this year, but that makes sense.
> 
>> +
>> +The vmgenid device is a sysbus device with the ACPI ID "QEMU_Gen_Counter_V1".
>> +
>> +The device has one properties, which can be set using the command line
> 
> s/properties/property/
Will fix.
> 
>> +argument or the QMP interface:
>> + guid - sets the value of the GUID
>> +For example:
>> +QEMU  -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
>> +
> 
> -- 
> Eric Blake   eblake redhat com    [phone]
> Libvirt virtualization library http://libvirt.org <http://libvirt.org/>

Eric Blake Jan. 16, 2017, 9:20 p.m. UTC | #3

On 01/16/2017 02:08 PM, Ben Warren wrote:

>>>
>>> Signed-off-by: Ben Warren <[e-mail] <mailto:[e-mail]>>
>>> Cc: Gal Hammer <[e-mail] <mailto:[e-mail]>>
>>
>> If you are basing this patch off of earlier work (for example, you
>> mentioned Igor's work), you may need additional S-o-b lines for work you
>> copied from the earlier versions.
>>
> yes, I used a previous patch set as a baseline and want to make sure credit goes to whoever did the real work.  In this case, Gal Hammer was the original author, so I CC’d Him (or her) hoping to get an SOB.  Should that be handled out-of-band?

If Gal already had S-o-b on the version you started with, then the most
common two approaches are:

1) Use Gal's commit message verbatim, including his S-o-b, then add
another paragraph about your changes, with your S-o-b.

2) Rewrite the commit message, but state that you are basing on Gal's
work, then list S-o-b for both content contributors next to one another.

Patch

diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt
new file mode 100644
index 0000000..afc1717
--- /dev/null
+++ b/docs/specs/vmgenid.txt
@@ -0,0 +1,38 @@ 
+VIRTUAL MACHINE GENERATION ID
+=============================
+
+Copyright (C) 2016 Red Hat, Inc.
+Copyright (C) 2016 Skyport Systems, Inc.
+
+This work is licensed under the terms of the GNU GPL, version 2 or later.
+See the COPYING file in the top-level directory.
+
+===
+
+The VM generation ID (vmgenid) device is an emulated device which
+exposes a 128-bit, cryptographically random, integer value identifier.
+This allows management applications (e.g. libvirt) to notify the guest
+operating system when the virtual machine is executed with a different
+configuration (e.g. snapshot execution or creation from a template).
+
+This is specified on the web at: http://go.microsoft.com/fwlink/?LinkId=260709
+
+---
+
+The vmgenid device is a sysbus device with the ACPI ID "QEMU_Gen_Counter_V1".
+
+The device has one properties, which can be set using the command line
+argument or the QMP interface:
+ guid - sets the value of the GUID
+For example:
+QEMU  -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
+
+Or to change guid in runtime use:
+ set-vm-generation-id guid="124e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
+
+According to the specification, any change to the GUID executes an
+ACPI notification. The vmgenid device triggers the \_GPE._E00 handler
+which executes the ACPI Notify operation.
+
+Although not specified in Microsoft's document, it is assumed that the
+device is expected to use the little-endian system.