docs/system/cpu-hotplug.rst

   1 ===================
   2 Virtual CPU hotplug
   3 ===================
   4
   5 A complete example of vCPU hotplug (and hot-unplug) using QMP
   6 ``device_add`` and ``device_del``.
   7
   8 vCPU hotplug
   9 ------------
  10
  11 (1) Launch QEMU as follows (note that the "maxcpus" is mandatory to
  12     allow vCPU hotplug)::
  13
  14       $ qemu-system-x86_64 -display none -no-user-config -m 2048 \
  15           -nodefaults -monitor stdio -machine pc,accel=kvm,usb=off \
  16           -smp 1,maxcpus=2 -cpu IvyBridge-IBRS \
  17           -qmp unix:/tmp/qmp-sock,server=on,wait=off
  18
  19 (2) Run 'qmp-shell' (located in the source tree, under: "scripts/qmp/)
  20     to connect to the just-launched QEMU::
  21
  22       $> ./qmp-shell -p -v /tmp/qmp-sock
  23       [...]
  24       (QEMU)
  25
  26 (3) Find out which CPU types could be plugged, and into which sockets::
  27
  28       (QEMU) query-hotpluggable-cpus
  29       {
  30           "execute": "query-hotpluggable-cpus",
  31           "arguments": {}
  32       }
  33       {
  34           "return": [
  35               {
  36                   "props": {
  37                       "core-id": 1,
  38                       "socket-id": 0,
  39                       "thread-id": 0
  40                   },
  41                   "type": "IvyBridge-IBRS-x86_64-cpu",
  42                   "vcpus-count": 1
  43               },
  44               {
  45                   "props": {
  46                       "core-id": 0,
  47                       "socket-id": 0,
  48                       "thread-id": 0
  49                   },
  50                   "qom-path": "/machine/unattached/device[0]",
  51                   "type": "IvyBridge-IBRS-x86_64-cpu",
  52                   "vcpus-count": 1
  53               }
  54           ]
  55       }
  56       (QEMU)
  57
  58 (4) The ``query-hotpluggable-cpus`` command returns an object for CPUs
  59     that are present (containing a "qom-path" member) or which may be
  60     hot-plugged (no "qom-path" member).  From its output in step (3), we
  61     can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0 core 0,
  62     while hot-plugging a CPU into socket 0 core 1 requires passing the listed
  63     properties to QMP ``device_add``::
  64
  65       (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=0 core-id=1 thread-id=0
  66       {
  67           "execute": "device_add",
  68           "arguments": {
  69               "core-id": 1,
  70               "driver": "IvyBridge-IBRS-x86_64-cpu",
  71               "id": "cpu-2",
  72               "socket-id": 0,
  73               "thread-id": 0
  74           }
  75       }
  76       {
  77           "return": {}
  78       }
  79       (QEMU)
  80
  81 (5) Optionally, run QMP ``query-cpus-fast`` for some details about the
  82     vCPUs::
  83
  84       (QEMU) query-cpus-fast
  85       {
  86           "arguments": {}
  87           "execute": "query-cpus-fast",
  88       }
  89       {
  90           "return": [
  91               {
  92                   "cpu-index": 0,
  93                   "props": {
  94                       "core-id": 0,
  95                       "socket-id": 0,
  96                       "thread-id": 0
  97                   },
  98                   "qom-path": "/machine/unattached/device[0]",
  99                   "target": "x86_64",
 100                   "thread-id": 28957
 101               },
 102               {
 103                   "cpu-index": 1,
 104                   "props": {
 105                       "core-id": 1,
 106                       "socket-id": 0,
 107                       "thread-id": 0
 108                   },
 109                   "qom-path": "/machine/peripheral/cpu-2",
 110                   "target": "x86_64",
 111                   "thread-id": 29095
 112               }
 113           ]
 114       }
 115       (QEMU)
 116
 117 vCPU hot-unplug
 118 ---------------
 119
 120 From the 'qmp-shell', invoke the QMP ``device_del`` command::
 121
 122       (QEMU) device_del id=cpu-2
 123       {
 124           "arguments": {
 125               "id": "cpu-2"
 126           }
 127           "execute": "device_del",
 128       }
 129       {
 130           "return": {}
 131       }
 132       (QEMU)
 133
 134 .. note::
 135     vCPU hot-unplug requires guest cooperation; so the ``device_del``
 136     command above does not guarantee vCPU removal -- it's a "request to
 137     unplug".  At this point, the guest will get a System Control
 138     Interrupt (SCI) and calls the ACPI handler for the affected vCPU
 139     device.  Then the guest kernel will bring the vCPU offline and tell
 140     QEMU to unplug it.