[v4] docs: add cpu-hotplug.txt

Commit Message

Dou Liyang Aug. 16, 2016, 3:07 a.m. UTC

This document describes how to use cpu hotplug in QEMU.

Signed-off-by: Andrew Jones <[e-mail]>
Signed-off-by: Dou Liyang <[e-mail]>
---
Change log v3 -> v4
  From David's advice
    1. add spapr examples
    2. Fix some comment
  From drew's advice
    1. Fix some syntax

Change log v2 -> v3:
  From drew's advice:
    1. modify the examples.
    2. Fix some syntax.

Change log v1 -> v2:
  From Fam's advice:
    1. Fix some comment.

Change log v1:
  From Igor's advice:
    1. Remove any mentioning of apic-id from the document.
    2. Remove the "device_del qom_path" from the CPU hot-unplug.
    3. Fix some comment.

 docs/cpu-hotplug.txt | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 docs/cpu-hotplug.txt

Comments

Bharata B Rao Aug. 16, 2016, 3:31 a.m. UTC | #1

On Tue, Aug 16, 2016 at 11:07:41AM +0800, Dou Liyang wrote:
> This document describes how to use cpu hotplug in QEMU.
> 
> Signed-off-by: Andrew Jones <[e-mail]>
> Signed-off-by: Dou Liyang <[e-mail]>
> ---
> Change log v3 -> v4
>   From David's advice
>     1. add spapr examples
>     2. Fix some comment
>   From drew's advice
>     1. Fix some syntax
> 
> Change log v2 -> v3:
>   From drew's advice:
>     1. modify the examples.
>     2. Fix some syntax.
> 
> Change log v1 -> v2:
>   From Fam's advice:
>     1. Fix some comment.
> 
> Change log v1:
>   From Igor's advice:
>     1. Remove any mentioning of apic-id from the document.
>     2. Remove the "device_del qom_path" from the CPU hot-unplug.
>     3. Fix some comment.
> 
>  docs/cpu-hotplug.txt | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 132 insertions(+)
>  create mode 100644 docs/cpu-hotplug.txt
> 
> diff --git a/docs/cpu-hotplug.txt b/docs/cpu-hotplug.txt
> new file mode 100644
> index 0000000..0c1bfe9
> --- /dev/null
> +++ b/docs/cpu-hotplug.txt
> @@ -0,0 +1,132 @@
> +QEMU CPU hotplug
> +================
> +
> +This document explains how to use the CPU hotplug feature in QEMU,
> +which regards the CPU as a device, using -device/device_add and
> +device_del.
> +
> +QEMU support was merged for 2.7.
> +
> +Guest support is required for CPU hotplug to work.
> +
> +CPU hot-plug
> +------------
> +
> +In order to be able to hotplug CPUs, QEMU has to be told the maximum
> +number of CPUs which the guest can have. This is done at startup time
> +by means of the -smp command-line option, which has the following
> +format:
> +
> + -smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads]
> +	[,sockets=sockets]
> +
> +Where,
> +
> + - "cpus"    sets the number of CPUs to 'n' [default=1].
> + - "maxcpus" sets the maximum number of CPUs, including offline VCPUs
> +   for hotplug.
> + - "sockets" sets the number of discrete sockets in the system.
> + - "cores"   sets the number of CPU cores on one socket.
> + - "threads" sets the number of threads on one CPU core.
> +
> +For example, the following command-line:
> +
> + qemu [...] -smp 3,maxcpus=8,sockets=2,cores=2,threads=2

This is not a valid topology on sPAPR. In the documentation, why not have
a bit more generic topology that is likely to work for most archs ?

Like -smp 4,maxcpus=8,sockets=2,cores=2,threads=2.

Regards,
Bharata.

Dou Liyang Aug. 16, 2016, 3:42 a.m. UTC | #2

Hi Bharata,

At 08/16/2016 11:31 AM, Bharata B Rao wrote:
> On Tue, Aug 16, 2016 at 11:07:41AM +0800, Dou Liyang wrote:
>> This document describes how to use cpu hotplug in QEMU.
>>
>> Signed-off-by: Andrew Jones <[e-mail]>
>> Signed-off-by: Dou Liyang <[e-mail]>
>> ---
>> Change log v3 -> v4
>>   From David's advice
>>     1. add spapr examples
>>     2. Fix some comment
>>   From drew's advice
>>     1. Fix some syntax
>> +
>> +For example, the following command-line:
>> +
>> + qemu [...] -smp 3,maxcpus=8,sockets=2,cores=2,threads=2
>
> This is not a valid topology on sPAPR. In the documentation, why not have
> a bit more generic topology that is likely to work for most archs ?
>
> Like -smp 4,maxcpus=8,sockets=2,cores=2,threads=2.

Yes, I got it.
I will change it and check other examples.

Thanks,
Dou

Patch

diff --git a/docs/cpu-hotplug.txt b/docs/cpu-hotplug.txt
new file mode 100644
index 0000000..0c1bfe9
--- /dev/null
+++ b/docs/cpu-hotplug.txt
@@ -0,0 +1,132 @@ 
+QEMU CPU hotplug
+================
+
+This document explains how to use the CPU hotplug feature in QEMU,
+which regards the CPU as a device, using -device/device_add and
+device_del.
+
+QEMU support was merged for 2.7.
+
+Guest support is required for CPU hotplug to work.
+
+CPU hot-plug
+------------
+
+In order to be able to hotplug CPUs, QEMU has to be told the maximum
+number of CPUs which the guest can have. This is done at startup time
+by means of the -smp command-line option, which has the following
+format:
+
+ -smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads]
+	[,sockets=sockets]
+
+Where,
+
+ - "cpus"    sets the number of CPUs to 'n' [default=1].
+ - "maxcpus" sets the maximum number of CPUs, including offline VCPUs
+   for hotplug.
+ - "sockets" sets the number of discrete sockets in the system.
+ - "cores"   sets the number of CPU cores on one socket.
+ - "threads" sets the number of threads on one CPU core.
+
+For example, the following command-line:
+
+ qemu [...] -smp 3,maxcpus=8,sockets=2,cores=2,threads=2
+
+creates a guest with 3 VCPUs and supports up to 8 VCPUs. The CPU
+topology is sockets (2) * cores (2) * threads (2) and can't be
+greater than maxcpus. When the guest finishes loading, the guest
+will see 3 VCPUs. More on this below.
+
+Query available CPU objects
+---------------------------
+
+To add a VCPUs, it must be identified by socket-id, core-id, and/or
+thread-id parameters.
+
+Before adding the VCPUs, we should know those topology parameters,
+so that we can find the available location (socket,core,thread) for
+a new VCPU.
+
+Using the corresponding HMP command "info hotpluggable-cpus" to obtain
+them.
+
+For example, the following command-line:
+
+  (qemu) info hotpluggable-cpus
+
+lists the hotpluggable CPUs including "CPUInstance Properties" for
+hotplugging. Such as this:
+
+  ...
+  type: "qemu64-x86_64-cpu"
+  vcpus_count: "1"
+  CPUInstance Properties:
+    socket-id: "0"
+    core-id: "1"
+    thread-id: "0"
+  ...
+
+Or
+
+  ...
+  type: "POWER7_v2.3-spapr-cpu-core"
+  vcpus_count: "1"
+  CPUInstance Properties:
+    core-id: "2"
+  ...
+
+Different platforms may have different "CPUInstance Properties".
+
+Hotplug CPUs
+------------
+
+A monitor command can be used to hotplug CPUs:
+
+ - "device_add": creates a CPU device and inserts it into the
+	specific location.
+
+For example, the following command adds a VCPU, which has the id cpu1,
+to a specific location in the topology (socket=0,core=1,thread=1):
+
+  (qemu) device_add qemu64-x86_64-cpu,id=cpu1,socket-id=0,core-id=1,thread-id=1
+
+Where,
+
+ - "qemu64-x86_64-cpu" is the CPU model.
+ - "id" is the unique identifier in the device set.
+ - "socket-id/core-id/thread-id" represent the designated location,
+   which is obtained form the above possible list of CPUs.
+
+It's also possible to start a guest with a cpu cold-plugged into a
+specific location (socket,core,thread).
+
+In the following command line example, a guest which has 3 VCPUs is
+created:
+
+ qemu  [...] -smp 1,maxcpus=8,sockets=2,cores=2,threads=2 \
+	-device qemu64-x86_64-cpu,id=cpu1,socket-id=1, \
+	core-id=1,thread-id=0 \
+	-device qemu64-x86_64-cpu,id=cpu2,socket-id=1, \
+	core-id=1,thread-id=1 \
+
+Two VCPUs are cold-plugged by "-device" parameter, which are in the
+same socket and core, but with different thread-ids. After that, the
+guest has an additional five VCPUs to be hot-plugged when needed.
+
+CPU hot-unplug
+--------------
+
+In order to be able to hot unplug a CPU device, QEMU removes CPU
+devices by using the ids which were assigned when hotplugging the
+CPU device.
+
+A monitor command can be used to hot unplug CPUs:
+
+ - "device_del": deletes a CPU device
+
+For example, assuming that the CPU device with id "cpu1" exists,
+then the following command tries to remove it.
+
+  (qemu) device_del cpu1
+