1*912fb367SPeter MaydellVirtual Machine Generation ID Device 2*912fb367SPeter Maydell==================================== 3*912fb367SPeter Maydell 4*912fb367SPeter Maydell.. 5*912fb367SPeter Maydell Copyright (C) 2016 Red Hat, Inc. 6*912fb367SPeter Maydell Copyright (C) 2017 Skyport Systems, Inc. 7*912fb367SPeter Maydell 8*912fb367SPeter Maydell This work is licensed under the terms of the GNU GPL, version 2 or later. 9*912fb367SPeter Maydell See the COPYING file in the top-level directory. 10*912fb367SPeter Maydell 11*912fb367SPeter MaydellThe VM generation ID (``vmgenid``) device is an emulated device which 12*912fb367SPeter Maydellexposes a 128-bit, cryptographically random, integer value identifier, 13*912fb367SPeter Maydellreferred to as a Globally Unique Identifier, or GUID. 14*912fb367SPeter Maydell 15*912fb367SPeter MaydellThis allows management applications (e.g. libvirt) to notify the guest 16*912fb367SPeter Maydelloperating system when the virtual machine is executed with a different 17*912fb367SPeter Maydellconfiguration (e.g. snapshot execution or creation from a template). The 18*912fb367SPeter Maydellguest operating system notices the change, and is then able to react as 19*912fb367SPeter Maydellappropriate by marking its copies of distributed databases as dirty, 20*912fb367SPeter Maydellre-initializing its random number generator etc. 21*912fb367SPeter Maydell 22*912fb367SPeter Maydell 23*912fb367SPeter MaydellRequirements 24*912fb367SPeter Maydell------------ 25*912fb367SPeter Maydell 26*912fb367SPeter MaydellThese requirements are extracted from the "How to implement virtual machine 27*912fb367SPeter Maydellgeneration ID support in a virtualization platform" section of 28*912fb367SPeter Maydell`the Microsoft Virtual Machine Generation ID specification 29*912fb367SPeter Maydell<http://go.microsoft.com/fwlink/?LinkId=260709>`_ dated August 1, 2012. 30*912fb367SPeter Maydell 31*912fb367SPeter Maydell- **R1a** The generation ID shall live in an 8-byte aligned buffer. 32*912fb367SPeter Maydell 33*912fb367SPeter Maydell- **R1b** The buffer holding the generation ID shall be in guest RAM, 34*912fb367SPeter Maydell ROM, or device MMIO range. 35*912fb367SPeter Maydell 36*912fb367SPeter Maydell- **R1c** The buffer holding the generation ID shall be kept separate from 37*912fb367SPeter Maydell areas used by the operating system. 38*912fb367SPeter Maydell 39*912fb367SPeter Maydell- **R1d** The buffer shall not be covered by an AddressRangeMemory or 40*912fb367SPeter Maydell AddressRangeACPI entry in the E820 or UEFI memory map. 41*912fb367SPeter Maydell 42*912fb367SPeter Maydell- **R1e** The generation ID shall not live in a page frame that could be 43*912fb367SPeter Maydell mapped with caching disabled. (In other words, regardless of whether the 44*912fb367SPeter Maydell generation ID lives in RAM, ROM or MMIO, it shall only be mapped as 45*912fb367SPeter Maydell cacheable.) 46*912fb367SPeter Maydell 47*912fb367SPeter Maydell- **R2** to **R5** [These AML requirements are isolated well enough in the 48*912fb367SPeter Maydell Microsoft specification for us to simply refer to them here.] 49*912fb367SPeter Maydell 50*912fb367SPeter Maydell- **R6** The hypervisor shall expose a _HID (hardware identifier) object 51*912fb367SPeter Maydell in the VMGenId device's scope that is unique to the hypervisor vendor. 52*912fb367SPeter Maydell 53*912fb367SPeter Maydell 54*912fb367SPeter MaydellQEMU Implementation 55*912fb367SPeter Maydell------------------- 56*912fb367SPeter Maydell 57*912fb367SPeter MaydellThe above-mentioned specification does not dictate which ACPI descriptor table 58*912fb367SPeter Maydellwill contain the VM Generation ID device. Other implementations (Hyper-V and 59*912fb367SPeter MaydellXen) put it in the main descriptor table (Differentiated System Description 60*912fb367SPeter MaydellTable or DSDT). For ease of debugging and implementation, we have decided to 61*912fb367SPeter Maydellput it in its own Secondary System Description Table, or SSDT. 62*912fb367SPeter Maydell 63*912fb367SPeter MaydellThe following is a dump of the contents from a running system:: 64*912fb367SPeter Maydell 65*912fb367SPeter Maydell # iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT 66*912fb367SPeter Maydell 67*912fb367SPeter Maydell Intel ACPI Component Architecture 68*912fb367SPeter Maydell ASL+ Optimizing Compiler version 20150717-64 69*912fb367SPeter Maydell Copyright (c) 2000 - 2015 Intel Corporation 70*912fb367SPeter Maydell 71*912fb367SPeter Maydell Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length 72*912fb367SPeter Maydell 00000198 (0x0000C6) 73*912fb367SPeter Maydell ACPI: SSDT 0x0000000000000000 0000C6 (v01 BOCHS VMGENID 00000001 BXPC 00000001) 74*912fb367SPeter Maydell Acpi table [SSDT] successfully installed and loaded 75*912fb367SPeter Maydell Pass 1 parse of [SSDT] 76*912fb367SPeter Maydell Pass 2 parse of [SSDT] 77*912fb367SPeter Maydell Parsing Deferred Opcodes (Methods/Buffers/Packages/Regions) 78*912fb367SPeter Maydell 79*912fb367SPeter Maydell Parsing completed 80*912fb367SPeter Maydell Disassembly completed 81*912fb367SPeter Maydell ASL Output: ./SSDT.dsl - 1631 bytes 82*912fb367SPeter Maydell # cat SSDT.dsl 83*912fb367SPeter Maydell /* 84*912fb367SPeter Maydell * Intel ACPI Component Architecture 85*912fb367SPeter Maydell * AML/ASL+ Disassembler version 20150717-64 86*912fb367SPeter Maydell * Copyright (c) 2000 - 2015 Intel Corporation 87*912fb367SPeter Maydell * 88*912fb367SPeter Maydell * Disassembling to symbolic ASL+ operators 89*912fb367SPeter Maydell * 90*912fb367SPeter Maydell * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb 5 00:19:37 2017 91*912fb367SPeter Maydell * 92*912fb367SPeter Maydell * Original Table Header: 93*912fb367SPeter Maydell * Signature "SSDT" 94*912fb367SPeter Maydell * Length 0x000000CA (202) 95*912fb367SPeter Maydell * Revision 0x01 96*912fb367SPeter Maydell * Checksum 0x4B 97*912fb367SPeter Maydell * OEM ID "BOCHS " 98*912fb367SPeter Maydell * OEM Table ID "VMGENID" 99*912fb367SPeter Maydell * OEM Revision 0x00000001 (1) 100*912fb367SPeter Maydell * Compiler ID "BXPC" 101*912fb367SPeter Maydell * Compiler Version 0x00000001 (1) 102*912fb367SPeter Maydell */ 103*912fb367SPeter Maydell DefinitionBlock ("/sys/firmware/acpi/tables/SSDT.aml", "SSDT", 1, "BOCHS ", "VMGENID", 0x00000001) 104*912fb367SPeter Maydell { 105*912fb367SPeter Maydell Name (VGIA, 0x07FFF000) 106*912fb367SPeter Maydell Scope (\_SB) 107*912fb367SPeter Maydell { 108*912fb367SPeter Maydell Device (VGEN) 109*912fb367SPeter Maydell { 110*912fb367SPeter Maydell Name (_HID, "QEMUVGID") // _HID: Hardware ID 111*912fb367SPeter Maydell Name (_CID, "VM_Gen_Counter") // _CID: Compatible ID 112*912fb367SPeter Maydell Name (_DDN, "VM_Gen_Counter") // _DDN: DOS Device Name 113*912fb367SPeter Maydell Method (_STA, 0, NotSerialized) // _STA: Status 114*912fb367SPeter Maydell { 115*912fb367SPeter Maydell Local0 = 0x0F 116*912fb367SPeter Maydell If ((VGIA == Zero)) 117*912fb367SPeter Maydell { 118*912fb367SPeter Maydell Local0 = Zero 119*912fb367SPeter Maydell } 120*912fb367SPeter Maydell 121*912fb367SPeter Maydell Return (Local0) 122*912fb367SPeter Maydell } 123*912fb367SPeter Maydell 124*912fb367SPeter Maydell Method (ADDR, 0, NotSerialized) 125*912fb367SPeter Maydell { 126*912fb367SPeter Maydell Local0 = Package (0x02) {} 127*912fb367SPeter Maydell Index (Local0, Zero) = (VGIA + 0x28) 128*912fb367SPeter Maydell Index (Local0, One) = Zero 129*912fb367SPeter Maydell Return (Local0) 130*912fb367SPeter Maydell } 131*912fb367SPeter Maydell } 132*912fb367SPeter Maydell } 133*912fb367SPeter Maydell 134*912fb367SPeter Maydell Method (\_GPE._E05, 0, NotSerialized) // _Exx: Edge-Triggered GPE 135*912fb367SPeter Maydell { 136*912fb367SPeter Maydell Notify (\_SB.VGEN, 0x80) // Status Change 137*912fb367SPeter Maydell } 138*912fb367SPeter Maydell } 139*912fb367SPeter Maydell 140*912fb367SPeter Maydell 141*912fb367SPeter MaydellDesign Details: 142*912fb367SPeter Maydell--------------- 143*912fb367SPeter Maydell 144*912fb367SPeter MaydellRequirements R1a through R1e dictate that the memory holding the 145*912fb367SPeter MaydellVM Generation ID must be allocated and owned by the guest firmware, 146*912fb367SPeter Maydellin this case BIOS or UEFI. However, to be useful, QEMU must be able to 147*912fb367SPeter Maydellchange the contents of the memory at runtime, specifically when starting a 148*912fb367SPeter Maydellbacked-up or snapshotted image. In order to do this, QEMU must know the 149*912fb367SPeter Maydelladdress that has been allocated. 150*912fb367SPeter Maydell 151*912fb367SPeter MaydellThe mechanism chosen for this memory sharing is writable fw_cfg blobs. 152*912fb367SPeter MaydellThese are data object that are visible to both QEMU and guests, and are 153*912fb367SPeter Maydelladdressable as sequential files. 154*912fb367SPeter Maydell 155*912fb367SPeter MaydellMore information about fw_cfg can be found in :doc:`fw_cfg`. 156*912fb367SPeter Maydell 157*912fb367SPeter MaydellTwo fw_cfg blobs are used in this case: 158*912fb367SPeter Maydell 159*912fb367SPeter Maydell``/etc/vmgenid_guid`` 160*912fb367SPeter Maydell 161*912fb367SPeter Maydell- contains the actual VM Generation ID GUID 162*912fb367SPeter Maydell- read-only to the guest 163*912fb367SPeter Maydell 164*912fb367SPeter Maydell``/etc/vmgenid_addr`` 165*912fb367SPeter Maydell 166*912fb367SPeter Maydell- contains the address of the downloaded vmgenid blob 167*912fb367SPeter Maydell- writable by the guest 168*912fb367SPeter Maydell 169*912fb367SPeter Maydell 170*912fb367SPeter MaydellQEMU sends the following commands to the guest at startup: 171*912fb367SPeter Maydell 172*912fb367SPeter Maydell1. Allocate memory for vmgenid_guid fw_cfg blob. 173*912fb367SPeter Maydell2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as 174*912fb367SPeter Maydell shown above in the iasl dump). Note that this change is not propagated 175*912fb367SPeter Maydell back to QEMU. 176*912fb367SPeter Maydell3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr 177*912fb367SPeter Maydell via the fw_cfg DMA interface. 178*912fb367SPeter Maydell 179*912fb367SPeter MaydellAfter step 3, QEMU is able to update the contents of vmgenid_guid at will. 180*912fb367SPeter Maydell 181*912fb367SPeter MaydellSince BIOS or UEFI does not necessarily run when we wish to change the GUID, 182*912fb367SPeter Maydellthe value of VGIA is persisted via the VMState mechanism. 183*912fb367SPeter Maydell 184*912fb367SPeter MaydellAs spelled out in the specification, any change to the GUID executes an 185*912fb367SPeter MaydellACPI notification. The exact handler to use is not specified, so the vmgenid 186*912fb367SPeter Maydelldevice uses the first unused one: ``\_GPE._E05``. 187*912fb367SPeter Maydell 188*912fb367SPeter Maydell 189*912fb367SPeter MaydellEndian-ness Considerations: 190*912fb367SPeter Maydell--------------------------- 191*912fb367SPeter Maydell 192*912fb367SPeter MaydellAlthough not specified in Microsoft's document, it is assumed that the 193*912fb367SPeter Maydelldevice is expected to use little-endian format. 194*912fb367SPeter Maydell 195*912fb367SPeter MaydellAll GUID passed in via command line or monitor are treated as big-endian. 196*912fb367SPeter MaydellGUID values displayed via monitor are shown in big-endian format. 197*912fb367SPeter Maydell 198*912fb367SPeter Maydell 199*912fb367SPeter MaydellGUID Storage Format: 200*912fb367SPeter Maydell-------------------- 201*912fb367SPeter Maydell 202*912fb367SPeter MaydellIn order to implement an OVMF "SDT Header Probe Suppressor", the contents of 203*912fb367SPeter Maydellthe vmgenid_guid fw_cfg blob are not simply a 128-bit GUID. There is also 204*912fb367SPeter Maydellsignificant padding in order to align and fill a memory page, as shown in the 205*912fb367SPeter Maydellfollowing diagram:: 206*912fb367SPeter Maydell 207*912fb367SPeter Maydell +----------------------------------+ 208*912fb367SPeter Maydell | SSDT with OEM Table ID = VMGENID | 209*912fb367SPeter Maydell +----------------------------------+ 210*912fb367SPeter Maydell | ... | TOP OF PAGE 211*912fb367SPeter Maydell | VGIA dword object ---------------|-----> +---------------------------+ 212*912fb367SPeter Maydell | ... | | fw-allocated array for | 213*912fb367SPeter Maydell | _STA method referring to VGIA | | "etc/vmgenid_guid" | 214*912fb367SPeter Maydell | ... | +---------------------------+ 215*912fb367SPeter Maydell | ADDR method referring to VGIA | | 0: OVMF SDT Header probe | 216*912fb367SPeter Maydell | ... | | suppressor | 217*912fb367SPeter Maydell +----------------------------------+ | 36: padding for 8-byte | 218*912fb367SPeter Maydell | alignment | 219*912fb367SPeter Maydell | 40: GUID | 220*912fb367SPeter Maydell | 56: padding to page size | 221*912fb367SPeter Maydell +---------------------------+ 222*912fb367SPeter Maydell END OF PAGE 223*912fb367SPeter Maydell 224*912fb367SPeter Maydell 225*912fb367SPeter MaydellDevice Usage: 226*912fb367SPeter Maydell------------- 227*912fb367SPeter Maydell 228*912fb367SPeter MaydellThe device has one property, which may be only be set using the command line: 229*912fb367SPeter Maydell 230*912fb367SPeter Maydell``guid`` 231*912fb367SPeter Maydell sets the value of the GUID. A special value ``auto`` instructs 232*912fb367SPeter Maydell QEMU to generate a new random GUID. 233*912fb367SPeter Maydell 234*912fb367SPeter MaydellFor example:: 235*912fb367SPeter Maydell 236*912fb367SPeter Maydell QEMU -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87" 237*912fb367SPeter Maydell QEMU -device vmgenid,guid=auto 238*912fb367SPeter Maydell 239*912fb367SPeter MaydellThe property may be queried via QMP/HMP:: 240*912fb367SPeter Maydell 241*912fb367SPeter Maydell (QEMU) query-vm-generation-id 242*912fb367SPeter Maydell {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}} 243*912fb367SPeter Maydell 244*912fb367SPeter MaydellSetting of this parameter is intentionally left out from the QMP/HMP 245*912fb367SPeter Maydellinterfaces. There are no known use cases for changing the GUID once QEMU is 246*912fb367SPeter Maydellrunning, and adding this capability would greatly increase the complexity. 247