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

[Pierrick Bouvier]

On 5/18/25 10:57 PM, Markus Armbruster wrote:

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.

All changes done, as requested.