[PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and query-sgx-capabilities

[PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and query-sgx-capabilities

[Zhao Liu]

Hi all,

There're 2 QMP commands: query-sgx and query-sgx-capabilities, but
their outputs are very similar and the documentation lacks clear
differentiation.

From the codes, query-sgx is used to gather guest's SGX capabilities
(including SGX related CPUIDs and EPC sections' size, in SGXInfo), and
query-sgx-capabilities is used to gather host's SGX capabilities 
(descripted by SGXInfo as well).

Therefore, fix their documentation to reflect this difference.

Thanks and Best Regards,
Zhao
---
Zhao Liu (2):
  qapi/misc-target: Fix the doc related SGXEPCSection
  qapi/misc-target: Fix the doc to distinguish query-sgx and
    query-sgx-capabilities

 qapi/misc-target.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

-- 
2.34.1

[PATCH 1/2] qapi/misc-target: Fix the doc related SGXEPCSection

[Zhao Liu]

The "sections" field of SGXInfo is used to gather EPC section
information for both the guest and the host. Therefore, delete the "for
guest" limitation.

Additionally, avoid the abbreviation "info" and use "information"
instead. And for SGXEPCSection, delete the redundant word "info".

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 qapi/misc-target.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 42e4a7417dc6..ed5b7db1bd2a 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -321,7 +321,7 @@
 ##
 # @SGXEPCSection:
 #
-# Information about intel SGX EPC section info
+# Information about intel SGX EPC section
 #
 # @node: the numa node
 #
@@ -346,7 +346,7 @@
 #
 # @flc: true if FLC is supported
 #
-# @sections: The EPC sections info for guest (Since: 7.0)
+# @sections: The EPC sections information (Since: 7.0)
 #
 # Since: 6.2
 ##
-- 
2.34.1

[PATCH 2/2] qapi/misc-target: Fix the doc to distinguish query-sgx and query-sgx-capabilities

[Zhao Liu]

There're 2 QMP commands: query-sgx and query-sgx-capabilities, but
their outputs are very similar and the documentation lacks clear
differentiation.

From the codes, query-sgx is used to gather guest's SGX capabilities
(including SGX related CPUIDs and EPC sections' size, in SGXInfo), and
if guest doesn't have SGX, then QEMU will report the error message.

On the other hand, query-sgx-capabilities is used to gather host's SGX
capabilities (descripted by SGXInfo as well). And if host doesn't
support SGX, then QEMU will also report the error message.

Considering that SGXInfo is already documented and both these 2 commands
have enough error messages (for the exception case in their codes).

Therefore the QAPI documentation for these two commands only needs to
emphasize that one of them applies to the guest and the other to the
host.

Fix their documentation to reflect this difference.

Reported-by: Markus Armbruster <armbru@redhat.com>
Suggested-by: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: Zhao Liu <zhao1.liu@intel.com>
---
 qapi/misc-target.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index ed5b7db1bd2a..903863e8d0c2 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -361,7 +361,7 @@
 ##
 # @query-sgx:
 #
-# Returns information about SGX
+# Returns information about configured SGX capabilities of guest
 #
 # Returns: @SGXInfo
 #
@@ -380,7 +380,7 @@
 ##
 # @query-sgx-capabilities:
 #
-# Returns information from host SGX capabilities
+# Returns information about SGX capabilities of host
 #
 # Returns: @SGXInfo
 #
-- 
2.34.1

Re: [PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and query-sgx-capabilities

[Markus Armbruster]

Zhao Liu <zhao1.liu@intel.com> writes:

> Hi all,
>
> There're 2 QMP commands: query-sgx and query-sgx-capabilities, but
> their outputs are very similar and the documentation lacks clear
> differentiation.
>
 >From the codes, query-sgx is used to gather guest's SGX capabilities
> (including SGX related CPUIDs and EPC sections' size, in SGXInfo), and
> query-sgx-capabilities is used to gather host's SGX capabilities 
> (descripted by SGXInfo as well).
>
> Therefore, fix their documentation to reflect this difference.

Acked-by: Markus Armbruster <armbru@redhat.com>

I'll take this through my tree unless Paolo is faster.

Re: [PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and query-sgx-capabilities

[Zhao Liu]

On Thu, May 15, 2025 at 08:07:02AM +0200, Markus Armbruster wrote:
> Date: Thu, 15 May 2025 08:07:02 +0200
> From: Markus Armbruster <armbru@redhat.com>
> Subject: Re: [PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and
>  query-sgx-capabilities
> 
> Zhao Liu <zhao1.liu@intel.com> writes:
> 
> > Hi all,
> >
> > There're 2 QMP commands: query-sgx and query-sgx-capabilities, but
> > their outputs are very similar and the documentation lacks clear
> > differentiation.
> >
>  >From the codes, query-sgx is used to gather guest's SGX capabilities
> > (including SGX related CPUIDs and EPC sections' size, in SGXInfo), and
> > query-sgx-capabilities is used to gather host's SGX capabilities 
> > (descripted by SGXInfo as well).
> >
> > Therefore, fix their documentation to reflect this difference.
> 
> Acked-by: Markus Armbruster <armbru@redhat.com>
> 
> I'll take this through my tree unless Paolo is faster.

Thanks Markus!

I was also thinking you would like "SgxInfo" and "SgxEpcSection" instead
of current "SGXInfo" and "SGXEPCSection".

But I'm not sure if modifying the old names has any compatibility issues
for QAPI? If you think it's ok, I can continue to make the SGX naming
styles more QAPI compliant.

Regards,
Zhao

Re: [PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and query-sgx-capabilities

[Markus Armbruster]

Zhao Liu <zhao1.liu@intel.com> writes:

> On Thu, May 15, 2025 at 08:07:02AM +0200, Markus Armbruster wrote:
>> Date: Thu, 15 May 2025 08:07:02 +0200
>> From: Markus Armbruster <armbru@redhat.com>
>> Subject: Re: [PATCH 0/2] qapi/misc-target: Fix the doc of query-sgx and
>>  query-sgx-capabilities
>> 
>> Zhao Liu <zhao1.liu@intel.com> writes:
>> 
>> > Hi all,
>> >
>> > There're 2 QMP commands: query-sgx and query-sgx-capabilities, but
>> > their outputs are very similar and the documentation lacks clear
>> > differentiation.
>> >
>>  >From the codes, query-sgx is used to gather guest's SGX capabilities
>> > (including SGX related CPUIDs and EPC sections' size, in SGXInfo), and
>> > query-sgx-capabilities is used to gather host's SGX capabilities 
>> > (descripted by SGXInfo as well).
>> >
>> > Therefore, fix their documentation to reflect this difference.
>> 
>> Acked-by: Markus Armbruster <armbru@redhat.com>
>> 
>> I'll take this through my tree unless Paolo is faster.
>
> Thanks Markus!
>
> I was also thinking you would like "SgxInfo" and "SgxEpcSection" instead
> of current "SGXInfo" and "SGXEPCSection".

These are indeed easier to read, especially the latter.

> But I'm not sure if modifying the old names has any compatibility issues
> for QAPI? If you think it's ok, I can continue to make the SGX naming
> styles more QAPI compliant.

Type names are not visible at the external interface, so changing them
is just fine.  That's a feature!