Pierrick Bouvier <pierrick.bouv...@linaro.org> writes:
> From: Daniel P. Berrangé <berra...@redhat.com>
>
> This gives some more context about the behaviour of the commands in
> unsupported guest configuration or platform scenarios.
>
> Reviewed-by: Richard Henderson <richard.hender...@linaro.org>
> Signed-off-by: Daniel P. Berrangé <berra...@redhat.com>
> Signed-off-by: Pierrick Bouvier <pierrick.bouv...@linaro.org>
> ---
> 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 5d0ffb0164f..ae55e437a5f 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.
We prefer imperative mood "Return" over "Returns". Could also use "Get"
or "Query"; matter of taste.
> +#
> +# If unavailable due to an incompatible configuration the
> +# returned @enabled field will be set to 'false' and the
I'd prefer "field is set".
> +# state of all other fields is undefined.
> #
> # 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
> #
Errors better go into their own section.
# Returns: The @SevLaunchMeasureInfo for the guest
#
# Errors:
# - If the launch measurement is unavailable, either due to an
# invalid guest configuration or if the guest has not reached
# the required SEV state, GenericError
> @@ -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.
> #
> # Returns: SevCapability objects.
> #
Likewise.
Suggest to use the opportunity to switch the intro to imperative mood.
Together:
##
# Get SEV capabilities.
#
# This is only supported on AMD X86 platforms with KVM enabled.
#
# Returns: SevCapability objects.
#
# Errors:
# - If # SEV is not available on the platform, GenericError
#
> @@ -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
> #
Likewise.
> @@ -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)
Likewise.
docs/devel/qapi-code-gen.rst:
For legibility, wrap text paragraphs so every line is at most 70
characters long.
Separate sentences with two spaces.
