Re: [PATCH v3 4/9] hw/misc/vmlaunchupdate: add api header

On 30.07.26 09:12, Ani Sinha wrote:
> Add a separate header file for guest usable api definitions.
>
> CC: Alex Graf <[email protected]>
> CC: Gerd Hoffman <[email protected]>
> Signed-off-by: Ani Sinha <[email protected]>
> ---
>   .../standard-headers/misc/vmlaunchupdate.h    | 102 ++++++++++++++++++
>   1 file changed, 102 insertions(+)
>   create mode 100644 include/standard-headers/misc/vmlaunchupdate.h
>
> diff --git a/include/standard-headers/misc/vmlaunchupdate.h b/include/standard-headers/misc/vmlaunchupdate.h
> new file mode 100644
> index 0000000000..fc18f8faf7
> --- /dev/null
> +++ b/include/standard-headers/misc/vmlaunchupdate.h


Didn't standard-headers usually get imported from somewhere, like Linux? 
Where does this one originate? If it's self written, why not put it into 
include/hw/misc?


> @@ -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 <[email protected]>
> + *
> + * 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,
> +    VM_LAUNCHUPDATE_LOAD_FAIL,
> +    VM_LAUNCHUPDATE_NOT_IGVM_INIT,
> +};
> +
> +typedef struct {
> +    /* 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;


In theory, we may want to allow all of this logic with TCG eventually. 
At that point, we need to watch out for different struct layout 
constraints implied by the compiler. It's probably best to mark this 
struct QEMU_PACKED right away to not run into accidental padding on 
obscure platforms later.


Alex