Re: [PATCH 02/10] qapi: expand docs for SEV commands

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> This gives some more context about the behaviour of the commands in
> unsupported guest configuration or platform scenarios.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  qapi/misc-target.json | 43 ++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 36 insertions(+), 7 deletions(-)
>
> diff --git a/qapi/misc-target.json b/qapi/misc-target.json
> index 5d0ffb0164..ae55e437a5 100644
> --- a/qapi/misc-target.json
> +++ b/qapi/misc-target.json
> @@ -110,7 +110,11 @@
>  ##
>  # @query-sev:
>  #
> -# Returns information about SEV
> +# Returns information about SEV/SEV-ES/SEV-SNP.
> +#
> +# If unavailable due to an incompatible configuration the
> +# returned @enabled field will be set to 'false' and the
> +# state of all other fields is undefined.

That's awful.  Not this patch's fault.

What's "incompatible configuration"?

Actual behavior as far as I can tell:

* If !CONFIG_SEV: GenericError "SEV is not available in this QEMU".

* If CONFIG_SEV and !sev_enabled(): SevInfo filled with zero bytes

* If CONFIG_SEV and sev_enabled(): SevInfo filled properly

sev_enabled() is true when the machine's cgs member is an instance of
"sev-common".

>  #
>  # Returns: @SevInfo
>  #
> @@ -141,7 +145,16 @@
>  ##
>  # @query-sev-launch-measure:
>  #
> -# Query the SEV guest launch information.
> +# Query the SEV/SEV-ES guest launch information.
> +#
> +# This is only valid on x86 machines configured with KVM and the
> +# 'sev-guest' confidential virtualization object. The launch
> +# measurement for SEV-SNP guests is only available within
> +# the guest.
> +#
> +# This will return an error if the launch measurement is
> +# unavailable, either due to an invalid guest configuration
> +# or if the guest has not reached the required SEV state.
>  #
>  # Returns: The @SevLaunchMeasureInfo for the guest
>  #
> @@ -185,8 +198,9 @@
>  ##
>  # @query-sev-capabilities:
>  #
> -# This command is used to get the SEV capabilities, and is supported
> -# on AMD X86 platforms only.
> +# This command is used to get the SEV capabilities, and is only
> +# supported on AMD X86 platforms with KVM enabled. If SEV is not
> +# available on the platform an error will be returned.

What does "not supported" mean here?

>  #
>  # Returns: SevCapability objects.
>  #
> @@ -205,7 +219,15 @@
>  ##
>  # @sev-inject-launch-secret:
>  #
> -# This command injects a secret blob into memory of SEV guest.
> +# This command injects a secret blob into memory of a SEV/SEV-ES guest.
> +#
> +# This is only valid on x86 machines configured with KVM and the
> +# 'sev-guest' confidential virtualization object. SEV-SNP guests
> +# do not support launch secret injection
> +#
> +# This will return an error if launch secret injection is not possible,
> +# either due to an invalid guest configuration, or if the guest has not
> +# reached the required SEV state.
>  #
>  # @packet-header: the launch secret packet header encoded in base64
>  #
> @@ -236,8 +258,15 @@
>  ##
>  # @query-sev-attestation-report:
>  #
> -# This command is used to get the SEV attestation report, and is
> -# supported on AMD X86 platforms only.
> +# This command is used to get the SEV attestation report.
> +#
> +# This is only valid on x86 machines configured with KVM and the
> +# 'sev-guest' confidential virtualization object. The attestation
> +# report for SEV-SNP guests is only available within the guest.
> +#
> +# This will return an error if the attestation report is
> +# unavailable, either due to an invalid guest configuration
> +# or if the guest has not reached the required SEV state.
>  #
>  # @mnonce: a random 16 bytes value encoded in base64 (it will be
>  #     included in report)

Strict improvemement already, so
Acked-by: Markus Armbruster <armbru@redhat.com>