diff mbox series

[v2,1/2] Deprecate QMP `cpu-add`

Message ID 20180925160248.30801-2-kchamart@redhat.com (mailing list archive)
State New, archived
Headers show
Series Deprecate QMP `cpu-add`; document vCPU hotplug | expand

Commit Message

Kashyap Chamarthy Sept. 25, 2018, 4:02 p.m. UTC
The intended functionality of QMP `cpu-add` is replaced with
`device_add` (and `query-hotpluggable-cpus`).  So let's deprecate
`cpu-add`.

A complete example of vCPU hotplug with the recommended way (using
`device_add`) is provided as part of a seperate docs patch.

Suggested-by: Eduardo Habkost <ehabkost@redhat.com
Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
---
 qapi/misc.json       | 8 +++++++-
 qemu-deprecated.texi | 5 +++++
 2 files changed, 12 insertions(+), 1 deletion(-)

Comments

Thomas Huth Oct. 1, 2018, 9:28 a.m. UTC | #1
On 2018-09-25 18:02, Kashyap Chamarthy wrote:
> The intended functionality of QMP `cpu-add` is replaced with
> `device_add` (and `query-hotpluggable-cpus`).  So let's deprecate
> `cpu-add`.
> 
> A complete example of vCPU hotplug with the recommended way (using
> `device_add`) is provided as part of a seperate docs patch.
> 
> Suggested-by: Eduardo Habkost <ehabkost@redhat.com
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
> ---
>  qapi/misc.json       | 8 +++++++-
>  qemu-deprecated.texi | 5 +++++
>  2 files changed, 12 insertions(+), 1 deletion(-)
> 
> diff --git a/qapi/misc.json b/qapi/misc.json
> index d450cfef21..6479b8f8a6 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -1104,7 +1104,11 @@
>  ##
>  # @cpu-add:
>  #
> -# Adds CPU with specified ID
> +# Adds CPU with specified ID.
> +#
> +# Notes: This command is deprecated.  The `device_add` command should be

s/Notes/Note/ ?

> +#        used instead.  See the `query-hotpluggable-cpus` command for
> +#        details.
>  #
>  # @id: ID of CPU to be created, valid values [0..max_cpus)
>  #
> @@ -3213,6 +3217,8 @@
>  ##
>  # @query-hotpluggable-cpus:
>  #
> +# TODO: Better documentation; currently there is none.
> +#
>  # Returns: a list of HotpluggableCPU objects.
>  #
>  # Since: 2.7
> diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
> index 1b9c007f12..c86924ad9a 100644
> --- a/qemu-deprecated.texi
> +++ b/qemu-deprecated.texi
> @@ -155,6 +155,11 @@ The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
>  The ``arch'' output member of the ``query-cpus-fast'' command is
>  replaced by the ``target'' output member.
>  
> +@subsection cpu-add (since 3.1)
> +
> +Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
> +documentation of ``query-hotpluggable-cpus'' for additional details.
> +
>  @section System emulator devices
>  
>  @subsection ivshmem (since 2.6.0)
> 

Do you plan to keep the "cpu-add" HMP command? hmp_cpu_add() currently
is only a wrapper for qmp_cpu_add(), so if you plan to get rid of the
QMP command, it might make sense to deprecate the HMP command in the
same breath, too.

 Thomas
Kashyap Chamarthy Oct. 1, 2018, 12:40 p.m. UTC | #2
On Mon, Oct 01, 2018 at 11:28:17AM +0200, Thomas Huth wrote:
> On 2018-09-25 18:02, Kashyap Chamarthy wrote:

[...]

> > +++ b/qapi/misc.json
> > @@ -1104,7 +1104,11 @@
> >  ##
> >  # @cpu-add:
> >  #
> > -# Adds CPU with specified ID
> > +# Adds CPU with specified ID.
> > +#
> > +# Notes: This command is deprecated.  The `device_add` command should be
> 
> s/Notes/Note/ ?

Yeah, first I wrote the singular.  But went with plural as I saw it as
it was the 'majority' pattern:

    $> git grep "Note:" qapi/misc.json | wc -l
    13
    $> git grep "Notes:" qapi/misc.json | wc -l
    18

Maybe people use the plural, "Notes", as they can add multiple entries.

[...]

> Do you plan to keep the "cpu-add" HMP command? hmp_cpu_add() currently
> is only a wrapper for qmp_cpu_add(), so if you plan to get rid of the
> QMP command, it might make sense to deprecate the HMP command in the
> same breath, too.

Yeah, I did think about deprecating the HMP variant; and even brought it
up with Dave Gilbert the other day.  He pointed out an example commit of
yours (559964a1) on how to mark an HMP command as deprecated. :-)

Thanks for the reminder.  Will add it as a TODO for the next revision.
Markus Armbruster Oct. 8, 2018, 1:29 p.m. UTC | #3
Kashyap Chamarthy <kchamart@redhat.com> writes:

> On Mon, Oct 01, 2018 at 11:28:17AM +0200, Thomas Huth wrote:
>> On 2018-09-25 18:02, Kashyap Chamarthy wrote:
>
> [...]
>
>> > +++ b/qapi/misc.json
>> > @@ -1104,7 +1104,11 @@
>> >  ##
>> >  # @cpu-add:
>> >  #
>> > -# Adds CPU with specified ID
>> > +# Adds CPU with specified ID.
>> > +#
>> > +# Notes: This command is deprecated.  The `device_add` command should be
>> 
>> s/Notes/Note/ ?
>
> Yeah, first I wrote the singular.  But went with plural as I saw it as
> it was the 'majority' pattern:
>
>     $> git grep "Note:" qapi/misc.json | wc -l
>     13
>     $> git grep "Notes:" qapi/misc.json | wc -l
>     18

Not exactly overwhelming majority :)

> Maybe people use the plural, "Notes", as they can add multiple entries.

For what it's worth, our doc generator recognizes both.

[...]
diff mbox series

Patch

diff --git a/qapi/misc.json b/qapi/misc.json
index d450cfef21..6479b8f8a6 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -1104,7 +1104,11 @@ 
 ##
 # @cpu-add:
 #
-# Adds CPU with specified ID
+# Adds CPU with specified ID.
+#
+# Notes: This command is deprecated.  The `device_add` command should be
+#        used instead.  See the `query-hotpluggable-cpus` command for
+#        details.
 #
 # @id: ID of CPU to be created, valid values [0..max_cpus)
 #
@@ -3213,6 +3217,8 @@ 
 ##
 # @query-hotpluggable-cpus:
 #
+# TODO: Better documentation; currently there is none.
+#
 # Returns: a list of HotpluggableCPU objects.
 #
 # Since: 2.7
diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
index 1b9c007f12..c86924ad9a 100644
--- a/qemu-deprecated.texi
+++ b/qemu-deprecated.texi
@@ -155,6 +155,11 @@  The ``query-cpus'' command is replaced by the ``query-cpus-fast'' command.
 The ``arch'' output member of the ``query-cpus-fast'' command is
 replaced by the ``target'' output member.
 
+@subsection cpu-add (since 3.1)
+
+Use ``device_add'' for hotplugging vCPUs instead of ``cpu-add''.  See
+documentation of ``query-hotpluggable-cpus'' for additional details.
+
 @section System emulator devices
 
 @subsection ivshmem (since 2.6.0)