| 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. |