From: "Philippe Mathieu-Daudé" <philmd@linaro.org>
To: Peter Maydell <peter.maydell@linaro.org>, qemu-devel@nongnu.org
Cc: Ani Sinha <anisinha@redhat.com>
Subject: Re: [PATCH 8/8] docs/specs/vmgenid: Convert to rST
Date: Tue, 31 Oct 2023 16:43:49 +0100 [thread overview]
Message-ID: <878a78c4-a07c-04bb-7618-5fb5c2347420@linaro.org> (raw)
In-Reply-To: <20230927151205.70930-9-peter.maydell@linaro.org>
On 27/9/23 17:12, Peter Maydell wrote:
> Convert docs/specs/vmgenid.txt to rST format.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> MAINTAINERS | 2 +-
> docs/specs/index.rst | 1 +
> docs/specs/vmgenid.rst | 246 +++++++++++++++++++++++++++++++++++++++++
> docs/specs/vmgenid.txt | 245 ----------------------------------------
> 4 files changed, 248 insertions(+), 246 deletions(-)
> create mode 100644 docs/specs/vmgenid.rst
> delete mode 100644 docs/specs/vmgenid.txt
Cc'ing Ani.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 23ee617acaf..d2338e3beb6 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2369,7 +2369,7 @@ S: Orphan
> R: Ani Sinha <ani@anisinha.ca>
> F: hw/acpi/vmgenid.c
> F: include/hw/acpi/vmgenid.h
> -F: docs/specs/vmgenid.txt
> +F: docs/specs/vmgenid.rst
> F: tests/qtest/vmgenid-test.c
>
> LED
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index 7a56ccb2155..b3f482b0aa5 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -31,3 +31,4 @@ guest hardware that is specific to QEMU.
> standard-vga
> virt-ctlr
> vmcoreinfo
> + vmgenid
> diff --git a/docs/specs/vmgenid.rst b/docs/specs/vmgenid.rst
> new file mode 100644
> index 00000000000..9a3cefcd828
> --- /dev/null
> +++ b/docs/specs/vmgenid.rst
> @@ -0,0 +1,246 @@
> +Virtual Machine Generation ID Device
> +====================================
> +
> +..
> + Copyright (C) 2016 Red Hat, Inc.
> + Copyright (C) 2017 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,
> +referred to as a Globally Unique Identifier, or GUID.
> +
> +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). The
> +guest operating system notices the change, and is then able to react as
> +appropriate by marking its copies of distributed databases as dirty,
> +re-initializing its random number generator etc.
> +
> +
> +Requirements
> +------------
> +
> +These requirements are extracted from the "How to implement virtual machine
> +generation ID support in a virtualization platform" section of
> +`the Microsoft Virtual Machine Generation ID specification
> +<http://go.microsoft.com/fwlink/?LinkId=260709>`_ dated August 1, 2012.
> +
> +- **R1a** The generation ID shall live in an 8-byte aligned buffer.
> +
> +- **R1b** The buffer holding the generation ID shall be in guest RAM,
> + ROM, or device MMIO range.
> +
> +- **R1c** The buffer holding the generation ID shall be kept separate from
> + areas used by the operating system.
> +
> +- **R1d** The buffer shall not be covered by an AddressRangeMemory or
> + AddressRangeACPI entry in the E820 or UEFI memory map.
> +
> +- **R1e** The generation ID shall not live in a page frame that could be
> + mapped with caching disabled. (In other words, regardless of whether the
> + generation ID lives in RAM, ROM or MMIO, it shall only be mapped as
> + cacheable.)
> +
> +- **R2** to **R5** [These AML requirements are isolated well enough in the
> + Microsoft specification for us to simply refer to them here.]
> +
> +- **R6** The hypervisor shall expose a _HID (hardware identifier) object
> + in the VMGenId device's scope that is unique to the hypervisor vendor.
> +
> +
> +QEMU Implementation
> +-------------------
> +
> +The above-mentioned specification does not dictate which ACPI descriptor table
> +will contain the VM Generation ID device. Other implementations (Hyper-V and
> +Xen) put it in the main descriptor table (Differentiated System Description
> +Table or DSDT). For ease of debugging and implementation, we have decided to
> +put it in its own Secondary System Description Table, or SSDT.
> +
> +The following is a dump of the contents from a running system::
> +
> + # iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT
> +
> + Intel ACPI Component Architecture
> + ASL+ Optimizing Compiler version 20150717-64
> + Copyright (c) 2000 - 2015 Intel Corporation
> +
> + Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length
> + 00000198 (0x0000C6)
> + ACPI: SSDT 0x0000000000000000 0000C6 (v01 BOCHS VMGENID 00000001 BXPC 00000001)
> + Acpi table [SSDT] successfully installed and loaded
> + Pass 1 parse of [SSDT]
> + Pass 2 parse of [SSDT]
> + Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions)
> +
> + Parsing completed
> + Disassembly completed
> + ASL Output: ./SSDT.dsl - 1631 bytes
> + # cat SSDT.dsl
> + /*
> + * Intel ACPI Component Architecture
> + * AML/ASL+ Disassembler version 20150717-64
> + * Copyright (c) 2000 - 2015 Intel Corporation
> + *
> + * Disassembling to symbolic ASL+ operators
> + *
> + * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb 5 00:19:37 2017
> + *
> + * Original Table Header:
> + * Signature "SSDT"
> + * Length 0x000000CA (202)
> + * Revision 0x01
> + * Checksum 0x4B
> + * OEM ID "BOCHS "
> + * OEM Table ID "VMGENID"
> + * OEM Revision 0x00000001 (1)
> + * Compiler ID "BXPC"
> + * Compiler Version 0x00000001 (1)
> + */
> + DefinitionBlock ("/sys/firmware/acpi/tables/SSDT.aml", "SSDT", 1, "BOCHS ", "VMGENID", 0x00000001)
> + {
> + Name (VGIA, 0x07FFF000)
> + Scope (\_SB)
> + {
> + Device (VGEN)
> + {
> + Name (_HID, "QEMUVGID") // _HID: Hardware ID
> + Name (_CID, "VM_Gen_Counter") // _CID: Compatible ID
> + Name (_DDN, "VM_Gen_Counter") // _DDN: DOS Device Name
> + Method (_STA, 0, NotSerialized) // _STA: Status
> + {
> + Local0 = 0x0F
> + If ((VGIA == Zero))
> + {
> + Local0 = Zero
> + }
> +
> + Return (Local0)
> + }
> +
> + Method (ADDR, 0, NotSerialized)
> + {
> + Local0 = Package (0x02) {}
> + Index (Local0, Zero) = (VGIA + 0x28)
> + Index (Local0, One) = Zero
> + Return (Local0)
> + }
> + }
> + }
> +
> + Method (\_GPE._E05, 0, NotSerialized) // _Exx: Edge-Triggered GPE
> + {
> + Notify (\_SB.VGEN, 0x80) // Status Change
> + }
> + }
> +
> +
> +Design Details:
> +---------------
> +
> +Requirements R1a through R1e dictate that the memory holding the
> +VM Generation ID must be allocated and owned by the guest firmware,
> +in this case BIOS or UEFI. However, to be useful, QEMU must be able to
> +change the contents of the memory at runtime, specifically when starting a
> +backed-up or snapshotted image. In order to do this, QEMU must know the
> +address that has been allocated.
> +
> +The mechanism chosen for this memory sharing is writable fw_cfg blobs.
> +These are data object that are visible to both QEMU and guests, and are
> +addressable as sequential files.
> +
> +More information about fw_cfg can be found in :doc:`fw_cfg`.
> +
> +Two fw_cfg blobs are used in this case:
> +
> +``/etc/vmgenid_guid``
> +
> +- contains the actual VM Generation ID GUID
> +- read-only to the guest
> +
> +``/etc/vmgenid_addr``
> +
> +- contains the address of the downloaded vmgenid blob
> +- writable by the guest
> +
> +
> +QEMU sends the following commands to the guest at startup:
> +
> +1. Allocate memory for vmgenid_guid fw_cfg blob.
> +2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as
> + shown above in the iasl dump). Note that this change is not propagated
> + back to QEMU.
> +3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr
> + via the fw_cfg DMA interface.
> +
> +After step 3, QEMU is able to update the contents of vmgenid_guid at will.
> +
> +Since BIOS or UEFI does not necessarily run when we wish to change the GUID,
> +the value of VGIA is persisted via the VMState mechanism.
> +
> +As spelled out in the specification, any change to the GUID executes an
> +ACPI notification. The exact handler to use is not specified, so the vmgenid
> +device uses the first unused one: ``\_GPE._E05``.
> +
> +
> +Endian-ness Considerations:
> +---------------------------
> +
> +Although not specified in Microsoft's document, it is assumed that the
> +device is expected to use little-endian format.
> +
> +All GUID passed in via command line or monitor are treated as big-endian.
> +GUID values displayed via monitor are shown in big-endian format.
> +
> +
> +GUID Storage Format:
> +--------------------
> +
> +In order to implement an OVMF "SDT Header Probe Suppressor", the contents of
> +the vmgenid_guid fw_cfg blob are not simply a 128-bit GUID. There is also
> +significant padding in order to align and fill a memory page, as shown in the
> +following diagram::
> +
> + +----------------------------------+
> + | SSDT with OEM Table ID = VMGENID |
> + +----------------------------------+
> + | ... | TOP OF PAGE
> + | VGIA dword object ---------------|-----> +---------------------------+
> + | ... | | fw-allocated array for |
> + | _STA method referring to VGIA | | "etc/vmgenid_guid" |
> + | ... | +---------------------------+
> + | ADDR method referring to VGIA | | 0: OVMF SDT Header probe |
> + | ... | | suppressor |
> + +----------------------------------+ | 36: padding for 8-byte |
> + | alignment |
> + | 40: GUID |
> + | 56: padding to page size |
> + +---------------------------+
> + END OF PAGE
> +
> +
> +Device Usage:
> +-------------
> +
> +The device has one property, which may be only be set using the command line:
> +
> +``guid``
> + sets the value of the GUID. A special value ``auto`` instructs
> + QEMU to generate a new random GUID.
> +
> +For example::
> +
> + QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
> + QEMU -device vmgenid,guid=auto
> +
> +The property may be queried via QMP/HMP::
> +
> + (QEMU) query-vm-generation-id
> + {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}}
> +
> +Setting of this parameter is intentionally left out from the QMP/HMP
> +interfaces. There are no known use cases for changing the GUID once QEMU is
> +running, and adding this capability would greatly increase the complexity.
> diff --git a/docs/specs/vmgenid.txt b/docs/specs/vmgenid.txt
> deleted file mode 100644
> index 80ff69f31cc..00000000000
> --- a/docs/specs/vmgenid.txt
> +++ /dev/null
> @@ -1,245 +0,0 @@
> -VIRTUAL MACHINE GENERATION ID
> -=============================
> -
> -Copyright (C) 2016 Red Hat, Inc.
> -Copyright (C) 2017 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,
> -referred to as a Globally Unique Identifier, or GUID.
> -
> -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). The
> -guest operating system notices the change, and is then able to react as
> -appropriate by marking its copies of distributed databases as dirty,
> -re-initializing its random number generator etc.
> -
> -
> -Requirements
> -------------
> -
> -These requirements are extracted from the "How to implement virtual machine
> -generation ID support in a virtualization platform" section of the
> -specification, dated August 1, 2012.
> -
> -
> -The document may be found on the web at:
> - http://go.microsoft.com/fwlink/?LinkId=260709
> -
> -R1a. The generation ID shall live in an 8-byte aligned buffer.
> -
> -R1b. The buffer holding the generation ID shall be in guest RAM, ROM, or device
> - MMIO range.
> -
> -R1c. The buffer holding the generation ID shall be kept separate from areas
> - used by the operating system.
> -
> -R1d. The buffer shall not be covered by an AddressRangeMemory or
> - AddressRangeACPI entry in the E820 or UEFI memory map.
> -
> -R1e. The generation ID shall not live in a page frame that could be mapped with
> - caching disabled. (In other words, regardless of whether the generation ID
> - lives in RAM, ROM or MMIO, it shall only be mapped as cacheable.)
> -
> -R2 to R5. [These AML requirements are isolated well enough in the Microsoft
> - specification for us to simply refer to them here.]
> -
> -R6. The hypervisor shall expose a _HID (hardware identifier) object in the
> - VMGenId device's scope that is unique to the hypervisor vendor.
> -
> -
> -QEMU Implementation
> --------------------
> -
> -The above-mentioned specification does not dictate which ACPI descriptor table
> -will contain the VM Generation ID device. Other implementations (Hyper-V and
> -Xen) put it in the main descriptor table (Differentiated System Description
> -Table or DSDT). For ease of debugging and implementation, we have decided to
> -put it in its own Secondary System Description Table, or SSDT.
> -
> -The following is a dump of the contents from a running system:
> -
> -# iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT
> -
> -Intel ACPI Component Architecture
> -ASL+ Optimizing Compiler version 20150717-64
> -Copyright (c) 2000 - 2015 Intel Corporation
> -
> -Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length
> -00000198 (0x0000C6)
> -ACPI: SSDT 0x0000000000000000 0000C6 (v01 BOCHS VMGENID 00000001 BXPC
> -00000001)
> -Acpi table [SSDT] successfully installed and loaded
> -Pass 1 parse of [SSDT]
> -Pass 2 parse of [SSDT]
> -Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions)
> -
> -Parsing completed
> -Disassembly completed
> -ASL Output: ./SSDT.dsl - 1631 bytes
> -# cat SSDT.dsl
> -/*
> - * Intel ACPI Component Architecture
> - * AML/ASL+ Disassembler version 20150717-64
> - * Copyright (c) 2000 - 2015 Intel Corporation
> - *
> - * Disassembling to symbolic ASL+ operators
> - *
> - * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb 5 00:19:37 2017
> - *
> - * Original Table Header:
> - * Signature "SSDT"
> - * Length 0x000000CA (202)
> - * Revision 0x01
> - * Checksum 0x4B
> - * OEM ID "BOCHS "
> - * OEM Table ID "VMGENID"
> - * OEM Revision 0x00000001 (1)
> - * Compiler ID "BXPC"
> - * Compiler Version 0x00000001 (1)
> - */
> -DefinitionBlock ("/sys/firmware/acpi/tables/SSDT.aml", "SSDT", 1, "BOCHS ",
> -"VMGENID", 0x00000001)
> -{
> - Name (VGIA, 0x07FFF000)
> - Scope (\_SB)
> - {
> - Device (VGEN)
> - {
> - Name (_HID, "QEMUVGID") // _HID: Hardware ID
> - Name (_CID, "VM_Gen_Counter") // _CID: Compatible ID
> - Name (_DDN, "VM_Gen_Counter") // _DDN: DOS Device Name
> - Method (_STA, 0, NotSerialized) // _STA: Status
> - {
> - Local0 = 0x0F
> - If ((VGIA == Zero))
> - {
> - Local0 = Zero
> - }
> -
> - Return (Local0)
> - }
> -
> - Method (ADDR, 0, NotSerialized)
> - {
> - Local0 = Package (0x02) {}
> - Index (Local0, Zero) = (VGIA + 0x28)
> - Index (Local0, One) = Zero
> - Return (Local0)
> - }
> - }
> - }
> -
> - Method (\_GPE._E05, 0, NotSerialized) // _Exx: Edge-Triggered GPE
> - {
> - Notify (\_SB.VGEN, 0x80) // Status Change
> - }
> -}
> -
> -
> -Design Details:
> ----------------
> -
> -Requirements R1a through R1e dictate that the memory holding the
> -VM Generation ID must be allocated and owned by the guest firmware,
> -in this case BIOS or UEFI. However, to be useful, QEMU must be able to
> -change the contents of the memory at runtime, specifically when starting a
> -backed-up or snapshotted image. In order to do this, QEMU must know the
> -address that has been allocated.
> -
> -The mechanism chosen for this memory sharing is writable fw_cfg blobs.
> -These are data object that are visible to both QEMU and guests, and are
> -addressable as sequential files.
> -
> -More information about fw_cfg can be found in "docs/specs/fw_cfg.txt"
> -
> -Two fw_cfg blobs are used in this case:
> -
> -/etc/vmgenid_guid - contains the actual VM Generation ID GUID
> - - read-only to the guest
> -/etc/vmgenid_addr - contains the address of the downloaded vmgenid blob
> - - writable by the guest
> -
> -
> -QEMU sends the following commands to the guest at startup:
> -
> -1. Allocate memory for vmgenid_guid fw_cfg blob.
> -2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as
> - shown above in the iasl dump). Note that this change is not propagated
> - back to QEMU.
> -3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr
> - via the fw_cfg DMA interface.
> -
> -After step 3, QEMU is able to update the contents of vmgenid_guid at will.
> -
> -Since BIOS or UEFI does not necessarily run when we wish to change the GUID,
> -the value of VGIA is persisted via the VMState mechanism.
> -
> -As spelled out in the specification, any change to the GUID executes an
> -ACPI notification. The exact handler to use is not specified, so the vmgenid
> -device uses the first unused one: \_GPE._E05.
> -
> -
> -Endian-ness Considerations:
> ----------------------------
> -
> -Although not specified in Microsoft's document, it is assumed that the
> -device is expected to use little-endian format.
> -
> -All GUID passed in via command line or monitor are treated as big-endian.
> -GUID values displayed via monitor are shown in big-endian format.
> -
> -
> -GUID Storage Format:
> ---------------------
> -
> -In order to implement an OVMF "SDT Header Probe Suppressor", the contents of
> -the vmgenid_guid fw_cfg blob are not simply a 128-bit GUID. There is also
> -significant padding in order to align and fill a memory page, as shown in the
> -following diagram:
> -
> -+----------------------------------+
> -| SSDT with OEM Table ID = VMGENID |
> -+----------------------------------+
> -| ... | TOP OF PAGE
> -| VGIA dword object ---------------|-----> +---------------------------+
> -| ... | | fw-allocated array for |
> -| _STA method referring to VGIA | | "etc/vmgenid_guid" |
> -| ... | +---------------------------+
> -| ADDR method referring to VGIA | | 0: OVMF SDT Header probe |
> -| ... | | suppressor |
> -+----------------------------------+ | 36: padding for 8-byte |
> - | alignment |
> - | 40: GUID |
> - | 56: padding to page size |
> - +---------------------------+
> - END OF PAGE
> -
> -
> -Device Usage:
> --------------
> -
> -The device has one property, which may be only be set using the command line:
> -
> - guid - sets the value of the GUID. A special value "auto" instructs
> - QEMU to generate a new random GUID.
> -
> -For example:
> -
> - QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
> - QEMU -device vmgenid,guid=auto
> -
> -The property may be queried via QMP/HMP:
> -
> - (QEMU) query-vm-generation-id
> - {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}}
> -
> -Setting of this parameter is intentionally left out from the QMP/HMP
> -interfaces. There are no known use cases for changing the GUID once QEMU is
> -running, and adding this capability would greatly increase the complexity.
next prev parent reply other threads:[~2023-10-31 15:44 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-09-27 15:11 [PATCH 0/8] docs/specs: Convert txt files to rST Peter Maydell
2023-09-27 15:11 ` [PATCH 1/8] docs/specs/vmw_pvscsi-spec: Convert " Peter Maydell
2023-10-19 16:38 ` Thomas Huth
2023-09-27 15:11 ` [PATCH 2/8] docs/specs/edu: " Peter Maydell
2023-10-19 16:48 ` Thomas Huth
2023-09-27 15:12 ` [PATCH 3/8] docs/specs/ivshmem-spec: " Peter Maydell
2023-10-31 15:46 ` Philippe Mathieu-Daudé
2023-09-27 15:12 ` [PATCH 4/8] docs/specs/pvpanic: " Peter Maydell
2023-10-31 15:33 ` Philippe Mathieu-Daudé
2023-09-27 15:12 ` [PATCH 5/8] docs/specs/standard-vga: " Peter Maydell
2023-10-31 15:36 ` Philippe Mathieu-Daudé
2023-09-27 15:12 ` [PATCH 6/8] docs/specs/virt-ctlr: " Peter Maydell
2023-10-31 15:39 ` Philippe Mathieu-Daudé
2023-10-31 15:43 ` Peter Maydell
2023-11-08 10:31 ` Philippe Mathieu-Daudé
2023-09-27 15:12 ` [PATCH 7/8] docs/specs/vmcoreinfo: " Peter Maydell
2023-10-31 15:42 ` Philippe Mathieu-Daudé
2023-11-02 13:35 ` Marc-André Lureau
2023-09-27 15:12 ` [PATCH 8/8] docs/specs/vmgenid: " Peter Maydell
2023-10-31 15:43 ` Philippe Mathieu-Daudé [this message]
2023-11-01 11:48 ` Ani Sinha
2023-10-17 12:46 ` [PATCH 0/8] docs/specs: Convert txt files " Peter Maydell
2023-10-31 14:09 ` Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=878a78c4-a07c-04bb-7618-5fb5c2347420@linaro.org \
--to=philmd@linaro.org \
--cc=anisinha@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).