docs/specs/vmgenid.rst

8    This work is licensed under the terms of the GNU GPL, version 2 or later.
9    See the COPYING file in the top-level directory.
12 exposes a 128-bit, cryptographically random, integer value identifier,
19 appropriate by marking its copies of distributed databases as dirty,
20 re-initializing its random number generator etc.
24 ------------
27 generation ID support in a virtualization platform" section of
31 - **R1a** The generation ID shall live in an 8-byte aligned buffer.
33 - **R1b** The buffer holding the generation ID shall be in guest RAM,
36 - **R1c** The buffer holding the generation ID shall be kept separate from
39 - **R1d** The buffer shall not be covered by an AddressRangeMemory or
42 - **R1e** The generation ID shall not live in a page frame that could be
43   mapped with caching disabled. (In other words, regardless of whether the
47 - **R2** to **R5** [These AML requirements are isolated well enough in the
50 - **R6** The hypervisor shall expose a _HID (hardware identifier) object
55 -------------------
57 The above-mentioned specification does not dictate which ACPI descriptor table
58 will contain the VM Generation ID device.  Other implementations (Hyper-V and
60 Table or DSDT).  For ease of debugging and implementation, we have decided to
63 The following is a dump of the contents from a running system::
65   # iasl -p ./SSDT -d /sys/firmware/acpi/tables/SSDT
68   ASL+ Optimizing Compiler version 20150717-64
69   Copyright (c) 2000 - 2015 Intel Corporation
71   Reading ACPI table from file /sys/firmware/acpi/tables/SSDT - Length
75   Pass 1 parse of [SSDT]
76   Pass 2 parse of [SSDT]
81   ASL Output:    ./SSDT.dsl - 1631 bytes
85    * AML/ASL+ Disassembler version 20150717-64
86    * Copyright (c) 2000 - 2015 Intel Corporation
90    * Disassembly of /sys/firmware/acpi/tables/SSDT, Sun Feb  5 00:19:37 2017
134       Method (\_GPE._E05, 0, NotSerialized)  // _Exx: Edge-Triggered GPE
142 ---------------
147 change the contents of the memory at runtime, specifically when starting a
148 backed-up or snapshotted image.  In order to do this, QEMU must know the
161 - contains the actual VM Generation ID GUID
162 - read-only to the guest
166 - contains the address of the downloaded vmgenid blob
167 - writable by the guest
173 2. Write the address of vmgenid_guid into the SSDT (VGIA ACPI variable as
176 3. Write the address of vmgenid_guid back to QEMU's copy of vmgenid_addr
179 After step 3, QEMU is able to update the contents of vmgenid_guid at will.
182 the value of VGIA is persisted via the VMState mechanism.
185 ACPI notification.  The exact handler to use is not specified, so the vmgenid
189 Endian-ness Considerations:
190 ---------------------------
193 device is expected to use little-endian format.
195 All GUID passed in via command line or monitor are treated as big-endian.
196 GUID values displayed via monitor are shown in big-endian format.
200 --------------------
202 In order to implement an OVMF "SDT Header Probe Suppressor", the contents of
203 the vmgenid_guid fw_cfg blob are not simply a 128-bit GUID.  There is also
207   +----------------------------------+
209   +----------------------------------+
210   | ...                              |       TOP OF PAGE
211   | VGIA dword object ---------------|-----> +---------------------------+
212   | ...                              |       | fw-allocated array for    |
214   | ...                              |       +---------------------------+
217   +----------------------------------+       | 36: padding for 8-byte    |
221                                              +---------------------------+
222                                              END OF PAGE
226 -------------
231   sets the value of the GUID.  A special value ``auto`` instructs
236   QEMU  -device vmgenid,guid="324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"
237   QEMU  -device vmgenid,guid=auto
241   (QEMU) query-vm-generation-id
242   {"return": {"guid": "324e6eaf-d1d1-4bf6-bf41-b9bb6c91fb87"}}
244 Setting of this parameter is intentionally left out from the QMP/HMP
245 interfaces.  There are no known use cases for changing the GUID once QEMU is