xref: /openbmc/qemu/docs/system/cpu-hotplug.rst (revision 9e4cc917) 
1===================
2Virtual CPU hotplug
3===================
4
5A complete example of vCPU hotplug (and hot-unplug) using QMP
6``device_add`` and ``device_del``.
7
8vCPU 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
117vCPU hot-unplug
118---------------
119
120From 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.
141