| Message ID | 20180925160248.30801-2-kchamart@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | Deprecate QMP `cpu-add`; document vCPU hotplug | expand |
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
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.
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 --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)
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(-)