MAINTAINERS: Make section QOM cover hw/core/*bus.c as well
[qemu/armbru.git] / docs / cpu-hotplug.rst
blobd0b06403f1958704e1b36a7e3606b1488966188b
1 ===================
2 Virtual CPU hotplug
3 ===================
5 A complete example of vCPU hotplug (and hot-unplug) using QMP
6 ``device_add`` and ``device_del``.
8 vCPU hotplug
9 ------------
11 (1) Launch QEMU as follows (note that the "maxcpus" is mandatory to
12     allow vCPU hotplug)::
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,nowait
19 (2) Run 'qmp-shell' (located in the source tree, under: "scripts/qmp/)
20     to connect to the just-launched QEMU::
22       $> ./qmp-shell -p -v /tmp/qmp-sock
23       [...]
24       (QEMU)
26 (3) Find out which CPU types could be plugged, and into which sockets::
28       (QEMU) query-hotpluggable-cpus
29       {
30           "execute": "query-hotpluggable-cpus",
31           "arguments": {}
32       }
33       {
34           "return": [
35               {
36                   "type": "IvyBridge-IBRS-x86_64-cpu",
37                   "vcpus-count": 1,
38                   "props": {
39                       "socket-id": 1,
40                       "core-id": 0,
41                       "thread-id": 0
42                   }
43               },
44               {
45                   "qom-path": "/machine/unattached/device[0]",
46                   "type": "IvyBridge-IBRS-x86_64-cpu",
47                   "vcpus-count": 1,
48                   "props": {
49                       "socket-id": 0,
50                       "core-id": 0,
51                       "thread-id": 0
52                   }
53               }
54           ]
55       }
56       (QEMU)
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,
62     while hot-plugging a CPU into socket 1 requires passing the listed
63     properties to QMP ``device_add``::
65       (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0
66       {
67           "execute": "device_add",
68           "arguments": {
69               "socket-id": 1,
70               "driver": "IvyBridge-IBRS-x86_64-cpu",
71               "id": "cpu-2",
72               "core-id": 0,
73               "thread-id": 0
74           }
75       }
76       {
77           "return": {}
78       }
79       (QEMU)
81 (5) Optionally, run QMP `query-cpus-fast` for some details about the
82     vCPUs::
84       (QEMU) query-cpus-fast
85       {
86           "execute": "query-cpus-fast",
87           "arguments": {}
88       }
89       {
90           "return": [
91               {
92                   "qom-path": "/machine/unattached/device[0]",
93                   "target": "x86_64",
94                   "thread-id": 11534,
95                   "cpu-index": 0,
96                   "props": {
97                       "socket-id": 0,
98                       "core-id": 0,
99                       "thread-id": 0
100                   },
101                   "arch": "x86"
102               },
103               {
104                   "qom-path": "/machine/peripheral/cpu-2",
105                   "target": "x86_64",
106                   "thread-id": 12106,
107                   "cpu-index": 1,
108                   "props": {
109                       "socket-id": 1,
110                       "core-id": 0,
111                       "thread-id": 0
112                   },
113                   "arch": "x86"
114               }
115           ]
116       }
117       (QEMU)
119 vCPU hot-unplug
120 ---------------
122 From the 'qmp-shell', invoke the QMP ``device_del`` command::
124       (QEMU) device_del id=cpu-2
125       {
126           "execute": "device_del",
127           "arguments": {
128               "id": "cpu-2"
129           }
130       }
131       {
132           "return": {}
133       }
134       (QEMU)
136 .. note::
137     vCPU hot-unplug requires guest cooperation; so the ``device_del``
138     command above does not guarantee vCPU removal -- it's a "request to
139     unplug".  At this point, the guest will get a System Control
140     Interrupt (SCI) and calls the ACPI handler for the affected vCPU
141     device.  Then the guest kernel will bring the vCPU offline and tell
142     QEMU to unplug it.