[V9,1/3] docs: vm generation id device's description

Signed-off-by: Gal Hammer <ghammer@redhat.com>

---
 docs/specs/vmgenid.txt | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 docs/specs/vmgenid.txt

On 12/09/2014 09:14 AM, Gal Hammer wrote:
> Signed-off-by: Gal Hammer <ghammer@redhat.com>
> 
> ---
>  docs/specs/vmgenid.txt | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 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..9a09d11
> --- /dev/null
> +++ b/docs/specs/vmgenid.txt
> @@ -0,0 +1,27 @@
> +VIRTUAL MACHINE GENERATION ID

Just because we aren't consistent doesn't mean that new files can get
away with not listing a license/copyright notice.  Check some of the
other recent doc additions for ideas on how to do it concisely.

> +=============================
> +
> +The VM generation ID (vmgenid) device is an emulated device which
> +expose a 128-bit, cryptographically random, integer value identifier.

s/expose/exposes/

> +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).
> +
> +Specs is on the web at: http://go.microsoft.com/fwlink/?LinkId=260709

s/Specs is/This is specified/

> +
> +---
> +
> +The vmgenid device is a sysbus device with the following ACPI ID:
> +"QEMU0002".
> +
> +The device adds a "vmgenid.uuid" property, which can be modifed using

s/modifed/modified/

> +the -global command line argument or the QMP interface.
> +
> +The device uses a fixed memory resource: 0xfedf0000-0xfedf0003. The

What endianness is the memory resource? Is 4 bytes sufficient, or should
it be 8 bytes because it holds a pointer?  Or is the size dependent on
the guest hardware?

> +guest is expected to write the physical address of the GUID's buffer
> +to that memory resource. This allows the device to modify the GUID if
> +requested by the management application.

What endianness is the GUID buffer?

> +
> +According to the specification, any change to the GUID executes an
> +ACPI notification. The vmgenid device triggers the GPE._E00 which
> +executes the ACPI Notify operation.
>

----- Original Message -----
> From: "Eric Blake" <eblake@redhat.com>
> To: "Gal Hammer" <ghammer@redhat.com>, qemu-devel@nongnu.org
> Sent: Tuesday, December 9, 2014 7:50:07 PM
> Subject: Re: [Qemu-devel] [PATCH V9 1/3] docs: vm generation id device's	description
> 
> On 12/09/2014 09:14 AM, Gal Hammer wrote:
> > Signed-off-by: Gal Hammer <ghammer@redhat.com>
> > 
> > ---
> >  docs/specs/vmgenid.txt | 27 +++++++++++++++++++++++++++
> >  1 file changed, 27 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..9a09d11
> > --- /dev/null
> > +++ b/docs/specs/vmgenid.txt
> > @@ -0,0 +1,27 @@
> > +VIRTUAL MACHINE GENERATION ID
> 
> Just because we aren't consistent doesn't mean that new files can get
> away with not listing a license/copyright notice.  Check some of the
> other recent doc additions for ideas on how to do it concisely.

Most of the files in the docs/specs doesn't have a legal notice so I missed it. Fixed.

> 
> > +=============================
> > +
> > +The VM generation ID (vmgenid) device is an emulated device which
> > +expose a 128-bit, cryptographically random, integer value identifier.
> 
> s/expose/exposes/
> 
> > +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).
> > +
> > +Specs is on the web at: http://go.microsoft.com/fwlink/?LinkId=260709
> 
> s/Specs is/This is specified/
> 
> > +
> > +---
> > +
> > +The vmgenid device is a sysbus device with the following ACPI ID:
> > +"QEMU0002".
> > +
> > +The device adds a "vmgenid.uuid" property, which can be modifed using
> 
> s/modifed/modified/

Fixed the typos. Thanks.

> > +the -global command line argument or the QMP interface.
> > +
> > +The device uses a fixed memory resource: 0xfedf0000-0xfedf0003. The
> 
> What endianness is the memory resource? Is 4 bytes sufficient, or should
> it be 8 bytes because it holds a pointer?  Or is the size dependent on
> the guest hardware?

Current implementation allocates the GUID's buffer in a 32-bit address range so the device uses 4 LE bytes.

> > +guest is expected to write the physical address of the GUID's buffer
> > +to that memory resource. This allows the device to modify the GUID if
> > +requested by the management application.
> 
> What endianness is the GUID buffer?

The spec say nothing about it. I assumed it is LE.

> > +
> > +According to the specification, any change to the GUID executes an
> > +ACPI notification. The vmgenid device triggers the GPE._E00 which
> > +executes the ACPI Notify operation.
> > 
> 
> --
> Eric Blake   eblake redhat com    +1-919-301-3266
> Libvirt virtualization library http://libvirt.org
> 
> 

Thanks,

    Gal.