hw/misc/vmlaunchupdate: add api header
Add a separate header file for guest usable api definitions. CC: Alex Graf <graf@amazon.com> CC: Gerd Hoffman <kraxel@redhat.com> Reviewed-by: Alexander Graf <graf@amazon.com> Signed-off-by: Ani Sinha <anisinha@redhat.com> Message-ID: <20260819041105.110625-1-anisinha@redhat.com> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
Ani Sinha committed
Aug 19, 2026 at 09:41 UTC
b23f6d5294cc2b3bcf99c4c28b5b58b8ae5bc1f1
1 file changed
+102
include/standard-headers/misc/vmlaunchupdate.h
new
+102
@@ -0,0 +1,102 @@
1
+/*
2
+ * Guest driven VM launch state update device via IGVM.
3
+ * The definitions in this header defines the API for the hypervisor interface.
4
+ * For details and specification, please look at docs/specs/vmlaunchupdate.rst.
5
+ *
6
+ * Copyright (C) 2026 Red Hat, Inc.
7
+ *
8
+ * Authors: Ani Sinha <anisinha@redhat.com>
9
+ *
10
+ * SPDX-License-Identifier: GPL-2.0-or-later
11
+ *
12
+ */
13
+#ifndef VMLAUNCHUPDATE_API_H
14
+#define VMLAUNCHUPDATE_API_H
15
+
16
+/* fw-cfg file definition */
17
+#define FILE_VMLAUNCHUPDATE "etc/vmlaunchupdate"
18
+
19
+/* version */
20
+#define VM_LAUNCHUPDATE_VERSION 0x01
21
+
22
+/* format bits, used by both 'capabilities' and 'control' */
23
+
24
+/* igvm */
25
+#define VM_LAUNCHUPDATE_FORMAT_IGVM (1ULL << 32)
26
+
27
+/* 'control' field bits */
28
+
29
+/* disable vmlaunchupdate interface */
30
+#define VM_LAUNCHUPDATE_CTL_DISABLE (1 << 0)
31
+/* revert to the original host provided igvm */
32
+#define VM_LAUNCHUPDATE_CTL_HOST_IGVM (1 << 1)
33
+
34
+/* The combination of the above two ctl interfaces work as
35
+ * follows:
36
+ *
37
+ * A) CTL_HOST_IGVM=off CTL_DISABLE=off
38
+ *
39
+ * Supplied IGVM file replaces the firmware permanently. Updating the
40
+ * firmware again is possible.
41
+ *
42
+ * B) CTL_HOST_IGVM=off CTL_DISABLE=on
43
+ *
44
+ * Supplied IGVM file replaces the firmware permanently. Updating the
45
+ * firmware again is not possible.
46
+ *
47
+ * C) CTL_HOST_IGVM=on CTL_DISABLE=off
48
+ *
49
+ * Supplied IGVM file replaces the firmware for one reset. Resetting
50
+ * again will switch back to the original firmware. Updating the
51
+ * firmware again is possible.
52
+ *
53
+ * D) CTL_HOST_IGVM=on CTL_DISABLE=on
54
+ *
55
+ * Supplied IGVM file replaces the firmware for one reset. Resetting
56
+ * again will switch back to the original firmware. Updating the
57
+ * firmware again is NOT possible.
58
+ *
59
+ */
60
+
61
+/* status code */
62
+enum VMLaunchUpdateStatus {
63
+ VM_LAUNCHUPDATE_SUCCESS = 0,
64
+ VM_LAUNCHUPDATE_LOAD_FAIL = 1,
65
+ VM_LAUNCHUPDATE_NOT_IGVM_INIT = 2,
66
+};
67
+
68
+typedef struct QEMU_PACKED {
69
+ /* api version */
70
+ uint16_t version;
71
+
72
+ /*
73
+ * The guest can read this in order to determine if loading new IGVM
74
+ * succeeded.
75
+ */
76
+ uint16_t status;
77
+
78
+ uint32_t _padding;
79
+
80
+ /* VMM capabilities, read-only. */
81
+ uint64_t capabilities;
82
+ /* control bits, see VMFWUPDATE_CTL_* */
83
+ uint64_t control;
84
+
85
+ /*
86
+ * address and size of the IGVM image. Will be cleared when
87
+ * the write completes successfully and IGVM file is correctly parsed.
88
+ */
89
+ uint64_t fw_image_addr;
90
+ uint64_t fw_image_size;
91
+
92
+ /*
93
+ * address + size of opaque blob. The guest can use this to pass on
94
+ * information, for example which memory region the linux kernel has been
95
+ * loaded to. writable, will be kept intact on firmware update.
96
+ */
97
+ uint64_t opaque_addr;
98
+ uint64_t opaque_size;
99
+
100
+} VMLaunchUpdate;
101
+
102
+#endif