| Message ID | 20250515172732.3992504-3-pierrick.bouvier@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | qapi: remove all TARGET_* conditionals from the schema | expand |
Pierrick Bouvier <pierrick.bouvier@linaro.org> writes: > From: Daniel P. Berrangé <berrange@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.henderson@linaro.org> > Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> > Signed-off-by: Pierrick Bouvier <pierrick.bouvier@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.
On 5/18/25 10:57 PM, Markus Armbruster wrote: > Pierrick Bouvier <pierrick.bouvier@linaro.org> writes: > >> From: Daniel P. Berrangé <berrange@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.henderson@linaro.org> >> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> >> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@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.
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. +# +# 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. # # 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. # # 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)