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..fbee1e6d34 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -1104,7 +1104,7 @@
 ##
 # @cpu-add:
 #
-# Adds CPU with specified ID
+# Adds CPU with specified ID.
 #
 # @id: ID of CPU to be created, valid values [0..max_cpus)
 #
@@ -1112,6 +1112,10 @@
 #
 # Since: 1.5
 #
+# Note: This command is deprecated.  The `device_add` command should be
+#       used instead.  See the `query-hotpluggable-cpus` command for
+#       details.
+#
 # Example:
 #
 # -> { "execute": "cpu-add", "arguments": { "id": 2 } }
@@ -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)
-- 
2.17.1

On 2018-10-30 13:35, 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>
> ---
> ---

Duplicated "---" line ... but I think this should not be a problem for
the usual tools.

Reviewed-by: Thomas Huth <thuth@redhat.com>

On 2018-10-30 13:35, 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>
> ---
[...]
> 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)

 Hi Kashyap,

could you please send a follow-up patch to change this into 4.0 now?

Please also provide a patch to add the HMP command to
qemu-deprecated.texi, too.

 Thanks,
  Thomas

On Thu, Dec 13, 2018 at 07:38:03AM +0100, Thomas Huth wrote:
> On 2018-10-30 13:35, 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>
> > ---
> [...]
> > 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)
> 
>  Hi Kashyap,
> 
> could you please send a follow-up patch to change this into 4.0 now?

Ah, sure.

> Please also provide a patch to add the HMP command to
> qemu-deprecated.texi, too.

Is it okay if both the above are done in the same patch?  Since they're
related.  Or am I missing a reason to do them separately?

-- 
/kashyap

On Thu, Dec 13, 2018 at 12:05:05PM +0100, Kashyap Chamarthy wrote:
> On Thu, Dec 13, 2018 at 07:38:03AM +0100, Thomas Huth wrote:
> > On 2018-10-30 13:35, Kashyap Chamarthy wrote:

[...]

> > > 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)
> > 
> >  Hi Kashyap,
> > 
> > could you please send a follow-up patch to change this into 4.0 now?
> 
> Ah, sure.
> 
> > Please also provide a patch to add the HMP command to
> > qemu-deprecated.texi, too.
> 
> Is it okay if both the above are done in the same patch?  Since they're
> related.  Or am I missing a reason to do them separately?

Okay, please disregard the above; Dave Gilbert reminded that it's
preferable that I send two separate patches (part of a "series"), as
they're different things.

-- 
/kashyap