qapi/machine-target.json | 46 +++++++++++++++++++++++++++------------- qapi/pragma.json | 3 --- 2 files changed, 31 insertions(+), 18 deletions(-)
Let's document the parameters of these commands, so we can remove them
from the "documentation-exceptions" list.
While at it, extend the "Returns:" documentation as well, fixing a wrong
use of CpuModelBaselineInfo vs. CpuModelCompareInfo for
query-cpu-model-comparison.
Cc: Markus Armbruster <armbru@redhat.com>
Cc: Eric Blake <eblake@redhat.com>
Cc: Eduardo Habkost <eduardo@habkost.net>
Cc: Marcel Apfelbaum <marcel.apfelbaum@gmail.com>
Cc: "Philippe Mathieu-Daudé" <philmd@linaro.org>
Cc: Yanan Wang <wangyanan55@huawei.com>
Signed-off-by: David Hildenbrand <david@redhat.com>
---
qapi/machine-target.json | 46 +++++++++++++++++++++++++++-------------
qapi/pragma.json | 3 ---
2 files changed, 31 insertions(+), 18 deletions(-)
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 519adf3220..7883616cce 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -124,11 +124,12 @@
##
# @query-cpu-model-comparison:
#
-# Compares two CPU models, returning how they compare in a specific
-# configuration. The results indicates how both models compare
-# regarding runnability. This result can be used by tooling to make
-# decisions if a certain CPU model will run in a certain configuration
-# or if a compatible CPU model has to be created by baselining.
+# Compares two CPU models, @modela and @modelb, returning how they
+# compare in a specific configuration. The results indicates how
+# both models compare regarding runnability. This result can be
+# used by tooling to make decisions if a certain CPU model will
+# run in a certain configuration or if a compatible CPU model has
+# to be created by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
@@ -154,7 +155,14 @@
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
#
-# Returns: a CpuModelBaselineInfo
+# @modela: description of the first CPU model to compare, referred to as
+# "model A" in CpuModelCompareResult
+#
+# @modelb: description of the second CPU model to compare, referred to as
+# "model B" in CpuModelCompareResult
+#
+# Returns: a CpuModelCompareInfo, describing how both CPU models
+# compare
#
# Errors:
# - if comparing CPU models is not supported
@@ -175,9 +183,9 @@
##
# @query-cpu-model-baseline:
#
-# Baseline two CPU models, creating a compatible third model. The
-# created model will always be a static, migration-safe CPU model (see
-# "static" CPU model expansion for details).
+# Baseline two CPU models, @modela and @modelb, creating a compatible
+# third model. The created model will always be a static,
+# migration-safe CPU model (see "static" CPU model expansion for details).
#
# This interface can be used by tooling to create a compatible CPU
# model out two CPU models. The created CPU model will be identical
@@ -204,7 +212,11 @@
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
#
-# Returns: a CpuModelBaselineInfo
+# @modela: description of the first CPU model to baseline
+#
+# @modelb: description of the second CPU model to baseline
+#
+# Returns: a CpuModelBaselineInfo, describing the baselined CPU model
#
# Errors:
# - if baselining CPU models is not supported
@@ -243,10 +255,10 @@
##
# @query-cpu-model-expansion:
#
-# Expands a given CPU model (or a combination of CPU model +
-# additional options) to different granularities, allowing tooling to
-# get an understanding what a specific CPU model looks like in QEMU
-# under a certain configuration.
+# Expands a given CPU model, @model, (or a combination of CPU model +
+# additional options) to different granularities, specified by
+# @type, allowing tooling to get an understanding what a specific
+# CPU model looks like in QEMU under a certain configuration.
#
# This interface can be used to query the "host" CPU model.
#
@@ -269,7 +281,11 @@
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".
#
-# Returns: a CpuModelExpansionInfo
+# @model: description of the CPU model to expand
+#
+# @type: expansion type, specifying how to expand the CPU model
+#
+# Returns: a CpuModelExpansionInfo, describing the expanded CPU model
#
# Errors:
# - if expanding CPU models is not supported
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 6929ab776e..0d82bc1a03 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -90,9 +90,6 @@
'XDbgBlockGraph',
'YankInstanceType',
'blockdev-reopen',
- 'query-cpu-model-baseline',
- 'query-cpu-model-comparison',
- 'query-cpu-model-expansion',
'query-rocker',
'query-rocker-ports',
'query-stats-schemas',
--
2.43.2
David Hildenbrand <david@redhat.com> writes: > Let's document the parameters of these commands, so we can remove them > from the "documentation-exceptions" list. > > While at it, extend the "Returns:" documentation as well, fixing a wrong > use of CpuModelBaselineInfo vs. CpuModelCompareInfo for > query-cpu-model-comparison. > > Cc: Markus Armbruster <armbru@redhat.com> > Cc: Eric Blake <eblake@redhat.com> > Cc: Eduardo Habkost <eduardo@habkost.net> > Cc: Marcel Apfelbaum <marcel.apfelbaum@gmail.com> > Cc: "Philippe Mathieu-Daudé" <philmd@linaro.org> > Cc: Yanan Wang <wangyanan55@huawei.com> > Signed-off-by: David Hildenbrand <david@redhat.com> > --- > qapi/machine-target.json | 46 +++++++++++++++++++++++++++------------- > qapi/pragma.json | 3 --- > 2 files changed, 31 insertions(+), 18 deletions(-) > > diff --git a/qapi/machine-target.json b/qapi/machine-target.json > index 519adf3220..7883616cce 100644 > --- a/qapi/machine-target.json > +++ b/qapi/machine-target.json > @@ -124,11 +124,12 @@ > ## > # @query-cpu-model-comparison: > # > -# Compares two CPU models, returning how they compare in a specific > -# configuration. The results indicates how both models compare > -# regarding runnability. This result can be used by tooling to make > -# decisions if a certain CPU model will run in a certain configuration > -# or if a compatible CPU model has to be created by baselining. > +# Compares two CPU models, @modela and @modelb, returning how they > +# compare in a specific configuration. The results indicates how > +# both models compare regarding runnability. This result can be > +# used by tooling to make decisions if a certain CPU model will > +# run in a certain configuration or if a compatible CPU model has > +# to be created by baselining. > # > # Usually, a CPU model is compared against the maximum possible CPU > # model of a certain configuration (e.g. the "host" model for KVM). > @@ -154,7 +155,14 @@ > # Some architectures may not support comparing CPU models. s390x > # supports comparing CPU models. > # > -# Returns: a CpuModelBaselineInfo > +# @modela: description of the first CPU model to compare, referred to as > +# "model A" in CpuModelCompareResult > +# > +# @modelb: description of the second CPU model to compare, referred to as > +# "model B" in CpuModelCompareResult > +# > +# Returns: a CpuModelCompareInfo, describing how both CPU models Scratch the comma? > +# compare > # > # Errors: > # - if comparing CPU models is not supported > @@ -175,9 +183,9 @@ > ## > # @query-cpu-model-baseline: > # > -# Baseline two CPU models, creating a compatible third model. The > -# created model will always be a static, migration-safe CPU model (see > -# "static" CPU model expansion for details). > +# Baseline two CPU models, @modela and @modelb, creating a compatible > +# third model. The created model will always be a static, > +# migration-safe CPU model (see "static" CPU model expansion for details). > # > # This interface can be used by tooling to create a compatible CPU > # model out two CPU models. The created CPU model will be identical > @@ -204,7 +212,11 @@ > # Some architectures may not support baselining CPU models. s390x > # supports baselining CPU models. > # > -# Returns: a CpuModelBaselineInfo > +# @modela: description of the first CPU model to baseline > +# > +# @modelb: description of the second CPU model to baseline > +# > +# Returns: a CpuModelBaselineInfo, describing the baselined CPU model Scratch the comma? > # > # Errors: > # - if baselining CPU models is not supported > @@ -243,10 +255,10 @@ > ## > # @query-cpu-model-expansion: > # > -# Expands a given CPU model (or a combination of CPU model + > -# additional options) to different granularities, allowing tooling to > -# get an understanding what a specific CPU model looks like in QEMU > -# under a certain configuration. > +# Expands a given CPU model, @model, (or a combination of CPU model + > +# additional options) to different granularities, specified by > +# @type, allowing tooling to get an understanding what a specific > +# CPU model looks like in QEMU under a certain configuration. > # > # This interface can be used to query the "host" CPU model. > # > @@ -269,7 +281,11 @@ > # Some architectures may not support all expansion types. s390x > # supports "full" and "static". Arm only supports "full". > # > -# Returns: a CpuModelExpansionInfo > +# @model: description of the CPU model to expand > +# > +# @type: expansion type, specifying how to expand the CPU model > +# > +# Returns: a CpuModelExpansionInfo, describing the expanded CPU model > # > # Errors: > # - if expanding CPU models is not supported > diff --git a/qapi/pragma.json b/qapi/pragma.json > index 6929ab776e..0d82bc1a03 100644 > --- a/qapi/pragma.json > +++ b/qapi/pragma.json > @@ -90,9 +90,6 @@ > 'XDbgBlockGraph', > 'YankInstanceType', > 'blockdev-reopen', > - 'query-cpu-model-baseline', > - 'query-cpu-model-comparison', > - 'query-cpu-model-expansion', > 'query-rocker', > 'query-rocker-ports', > 'query-stats-schemas', Reviewed-by: Markus Armbruster <armbru@redhat.com>
>> # >> # Usually, a CPU model is compared against the maximum possible CPU >> # model of a certain configuration (e.g. the "host" model for KVM). >> @@ -154,7 +155,14 @@ >> # Some architectures may not support comparing CPU models. s390x >> # supports comparing CPU models. >> # >> -# Returns: a CpuModelBaselineInfo >> +# @modela: description of the first CPU model to compare, referred to as >> +# "model A" in CpuModelCompareResult >> +# >> +# @modelb: description of the second CPU model to compare, referred to as >> +# "model B" in CpuModelCompareResult >> +# >> +# Returns: a CpuModelCompareInfo, describing how both CPU models > > Scratch the comma? Agreed to both. Do you want to fixup when applying or do you prefer a v2? Thanks! > > Reviewed-by: Markus Armbruster <armbru@redhat.com> > -- Cheers, David / dhildenb
David Hildenbrand <david@redhat.com> writes: >>> # >>> # Usually, a CPU model is compared against the maximum possible CPU >>> # model of a certain configuration (e.g. the "host" model for KVM). >>> @@ -154,7 +155,14 @@ >>> # Some architectures may not support comparing CPU models. s390x >>> # supports comparing CPU models. >>> # >>> -# Returns: a CpuModelBaselineInfo >>> +# @modela: description of the first CPU model to compare, referred to as >>> +# "model A" in CpuModelCompareResult >>> +# >>> +# @modelb: description of the second CPU model to compare, referred to as >>> +# "model B" in CpuModelCompareResult >>> +# >>> +# Returns: a CpuModelCompareInfo, describing how both CPU models >> >> Scratch the comma? > > Agreed to both. Do you want to fixup when applying or do you prefer a v2? Happy to fix it up myself, thanks! > Thanks! > >> Reviewed-by: Markus Armbruster <armbru@redhat.com>
© 2016 - 2024 Red Hat, Inc.