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>
---
.../standard-headers/misc/vmlaunchupdate.h | 102 ++++++++++++++++++
1 file changed, 102 insertions(+)
create mode 100644 include/standard-headers/misc/vmlaunchupdate.h
changelog:
v7: add specific values to enum as suggested by Gerd here
https://lists.gnu.org/archive/html/qemu-devel/2026-08/msg03621.html
diff --git a/include/standard-headers/misc/vmlaunchupdate.h b/include/standard-headers/misc/vmlaunchupdate.h
new file mode 100644
index 0000000000..7f8382a765
--- /dev/null
+++ b/include/standard-headers/misc/vmlaunchupdate.h
@@ -0,0 +1,102 @@
+/*
+ * Guest driven VM launch state update device via IGVM.
+ * The definitions in this header defines the API for the hypervisor interface.
+ * For details and specification, please look at docs/specs/vmlaunchupdate.rst.
+ *
+ * Copyright (C) 2026 Red Hat, Inc.
+ *
+ * Authors: Ani Sinha <anisinha@redhat.com>
+ *
+ * SPDX-License-Identifier: GPL-2.0-or-later
+ *
+ */
+#ifndef VMLAUNCHUPDATE_API_H
+#define VMLAUNCHUPDATE_API_H
+
+/* fw-cfg file definition */
+#define FILE_VMLAUNCHUPDATE "etc/vmlaunchupdate"
+
+/* version */
+#define VM_LAUNCHUPDATE_VERSION 0x01
+
+/* format bits, used by both 'capabilities' and 'control' */
+
+/* igvm */
+#define VM_LAUNCHUPDATE_FORMAT_IGVM (1ULL << 32)
+
+/* 'control' field bits */
+
+/* disable vmlaunchupdate interface */
+#define VM_LAUNCHUPDATE_CTL_DISABLE (1 << 0)
+/* revert to the original host provided igvm */
+#define VM_LAUNCHUPDATE_CTL_HOST_IGVM (1 << 1)
+
+/* The combination of the above two ctl interfaces work as
+ * follows:
+ *
+ * A) CTL_HOST_IGVM=off CTL_DISABLE=off
+ *
+ * Supplied IGVM file replaces the firmware permanently. Updating the
+ * firmware again is possible.
+ *
+ * B) CTL_HOST_IGVM=off CTL_DISABLE=on
+ *
+ * Supplied IGVM file replaces the firmware permanently. Updating the
+ * firmware again is not possible.
+ *
+ * C) CTL_HOST_IGVM=on CTL_DISABLE=off
+ *
+ * Supplied IGVM file replaces the firmware for one reset. Resetting
+ * again will switch back to the original firmware. Updating the
+ * firmware again is possible.
+ *
+ * D) CTL_HOST_IGVM=on CTL_DISABLE=on
+ *
+ * Supplied IGVM file replaces the firmware for one reset. Resetting
+ * again will switch back to the original firmware. Updating the
+ * firmware again is NOT possible.
+ *
+ */
+
+/* status code */
+enum VMLaunchUpdateStatus {
+ VM_LAUNCHUPDATE_SUCCESS = 0,
+ VM_LAUNCHUPDATE_LOAD_FAIL = 1,
+ VM_LAUNCHUPDATE_NOT_IGVM_INIT = 2,
+};
+
+typedef struct QEMU_PACKED {
+ /* api version */
+ uint16_t version;
+
+ /*
+ * The guest can read this in order to determine if loading new IGVM
+ * succeeded.
+ */
+ uint16_t status;
+
+ uint32_t _padding;
+
+ /* VMM capabilities, read-only. */
+ uint64_t capabilities;
+ /* control bits, see VMFWUPDATE_CTL_* */
+ uint64_t control;
+
+ /*
+ * address and size of the IGVM image. Will be cleared when
+ * the write completes successfully and IGVM file is correctly parsed.
+ */
+ uint64_t fw_image_addr;
+ uint64_t fw_image_size;
+
+ /*
+ * address + size of opaque blob. The guest can use this to pass on
+ * information, for example which memory region the linux kernel has been
+ * loaded to. writable, will be kept intact on firmware update.
+ */
+ uint64_t opaque_addr;
+ uint64_t opaque_size;
+
+} VMLaunchUpdate;
+
+#endif
--
2.42.0