diff mbox

[v6] docs: add cpu-hotplug.txt

Message ID 1471417266-22678-1-git-send-email-douly.fnst@cn.fujitsu.com (mailing list archive)
State New, archived
Headers show

Commit Message

Dou Liyang Aug. 17, 2016, 7:01 a.m. UTC 
This document describes how to use cpu hotplug in QEMU.

Signed-off-by: Dou Liyang <douly.fnst@cn.fujitsu.com>
---
Change log v5 -> v6
  From drew's advice
    1. Fix some spelling and grammar mistakes

Change log v4 -> v5
  1. add an example for sPAPR
  From Bharata's advice
    1. Fix the examples

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 | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 docs/cpu-hotplug.txt

Comments

Andrew Jones Aug. 17, 2016, 1:39 p.m. UTC | #1 
On Wed, Aug 17, 2016 at 03:01:06PM +0800, Dou Liyang wrote:
> This document describes how to use cpu hotplug in QEMU.
> 
> Signed-off-by: Dou Liyang <douly.fnst@cn.fujitsu.com>
> ---
> Change log v5 -> v6
>   From drew's advice
>     1. Fix some spelling and grammar mistakes
> 
> Change log v4 -> v5
>   1. add an example for sPAPR
>   From Bharata's advice
>     1. Fix the examples
> 
> 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 | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 140 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..c9a16f6
> --- /dev/null
> +++ b/docs/cpu-hotplug.txt
> @@ -0,0 +1,140 @@
> +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,

should be lowercase, '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 4,maxcpus=8,sockets=2,cores=2,threads=2
> +
> +creates a guest with 4 VCPUs and supports up to 8 VCPUs. The CPU topology
> +is sockets (2) * cores (2) * threads (2) and should compute a number of
> +slots exactly equal to maxcpus. A computed number of slots greater than
> +maxcpus will result in error. When the guest finishes loading, the guest
> +will see 4 VCPUs. More of this below.
> +
> +Query available CPU objects
> +---------------------------
> +
> +To add a VCPU, it must be identified by socket-id, core-id, and/or
> +thread-id parameters.
> +
> +Before adding the VCPU, we should know the topology parameters,so

need space after ,

> +that we can find the available location (socket,core,thread) for a
> +new VCPU.
> +
> +Use the HMP command "info hotpluggable-cpus" to obtain them, for example:
> +
> +  (qemu) info hotpluggable-cpus
> +
> +lists all hot-pluggable CPUs. Such as this:
> +
> +  ...
> +  type: "qemu64-x86_64-cpu"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    socket-id: "1"
> +    core-id: "0"
> +    thread-id: "0"
> +  ...
> +
> +Or

should be lowercase, 'or'

> +
> +  ...
> +  type: "POWER7_v2.3-spapr-cpu-core"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    core-id: "2"
> +  ...
> +
> +Different platforms may have different "CPUInstance Properties", which
> +will be used in hot-plugging below.
> +
> +Hotplug CPUs
> +------------
> +
> +A monitor command may 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=1,core=0,thread=0):
> +
> +  (qemu) device_add qemu64-x86_64-cpu,id=cpu1,socket-id=1,core-id=0,thread-id=0
> +
> +Where,

should be lowercase, '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 from 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

4 VCPUs

> +created:
> +
> + qemu  [...] -smp 2,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 the "-device" parameter, which are in
> +the same socket and core, but with different thread-ids. After that,
> +the guest has an additional four VCPUs available for hot-plug when
> +needed.
> +
> +The above example is for an x86 machine type. The topology parameters
> +and resulting number of online VCPUs may not be suitable for other
> +platforms. The "CPUInstance Properties" output described above lists
> +the valid topology parameters.
> +
> +For example, the following command adds a VCPU in an sPAPR hardware
> +system:
> +
> +  (qemu) device_add POWER7_v2.3-spapr-cpu-core,id=cpu1,core-id=2
> +
> +CPU hot-unplug
> +--------------
> +
> +In order to be able to hot unplug a CPU device, QEMU removes the
> +device by using the id which was assigned when hotplugging it.
> +
> +A monitor command may 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
> +
> -- 
> 2.5.5

Only a couple of tweaks remain (most important is the 4 not 3 VCPUs,
in one example). Anyway, looks good, so

Reviewed-by: Andrew Jones <drjones@redhat.com>
Bharata B Rao Aug. 17, 2016, 1:47 p.m. UTC | #2 
On Wed, Aug 17, 2016 at 03:01:06PM +0800, Dou Liyang wrote:
> This document describes how to use cpu hotplug in QEMU.
> 
> Signed-off-by: Dou Liyang <douly.fnst@cn.fujitsu.com>
> ---
> Change log v5 -> v6
>   From drew's advice
>     1. Fix some spelling and grammar mistakes
> 
> Change log v4 -> v5
>   1. add an example for sPAPR
>   From Bharata's advice
>     1. Fix the examples
> 
> 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 | 140 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 140 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..c9a16f6
> --- /dev/null
> +++ b/docs/cpu-hotplug.txt
> @@ -0,0 +1,140 @@
> +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 4,maxcpus=8,sockets=2,cores=2,threads=2
> +
> +creates a guest with 4 VCPUs and supports up to 8 VCPUs. The CPU topology
> +is sockets (2) * cores (2) * threads (2) and should compute a number of
> +slots exactly equal to maxcpus. A computed number of slots greater than
> +maxcpus will result in error. When the guest finishes loading, the guest
> +will see 4 VCPUs. More of this below.
> +
> +Query available CPU objects
> +---------------------------
> +
> +To add a VCPU, it must be identified by socket-id, core-id, and/or
> +thread-id parameters.
> +
> +Before adding the VCPU, we should know the topology parameters,so
> +that we can find the available location (socket,core,thread) for a
> +new VCPU.
> +
> +Use the HMP command "info hotpluggable-cpus" to obtain them, for example:
> +
> +  (qemu) info hotpluggable-cpus
> +
> +lists all hot-pluggable CPUs. Such as this:

lists all CPUs including the present and possible hot-pluggable CPUs.

> +
> +  ...
> +  type: "qemu64-x86_64-cpu"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    socket-id: "1"
> +    core-id: "0"
> +    thread-id: "0"
> +  ...
> +
> +Or
> +
> +  ...
> +  type: "POWER7_v2.3-spapr-cpu-core"
> +  vcpus_count: "1"
> +  CPUInstance Properties:
> +    core-id: "2"

There is another property called "qom_path" which if present indicates
that the listed CPU is already present or plugged-in. Hotpluggable CPUs
are those which don't have "qom_path" set.

May be useful to explicitly bring this out in the doc ?

Regards,
Bharata.
Dou Liyang Aug. 17, 2016, 11:56 p.m. UTC | #3 
Hi Bharata,

At 08/17/2016 09:47 PM, Bharata B Rao wrote:
> On Wed, Aug 17, 2016 at 03:01:06PM +0800, Dou Liyang wrote:
>> This document describes how to use cpu hotplug in QEMU.
>> +lists all hot-pluggable CPUs. Such as this:
>
> lists all CPUs including the present and possible hot-pluggable CPUs.
>
>> +
>> +  ...
>> +  type: "qemu64-x86_64-cpu"
>> +  vcpus_count: "1"
>> +  CPUInstance Properties:
>> +    socket-id: "1"
>> +    core-id: "0"
>> +    thread-id: "0"
>> +  ...
>> +
>> +Or
>> +
>> +  ...
>> +  type: "POWER7_v2.3-spapr-cpu-core"
>> +  vcpus_count: "1"
>> +  CPUInstance Properties:
>> +    core-id: "2"
>
> There is another property called "qom_path" which if present indicates
> that the listed CPU is already present or plugged-in. Hotpluggable CPUs
> are those which don't have "qom_path" set.
>
> May be useful to explicitly bring this out in the doc ?
>

Yes, it is. I will list it too.

Thanks,
Dou
diff mbox

Patch

diff --git a/docs/cpu-hotplug.txt b/docs/cpu-hotplug.txt
new file mode 100644
index 0000000..c9a16f6
--- /dev/null
+++ b/docs/cpu-hotplug.txt
@@ -0,0 +1,140 @@ 
+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 4,maxcpus=8,sockets=2,cores=2,threads=2
+
+creates a guest with 4 VCPUs and supports up to 8 VCPUs. The CPU topology
+is sockets (2) * cores (2) * threads (2) and should compute a number of
+slots exactly equal to maxcpus. A computed number of slots greater than
+maxcpus will result in error. When the guest finishes loading, the guest
+will see 4 VCPUs. More of this below.
+
+Query available CPU objects
+---------------------------
+
+To add a VCPU, it must be identified by socket-id, core-id, and/or
+thread-id parameters.
+
+Before adding the VCPU, we should know the topology parameters,so
+that we can find the available location (socket,core,thread) for a
+new VCPU.
+
+Use the HMP command "info hotpluggable-cpus" to obtain them, for example:
+
+  (qemu) info hotpluggable-cpus
+
+lists all hot-pluggable CPUs. Such as this:
+
+  ...
+  type: "qemu64-x86_64-cpu"
+  vcpus_count: "1"
+  CPUInstance Properties:
+    socket-id: "1"
+    core-id: "0"
+    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", which
+will be used in hot-plugging below.
+
+Hotplug CPUs
+------------
+
+A monitor command may 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=1,core=0,thread=0):
+
+  (qemu) device_add qemu64-x86_64-cpu,id=cpu1,socket-id=1,core-id=0,thread-id=0
+
+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 from 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 2,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 the "-device" parameter, which are in
+the same socket and core, but with different thread-ids. After that,
+the guest has an additional four VCPUs available for hot-plug when
+needed.
+
+The above example is for an x86 machine type. The topology parameters
+and resulting number of online VCPUs may not be suitable for other
+platforms. The "CPUInstance Properties" output described above lists
+the valid topology parameters.
+
+For example, the following command adds a VCPU in an sPAPR hardware
+system:
+
+  (qemu) device_add POWER7_v2.3-spapr-cpu-core,id=cpu1,core-id=2
+
+CPU hot-unplug
+--------------
+
+In order to be able to hot unplug a CPU device, QEMU removes the
+device by using the id which was assigned when hotplugging it.
+
+A monitor command may 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
+