Skip to content
Snippets Groups Projects
Commit 912fb367 authored by Peter Maydell's avatar Peter Maydell
Browse files

docs/specs/vmgenid: Convert to rST 


Convert docs/specs/vmgenid.txt to rST format.

Reviewed-by: default avatarAni Sinha <anisinha@redhat.com>
Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
Message-id: 20230927151205.70930-9-peter.maydell@linaro.org
parent 096d3ce2
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
MAINTAINERS
+ 1
− 1
View file @ 912fb367
......@@ -2437,7 +2437,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
......
docs/specs/index.rst
+ 1
− 0
View file @ 912fb367
......@@ -31,3 +31,4 @@ guest hardware that is specific to QEMU.
standard-vga
virt-ctlr
vmcoreinfo
vmgenid
docs/specs/vmgenid.txt → docs/specs/vmgenid.rst
+ 246
− 0
View file @ 912fb367
VIRTUAL MACHINE GENERATION ID
=============================
Virtual Machine Generation ID Device
====================================
Copyright (C) 2016 Red Hat, Inc.
Copyright (C) 2017 Skyport Systems, Inc.
..
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.
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
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.
......@@ -25,33 +24,31 @@ 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
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.
- **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.
- **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.
- **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.
- **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.)
- **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.]
- **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.
- **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
......@@ -63,84 +60,82 @@ 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
}
}
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:
......@@ -157,14 +152,19 @@ 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"
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
``/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:
......@@ -183,7 +183,7 @@ 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.
device uses the first unused one: ``\_GPE._E05``.
Endian-ness Considerations:
......@@ -202,24 +202,24 @@ 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
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:
......@@ -227,15 +227,16 @@ 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.
``guid``
sets the value of the GUID. A special value ``auto`` instructs
QEMU to generate a new random GUID.
For example:
For example::
QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
QEMU -device vmgenid,guid=auto
The property may be queried via QMP/HMP:
The property may be queried via QMP/HMP::
(QEMU) query-vm-generation-id
{"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}}
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment