[Qemu-devel] [PATCH] Deprecate QMP `cpu-add`

[Kashyap Chamarthy]

The intended functionality of QMP command `cpu-add` is replaced by
`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`:

(1) Launch QEMU as follows (note that the "maxcpus" is mandatory to
    allow vCPU hotplug):

    $ qemu-system-x86_64 -display none -no-user-config -m 2048 \
        -nodefaults -monitor stdio -machine pc,accel=kvm,usb=off \
        -smp 1,maxcpus=2 -cpu IvyBridge-IBRS \
        -blockdev 
node-name=node-Base,driver=qcow2,file.driver=file,file.filename=./base.qcow2 \
        -device virtio-blk,drive=node-Base,id=virtio0 -qmp 
unix:/tmp/qmp-sock,server,nowait

(2) Run 'qmp-shell' (located in the source tree) to connect to the
    just-launched QEMU:

    $> ./qmp/qmp-shell -p -v /tmp/qmp-sock
    [...]
    (QEMU)

(3) Check which socket is free to allow hotplugging a CPU:

    (QEMU) query-hotpluggable-cpus
    {
      "execute":"query-hotpluggable-cpus",
      "arguments":{

      }
    }
    {
      "return":[
        {
          "type":"IvyBridge-IBRS-x86_64-cpu",
          "vcpus-count":1,
          "props":{
            "socket-id":1,
            "core-id":0,
            "thread-id":0
          }
        },
        {
          "qom-path":"/machine/unattached/device[0]",
          "type":"IvyBridge-IBRS-x86_64-cpu",
          "vcpus-count":1,
          "props":{
            "socket-id":0,
            "core-id":0,
            "thread-id":0
          }
        }
      ]
    }
    (QEMU)

(4) We can see that socket 1 is free, so use `device_add` to hotplug
    "IvyBridge-IBRS-x86_64-cpu":

    (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 
core-id=0 thread-id=0
    {
        "execute": "device_add",
        "arguments": {
            "socket-id": 1,
            "driver": "IvyBridge-IBRS-x86_64-cpu",
            "id": "cpu-2",
            "core-id": 0,
            "thread-id": 0
        }
    }
    {
        "return": {}
    }
    (QEMU)

(5) Optionally, run QMP `query-cpus-fast` for some details about the
    vCPUs.

Suggested-by: Eduardo Habkost <address@hidden
Signed-off-by: Kashyap Chamarthy <address@hidden>
---
Also shouldn't we update tests/cpu-plug-test.c to make it use
`device_add`.  Can take a stab at it, if you'd like me to.
---
 qapi/misc.json       | 6 +++++-
 qemu-deprecated.texi | 5 +++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/qapi/misc.json b/qapi/misc.json
index d450cfef21..83bc9ad0ee 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)
 #
diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
index 1b9c007f12..9c6d70d43a 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.
 
address@hidden cpu-add (since 3.1)
+
+The intended functionality of ``cpu-add'' command, which is the ability
+to hot-plug vCPUs, can now be achieved by the ``device_add'' command.
+
 @section System emulator devices
 
 @subsection ivshmem (since 2.6.0)
-- 
2.17.1